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
// /api/agents/:id/copilot — the Conversational Trading Copilot.
//
// A tool-calling LLM that talks to the agent's owner (text or voice), answers
// with REAL live market + portfolio data, and PROPOSES trades the owner must
// confirm. The model never signs and never executes: read-only tools run
// server-side and feed grounded numbers back to the model; any state-changing
// intent (buy / sell / risk-limits) is returned to the client as a structured
// proposal. The client re-quotes it live and, only on the owner's confirmation,
// calls the existing guarded endpoints (POST /api/agents/:id/solana/trade,
// PUT /api/agents/:id/trade/limits) — which enforce the spend guards
// (api/_lib/agent-trade-guards.js), the rug/honeypot firewall
// (api/_lib/trade-firewall.js), and the custody audit (agent_custody_events).
// Conversation can never bypass a guard, the kill switch, or a spend cap.
//
// POST /api/agents/:id/copilot { messages:[{role,content}], network, model? } → SSE
// `model` overrides the agent's default model for this message
// (api/_lib/agent-model.js). The copilot is a tool loop, so an override
// without tool calling is refused; an agent default without tools
// answers on the platform chain. A free open model draws on the owner's
// daily free-tier allowance (api/_lib/free-tier.js).
// GET /api/agents/:id/copilot?after=<message id>&limit=<1-100>
// → { messages:[{id,role,content,channel,createdAt}], latest_id }
// the agent's cross-channel thread, oldest first, so the web panel can
// show what the owner said to the agent from a paired chat (tagged
// "via Telegram" and so on) and carry it into the next web turn.
//
// SSE events: `status` (phase), `tool` (a read-only tool ran), `proposal`
// (a confirm-before-execute trade/limits card), `chunk` (streamed narration
// tokens), `done` (final reply + proposals + citations), `error`.
//
// The tools, prompt and loop live in api/_lib/copilot-engine.js, shared with the
// Telegram and Discord gateways (api/_lib/gateway/). Each finished web turn is
// appended to the agent's cross-channel thread (api/_lib/agent-thread.js) with
// channel `web`, so a conversation started here continues in chat and back.
//
// $THREE (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump) is the only coin three.ws
// promotes. The copilot trades whatever mint the owner names at runtime — generic
// coin-agnostic plumbing — and never names or recommends any other token.
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { sql } from '../_lib/db.js';
import { cors, method, error, json, readJson, rateLimited } from '../_lib/http.js';
import { limits } from '../_lib/rate-limit.js';
import { providerChain } from '../_lib/llm-tool-chain.js';
import { runCopilotTurn, netOf, COPILOT_MAX_MESSAGES } from '../_lib/copilot-engine.js';
import { appendThreadMessage, listThread } from '../_lib/agent-thread.js';
import { ModelChoiceError } from '../_lib/agent-model.js';
import { resolveAgentBrain, brainBadge } from '../_lib/agent-brain.js';
import { meterFreeModel, FreeTierExhaustedError, freeTierErrorBody, retryAfterSeconds } from '../_lib/free-tier.js';
import { assertInferenceAllowed, chargeInference } from '../_lib/inference-billing.js';
import { randomUUID } from 'node:crypto';
import { recordEvent } from '../_lib/usage.js';
import { costMicroUsd } from '../_lib/llm-pricing.js';
export { providerChain };
// ── auth / ownership ──────────────────────────────────────────────────────────
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id };
const bearer = await authenticateBearer(extractBearer(req));
if (bearer) return { userId: bearer.userId };
return null;
}
// ── handler ─────────────────────────────────────────────────────────────────────
export default async function handler(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in to talk to this copilot');
const rl = await limits.tradePerUser(auth.userId).catch(() => ({ success: true }));
if (rl && rl.success === false) return rateLimited(res, rl);
const [row] = await sql`SELECT id, user_id, name, persona_prompt, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'only the owner can use this copilot');
if (req.method === 'GET') return sendThread(req, res, { agentId: row.id, userId: auth.userId });
const body = await readJson(req).catch(() => null);
const network = netOf(body?.network);
const rawMessages = Array.isArray(body?.messages) ? body.messages : [];
const history = rawMessages
.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && typeof m.content === 'string' && m.content.trim())
.slice(-COPILOT_MAX_MESSAGES)
.map((m) => ({ role: m.role, content: m.content.slice(0, 4000) }));
if (!history.length || history[history.length - 1].role !== 'user') {
return error(res, 422, 'no_message', 'send at least one user message');
}
const override = typeof body?.model === 'string' && body.model.trim() ? body.model.trim().slice(0, 80) : null;
let choice;
try {
choice = await resolveAgentBrain({ agent: row, requested: override, purpose: 'run', lenient: true });
} catch (e) {
if (e instanceof ModelChoiceError) return error(res, e.status, e.code, e.message);
throw e;
}
// `paid_fallback: true` is the owner's one-step approval of the paid route:
// skip the free tier, gate on credits, and bill each model round to them.
const paidFallback = body?.paid_fallback === true;
if (paidFallback) {
try {
await assertInferenceAllowed({ userId: auth.userId, agent: row });
} catch (e) {
if (!(e.status >= 400 && e.status < 500)) throw e;
return error(res, e.status, e.code, e.message);
}
} else {
try {
await meterFreeModel(choice.model, { userId: auth.userId });
} catch (e) {
if (!(e instanceof FreeTierExhaustedError)) throw e;
res.setHeader('Retry-After', String(retryAfterSeconds(e.resetAt)));
return error(res, 429, 'free_tier_exhausted', e.message, freeTierErrorBody(e, {
signedIn: true,
paidFallback: { method: 'POST', path: `/api/agents/${row.id}/copilot` },
}));
}
}
const { chain } = choice;
if (!chain.length) return error(res, 503, 'llm_unavailable', 'No LLM provider configured. Set GROQ_API_KEY, OPENROUTER_API_KEY, or NVIDIA_API_KEY (or GOOGLE_CLOUD_PROJECT for the Vertex credits anchor).');
// SSE open.
res.writeHead(200, {
'Content-Type': 'text/event-stream; charset=utf-8',
'Cache-Control': 'no-cache, no-transform',
Connection: 'keep-alive',
'X-Accel-Buffering': 'no',
});
res.flushHeaders?.();
let active = true;
req.on('close', () => { active = false; });
const send = (event, data) => { if (active) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); };
// Keepalive: a tool-loop round can sit silent for tens of seconds waiting on a
// slow provider (or a mid-round failover to the next one). Emit an SSE comment
// every 15s so the client's stall watchdog can stay tight and only fire on a
// genuinely dead connection, never on a model that's just thinking.
const heartbeat = setInterval(() => { if (active) res.write(': ping\n\n'); }, 15_000);
send('model', { model: choice.model, source: choice.source });
try {
const turn = await runCopilotTurn({
agent: row,
history,
network,
chain,
isActive: () => active,
onRound: (served) => {
send('model', { model: choice.model, source: choice.source, served: served.catalogModel || served.model, lane: served.provider, ...brainBadge(choice, served) });
meterRound({ userId: auth.userId, agentId: id, served });
if (paidFallback && served.usage) {
void chargeInference({
userId: auth.userId,
agentId: id,
callId: randomUUID(),
inputTokens: served.usage.input,
outputTokens: served.usage.output,
provider: served.provider,
model: served.model,
}).catch((err) => console.warn('[copilot] paid fallback charge failed', err?.message));
}
},
// tool_start is for surfaces that paint a live status line (the chat
// gateways); the web UI already paints each finished read as a card.
emit: (event, data) => { if (event !== 'tool_start') send(event, data); },
});
send('done', { reply: turn.reply, proposals: turn.proposals, citations: turn.citations });
await persistWebTurn({ agentId: id, userId: auth.userId, userText: history[history.length - 1].content, turn });
} catch (e) {
send('error', { code: e?.code || 'copilot_error', message: e?.message || 'The copilot hit an error. Try again.' });
} finally {
clearInterval(heartbeat);
if (active) res.end();
}
}
// The thread since `after` (a message id), oldest first. Without `after` it is
// the most recent page, which is what a panel opening for the first time shows.
async function sendThread(req, res, { agentId, userId }) {
const q = new URL(req.url, 'http://x').searchParams;
const after = /^\d{1,18}$/.test(q.get('after') || '') ? Number(q.get('after')) : null;
const limit = Math.max(1, Math.min(100, Number(q.get('limit')) || 30));
const { messages } = await listThread({ agentId, userId, limit });
const rows = messages.filter((m) => after == null || m.id > after).reverse();
const latestId = messages.length ? messages[0].id : after;
return json(res, 200, {
messages: rows.map((m) => ({ id: m.id, role: m.role, content: m.content, channel: m.channel, signatures: m.signatures, createdAt: m.createdAt })),
latest_id: latestId ?? null,
}, { 'cache-control': 'no-store' });
}
// Every model round is recorded against the owner, priced at the lane that
// served it (free lanes cost 0), the same ledger /brain and the runs write.
function meterRound({ userId, agentId, served }) {
if (!served.usage) return;
recordEvent({
userId,
agentId,
kind: 'llm',
tool: 'agent.copilot',
provider: served.provider,
model: served.model,
inputTokens: served.usage.input,
outputTokens: served.usage.output,
costMicroUsd: costMicroUsd({
provider: served.provider,
model: served.model,
input: served.usage.input,
output: served.usage.output,
reportedCostUsd: served.usage.reportedCostUsd,
}),
});
}
// Append the finished web turn to the agent's cross-channel thread, so Telegram
// and Discord continue the same conversation. Best-effort: the owner already has
// the reply, and a thread write must never turn a good answer into an error.
async function persistWebTurn({ agentId, userId, userText, turn }) {
if (!turn.reply) return;
try {
await appendThreadMessage({ agentId, userId, role: 'user', content: userText, channel: 'web' });
await appendThreadMessage({ agentId, userId, role: 'assistant', content: turn.reply, channel: 'web', toolCalls: turn.toolCalls });
} catch (e) {
console.warn('[copilot] thread append failed', e?.message);
}
}