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
// Daily free-tier allowance for the free open models.
//
// A model the roster marks `free` (api/_lib/model-roster.js) costs the caller
// nothing per message, but every message on it draws one unit from a daily
// allowance. The allowance lives in app_settings['free_tier'] so it can be
// changed without a deploy:
//
// { "daily_messages": 100, "anon_daily_messages": 20 }
//
// A signed-in account is metered by user id, an anonymous caller by a hash of
// its IP. Every day resets at 00:00 UTC. When the allowance is spent, consume
// throws FreeTierExhaustedError carrying the reset time; every surface turns
// that into the same 429 `free_tier_exhausted` body (freeTierErrorBody) so a
// client parses one shape wherever it sends a message.
//
// Paid models never touch this module: they are gated to signed-in callers and
// metered in llm-pricing.js.
import { createHash } from 'node:crypto';
import { sql } from './db.js';
import { isFreeTierModel } from './chat-models.js';
export const FREE_TIER_SETTINGS_KEY = 'free_tier';
// Used only when the settings row is missing (a database the migration has
// not reached). The migration seeds the same numbers.
export const DEFAULT_FREE_TIER = Object.freeze({ daily_messages: 100, anon_daily_messages: 20 });
const SETTINGS_TTL_MS = 60_000;
const RETENTION_DAYS = 90;
let settingsCache = { value: null, at: 0 };
let lastPruneDay = null;
/** A free-tier allowance that is spent for today. */
export class FreeTierExhaustedError extends Error {
/** @param {{ limit: number, used: number, resetAt: string, model: string|null }} info */
constructor(info) {
super(
`You have used all ${info.limit} free messages for today. The allowance resets at ${info.resetAt}. ` +
'Sign in for a larger allowance, or pick a paid model to keep going.',
);
this.name = 'FreeTierExhaustedError';
this.status = 429;
this.code = 'free_tier_exhausted';
this.limit = info.limit;
this.used = info.used;
this.resetAt = info.resetAt;
this.model = info.model;
}
}
function cleanCount(v, fallback) {
const n = Number(v);
return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
}
/** Normalize a stored settings value into { daily_messages, anon_daily_messages }. */
export function normalizeFreeTierSettings(value) {
const v = value && typeof value === 'object' ? value : {};
return {
daily_messages: cleanCount(v.daily_messages, DEFAULT_FREE_TIER.daily_messages),
anon_daily_messages: cleanCount(v.anon_daily_messages, DEFAULT_FREE_TIER.anon_daily_messages),
};
}
/** The live allowance, read from app_settings and cached for a minute. */
export async function getFreeTierSettings() {
if (settingsCache.value && Date.now() - settingsCache.at < SETTINGS_TTL_MS) return settingsCache.value;
const [row] = await sql`SELECT value FROM app_settings WHERE key = ${FREE_TIER_SETTINGS_KEY}`;
const value = normalizeFreeTierSettings(row?.value);
settingsCache = { value, at: Date.now() };
return value;
}
/** Test seam: forget the cached settings. */
export function resetFreeTierSettingsCache() {
settingsCache = { value: null, at: 0 };
}
/** The UTC calendar day `now` falls in, as YYYY-MM-DD. */
export function utcDay(now = new Date()) {
return now.toISOString().slice(0, 10);
}
/** The instant the current UTC day ends, as an ISO string. */
export function nextResetAt(now = new Date()) {
const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
return d.toISOString();
}
/**
* The metering subject for a caller: the account when signed in, otherwise a
* truncated SHA-256 of the IP (the raw address is never stored).
* @param {{ userId?: string|null, ip?: string|null }} who
*/
export function freeTierSubject({ userId = null, ip = null } = {}) {
if (userId) return { subject: `user:${userId}`, anonymous: false };
const hash = createHash('sha256').update(String(ip || 'unknown')).digest('hex').slice(0, 32);
return { subject: `ip:${hash}`, anonymous: true };
}
function limitFor(settings, anonymous) {
return anonymous ? settings.anon_daily_messages : settings.daily_messages;
}
/**
* Today's allowance for a caller without consuming anything.
* @param {{ userId?: string|null, ip?: string|null }} who
*/
export async function getFreeTierStatus(who) {
const settings = await getFreeTierSettings();
const { subject, anonymous } = freeTierSubject(who);
const day = utcDay();
const [row] = await sql`SELECT used FROM free_tier_usage WHERE subject = ${subject} AND day = ${day}`;
const limit = limitFor(settings, anonymous);
const used = Math.min(Number(row?.used || 0), limit);
return {
limit,
used,
remaining: Math.max(0, limit - used),
resetAt: nextResetAt(),
anonymous,
signedInLimit: settings.daily_messages,
};
}
/**
* Draw one message from the caller's allowance. Atomic: the increment only
* lands while `used` is under the limit, so concurrent requests can never
* overshoot it. Throws FreeTierExhaustedError when nothing is left.
* @param {{ userId?: string|null, ip?: string|null, model?: string|null }} who
* @returns {Promise<{ limit: number, used: number, remaining: number, resetAt: string }>}
*/
export async function consumeFreeMessage({ userId = null, ip = null, model = null } = {}) {
const settings = await getFreeTierSettings();
const { subject, anonymous } = freeTierSubject({ userId, ip });
const limit = limitFor(settings, anonymous);
const day = utcDay();
const resetAt = nextResetAt();
if (limit <= 0) throw new FreeTierExhaustedError({ limit, used: 0, resetAt, model });
const rows = await sql`
INSERT INTO free_tier_usage (subject, day, used)
VALUES (${subject}, ${day}, 1)
ON CONFLICT (subject, day) DO UPDATE
SET used = free_tier_usage.used + 1, updated_at = now()
WHERE free_tier_usage.used < ${limit}
RETURNING used
`;
if (!rows.length) throw new FreeTierExhaustedError({ limit, used: limit, resetAt, model });
pruneOldUsage(day);
const used = Number(rows[0].used);
return { limit, used, remaining: Math.max(0, limit - used), resetAt };
}
// Retention runs at most once per instance per day and never blocks the
// request that triggered it.
function pruneOldUsage(day) {
if (lastPruneDay === day) return;
lastPruneDay = day;
sql`DELETE FROM free_tier_usage WHERE day < (now() AT TIME ZONE 'utc')::date - ${RETENTION_DAYS}::int`.catch((err) =>
console.warn(`[free-tier] prune failed: ${err?.message || err}`),
);
}
/**
* Consume an allowance unit only when the model is a free-tier model. Paid and
* unknown models pass through untouched (null).
* @param {string|null|undefined} model
* @param {{ userId?: string|null, ip?: string|null }} who
*/
export async function meterFreeModel(model, who) {
if (!model || !isFreeTierModel(model)) return null;
return consumeFreeMessage({ ...who, model });
}
const CREDITS_URL = 'https://three.ws/credits';
const BYOK_DOCS_URL = 'https://three.ws/docs/inference-billing#bring-your-own-key';
/**
* The ways out of a spent allowance, in the order a client should offer them.
* Every choice is machine-actionable: `wait` carries the reset instant,
* `top_up` and `bring_your_own_key` carry the exact calls, and `paid_fallback`
* (present when the surface supports it) is the SAME request with
* `paid_fallback: true` merged into its body, which skips the free tier and
* bills the call to credits in one step. `requires_sign_in` marks the choices
* an anonymous caller must sign in for.
* @param {FreeTierExhaustedError} err
* @param {{ signedIn?: boolean, paidFallback?: { method: string, path: string }|null }} [ctx]
*/
export function freeTierChoices(err, { signedIn = false, paidFallback = null } = {}) {
const choices = [
{
action: 'wait',
description: 'Retry after the daily allowance resets.',
reset_at: err.resetAt,
retry_after_seconds: retryAfterSeconds(err.resetAt),
},
{
action: 'top_up',
description: 'Add prepaid credits, then resend with paid_fallback: true.',
url: CREDITS_URL,
catalog: { method: 'GET', path: '/api/credits' },
deposit: {
method: 'POST',
path: '/api/credits/deposit',
body: { asset: '<SOL|USDC|THREE>', tx_signature: '<signature>' },
},
requires_sign_in: !signedIn,
},
{
action: 'bring_your_own_key',
description: 'Store your own provider key; calls on it are billed by that provider, not metered here.',
url: BYOK_DOCS_URL,
set_key: { method: 'PATCH', path: '/api/user/provider-keys', body: { '<provider>': '<key>' } },
requires_sign_in: !signedIn,
},
];
if (paidFallback?.method && paidFallback?.path) {
choices.push({
action: 'paid_fallback',
description: 'Resend this request with body_patch merged in to bill it to credits now.',
method: paidFallback.method,
path: paidFallback.path,
body_patch: { paid_fallback: true },
bills: 'credits',
requires_sign_in: !signedIn,
});
}
return choices;
}
/**
* The one JSON body every surface answers an exhausted allowance with. `ctx`
* (see freeTierChoices) tells the body which choices this surface can honor.
*/
export function freeTierErrorBody(err, ctx = {}) {
return {
error: 'free_tier_exhausted',
error_description: err.message,
message: err.message,
limit: err.limit,
used: err.used,
reset_at: err.resetAt,
retry_after_seconds: retryAfterSeconds(err.resetAt),
model: err.model || null,
choices: freeTierChoices(err, ctx),
};
}
/** Seconds until the allowance resets, for a Retry-After header. */
export function retryAfterSeconds(resetAt) {
return Math.max(1, Math.ceil((Date.parse(resetAt) - Date.now()) / 1000));
}