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
refactor(agent): extract the server tool loop into a steppable, checkpointable module
qhqf0b8558f803ab
diff --git a/api/_lib/agent-loop.js b/api/_lib/agent-loop.jsnew file mode 100644index 000000000..a3a0b247c--- /dev/null+++ b/api/_lib/agent-loop.js@@ -0,0 +1,267 @@+// api/_lib/agent-loop.js: the server-side agent tool loop, one step at a time.+//+// Extracted from api/agent/run.js so the chat completion route and v1 runs+// (api/_lib/agents-v1/runs.js) drive the SAME loop: the LLM is called over the+// shared tool-calling chain (api/_lib/llm-tool-chain.js), every planned tool+// call is preflighted through the GuardChain in headless mode, and allowed+// calls execute from the read-only registry (api/_lib/agent-tools.js).+//+// The loop is expressed as `step(state, context)` over @three-ws/agent-runtime's+// AgentRuntime, whose state and context are plain JSON. A caller that runs the+// loop inline just steps until done; a caller that must survive an instance+// change (a run) persists `{ state, context }` after every step and resumes+// from it anywhere. Nothing in the runner keeps state outside those two+// objects, which is what makes the checkpoint sufficient.++import { AgentRuntime, GuardChain, TradeGuard } from '@three-ws/agent-runtime';+import { streamRound } from './llm-tool-chain.js';+import { costMicroUsd, isFreeLane } from './llm-pricing.js';++const guardChain = new GuardChain({ defiGuard: new TradeGuard() });++export const AGENT_SYSTEM_NOTE = [+ 'You have server-side tools: live token prices and trends, web search, Solana balances, a rug/honeypot safety verdict, smart-money activity, and .sol name resolution.',+ 'Use them instead of guessing; never invent prices, balances, or safety verdicts. If a tool returns no data, say so plainly.',+ 'You cannot move funds: no tool here transfers, swaps, or signs anything.',+].join(' ');++const MAX_TOOL_OUTPUT_CHARS = 20_000;++/** Rough token count for a lane that streams no usage chunk (about 4 chars per token). */+function estimateTokens(value) {+ const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');+ return Math.ceil(text.length / 4);+}++/**+ * Initial `{ state, context }` for a loop over `messages`.+ * @param {{ operationId: string, messages: Array<{role: string, content: any}>, maxSteps: number }} o+ */+export function initialLoopState({ operationId, messages, maxSteps }) {+ const state = AgentRuntime.createInitialState({ operationId, maxSteps });+ state.messages = messages;+ return { state, context: undefined };+}++/** Whether a loop state has reached a terminal status. */+export function loopFinished(state, context) {+ return state.status === 'done' || state.status === 'error' || (!context && state.stepCount > 0);+}++/** The last assistant answer in a loop's transcript. */+export function finalAnswer(state) {+ for (let i = state.messages.length - 1; i >= 0; i--) {+ const m = state.messages[i];+ if (m.role === 'assistant' && !m.tool_calls && typeof m.content === 'string') return m.content;+ }+ return '';+}++/**+ * Build a steppable agent loop.+ *+ * @param {object} o+ * @param {Array<object>} o.chain provider rungs, in failover order+ * @param {Array<object>} o.toolSchemas OpenAI function schemas the model may call+ * @param {Record<string, Function>} o.toolHandlers name → handler(args)+ * @param {number} [o.maxToolRounds] tool rounds before the model must answer+ * @param {number} [o.temperature]+ * @param {(delta: string) => void} [o.onContent] streamed assistant text+ * @param {(event: object) => void|Promise<void>} [o.onEvent] model_call / tool_call / tool_blocked / tool_result+ * @param {(name: string, args: object) => Promise<string|null>} [o.preflight] extra per-call gate; a string blocks with that reason+ */+export function createAgentLoop({+ chain,+ toolSchemas,+ toolHandlers,+ maxToolRounds = 4,+ temperature = 0.4,+ onContent,+ onEvent,+ preflight,+}) {+ const emit = async (event) => {+ if (onEvent) await onEvent(event);+ };++ // One round over the provider chain, failing over BEFORE any byte streams and+ // aborting (not retrying) after a mid-stream death so a listener never sees+ // the same sentence twice.+ async function* modelRuntime(payload) {+ let lastErr = null;+ for (const provider of chain) {+ let emittedHere = false;+ const started = Date.now();+ try {+ const out = await streamRound(provider, {+ messages: payload.messages,+ tools: toolSchemas,+ temperature,+ onContent: (delta) => {+ emittedHere = true;+ onContent?.(delta);+ },+ });+ const model = provider.catalogModel || provider.model;+ const estimated = !out.usage;+ const input = out.usage ? out.usage.input : estimateTokens(payload.messages);+ const output = out.usage ? out.usage.output : estimateTokens(out.content) + estimateTokens(out.toolCalls);+ const cost = costMicroUsd({+ provider: provider.name,+ model,+ input,+ output,+ reportedCostUsd: out.usage?.reportedCostUsd ?? null,+ });+ await emit({+ kind: 'model_call',+ provider: provider.name,+ model,+ free: isFreeLane(provider.name, model),+ content: out.content,+ toolCalls: out.toolCalls.map((tc) => ({ id: tc.id, name: tc.name, args: tc.args })),+ usage: { input, output, estimated },+ costMicroUsd: cost,+ latencyMs: Date.now() - started,+ });+ yield {+ content: out.content,+ tool_calls: out.toolCalls.map((tc) => ({+ id: tc.id,+ type: 'function',+ function: { name: tc.name, arguments: tc.args || '{}' },+ })),+ };+ return;+ } catch (err) {+ lastErr = err;+ if (emittedHere) throw err;+ }+ }+ throw lastErr || new Error('No LLM provider available');+ }++ // Handlers never throw into the runtime: a failing tool becomes an error+ // result the model can read and route around, instead of ending the turn.+ const handlers = {};+ for (const [name, handler] of Object.entries(toolHandlers)) {+ handlers[name] = async (args) => {+ const started = Date.now();+ let result;+ let failed = null;+ try {+ result = await handler(args);+ } catch (err) {+ failed = String(err?.message || err).slice(0, 300);+ result = { error: failed };+ }+ let serialized = JSON.stringify(result ?? null);+ if (serialized.length > MAX_TOOL_OUTPUT_CHARS) {+ result = { truncated: true, preview: serialized.slice(0, MAX_TOOL_OUTPUT_CHARS) };+ serialized = JSON.stringify(result);+ }+ await emit({ kind: 'tool_result', tool: name, args, result, error: failed, latencyMs: Date.now() - started });+ return result;+ };+ }++ const runner = async (context, state) => {+ switch (context.phase) {+ case 'init':+ case 'user_input':+ return { type: 'call_llm', payload: { messages: state.messages } };++ case 'llm_result': {+ const { result, toolCalls } = context.payload || {};+ const content = result?.content || '';+ const roundsUsed = state.messages.filter((m) => m.role === 'assistant' && m.tool_calls).length;++ if (Array.isArray(toolCalls) && toolCalls.length > 0 && roundsUsed < maxToolRounds) {+ state.messages.push({ role: 'assistant', content: content || null, tool_calls: toolCalls });++ const allowed = [];+ for (const tc of toolCalls) {+ const name = tc.function?.name || '';+ let args = {};+ try {+ args = JSON.parse(tc.function?.arguments || '{}');+ } catch {+ args = {};+ }+ const block = async (reason) => {+ state.messages.push({+ role: 'tool',+ tool_call_id: tc.id,+ content: JSON.stringify({ blocked: true, error: reason }),+ });+ await emit({ kind: 'tool_blocked', tool: name, args, reason });+ };+ if (!handlers[name]) {+ await block(`Unknown tool: ${name}`);+ continue;+ }+ const verdict = await guardChain.evaluate({+ identifier: name,+ apiName: name,+ arguments: args,+ approvalMode: 'headless',+ });+ if (verdict.decision === 'block') {+ await block(verdict.reason);+ continue;+ }+ const extra = preflight ? await preflight(name, args) : null;+ if (extra) {+ await block(extra);+ continue;+ }+ await emit({ kind: 'tool_call', tool: name, args });+ allowed.push(tc);+ }++ if (allowed.length > 0) return { type: 'call_tools_batch', payload: allowed };+ // Everything was blocked or unknown: let the model read the errors.+ return { type: 'call_llm', payload: { messages: state.messages } };+ }++ state.messages.push({ role: 'assistant', content });+ return { type: 'finish', reason: 'completed' };+ }++ case 'tool_result':+ case 'tools_batch_result':+ return { type: 'call_llm', payload: { messages: state.messages } };++ case 'error':+ return { type: 'finish', reason: 'error_recovery' };++ default:+ return { type: 'finish', reason: 'agent_decision' };+ }+ };++ const runtime = new AgentRuntime({ runner, modelRuntime, tools: handlers });++ return {+ /**+ * Advance one step. Returns the next `{ state, context }`; the loop is over+ * when `loopFinished(state, context)` holds.+ */+ async step(state, context) {+ const out = await runtime.step(state, context);+ return { state: out.newState, context: out.nextContext };+ },+ };+}++/**+ * Run a loop to completion inline. `shouldContinue` is consulted before every+ * step; returning false stops the loop where it stands.+ */+export async function runLoopToEnd(loop, { state, context }, { shouldContinue } = {}) {+ while (!loopFinished(state, context)) {+ if (shouldContinue && !(await shouldContinue(state))) break;+ ({ state, context } = await loop.step(state, context));+ }+ return { state, context };+}diff --git a/api/_lib/llm-tool-chain.js b/api/_lib/llm-tool-chain.jsindex eb0e58a4a..6b4a7b641 100644--- a/api/_lib/llm-tool-chain.js+++ b/api/_lib/llm-tool-chain.js@@ -10,7 +10,7 @@// handles them all.import { env } from './env.js';-import { DEFAULT_FREE_MODEL } from './chat-models.js';+import { DEFAULT_FREE_MODEL, MODEL_CATALOG } from './chat-models.js';import {vertexGeminiAvailable,vertexGeminiModel,@@ -98,14 +98,19 @@ export function providerChain() {// Stream one chat-completion round. Emits assistant content deltas via// onContent; accumulates streamed tool_calls. Resolves { content, toolCalls }.// Throws on transport / non-2xx so the caller can fail over to the next provider.-export async function streamRound(provider, { messages, tools, onContent }) {+export async function streamRound(provider, { messages, tools, onContent, temperature = 0.4 }) {const body = {model: provider.model,max_tokens: 1024,- temperature: 0.4,+ temperature,stream: true,messages,};+ // Ask for the usage chunk only where the lane is known to accept the+ // option; an unknown field is a 400 on some OpenAI-compatible hosts, and a+ // 400 here would fail the rung over for no reason. Other lanes still get+ // their usage read when they volunteer it.+ if (USAGE_OPTION_LANES.has(baseLane(provider.name))) body.stream_options = { include_usage: true };if (Array.isArray(tools) && tools.length) { body.tools = tools; body.tool_choice = 'auto'; }// Keyless lanes (the Vertex Gemini credits anchor) mint their auth per request// via getHeaders; a token-exchange failure throws here and fails over to the@@ -128,6 +133,7 @@ export async function streamRound(provider, { messages, tools, onContent }) {let buf = '';let content = '';const toolCalls = []; // index → { id, name, args }+ let usage = null;for (;;) {const { value, done } = await reader.read();if (done) break;@@ -141,6 +147,8 @@ export async function streamRound(provider, { messages, tools, onContent }) {if (payload === '[DONE]') { buf = ''; break; }let evt;try { evt = JSON.parse(payload); } catch { continue; }+ const u = evt.usage || evt.x_groq?.usage;+ if (u && typeof u === 'object') usage = readUsage(u);const delta = evt.choices?.[0]?.delta;if (!delta) continue;if (delta.content) { content += delta.content; onContent?.(delta.content); }@@ -155,6 +163,86 @@ export async function streamRound(provider, { messages, tools, onContent }) {}}}- return { content, toolCalls: toolCalls.filter(Boolean) };+ return { content, toolCalls: toolCalls.filter(Boolean), usage };+}++// Lanes documented to accept `stream_options.include_usage` on their+// OpenAI-compatible endpoint.+const USAGE_OPTION_LANES = new Set(['openai', 'groq', 'openrouter', 'cerebras', 'nvidia', 'gemini', 'grok']);++function baseLane(name) {+ return String(name || '').split('#')[0];+}++function readUsage(u) {+ const input = Number(u.prompt_tokens ?? u.input_tokens);+ const output = Number(u.completion_tokens ?? u.output_tokens);+ const cost = Number(u.cost);+ return {+ input: Number.isFinite(input) ? input : 0,+ output: Number.isFinite(output) ? output : 0,+ reportedCostUsd: Number.isFinite(cost) ? cost : null,+ };+}++// OpenAI-compatible chat-completions endpoint per catalog provider. Anthropic+// ids are served through OpenRouter's mirror of the same model, because the+// tool loop speaks one wire format and the platform key for OpenRouter is the+// one that is funded.+const LANE_ENDPOINTS = {+ groq: { url: 'https://api.groq.com/openai/v1/chat/completions', key: () => env.GROQ_API_KEY },+ openrouter: { url: 'https://openrouter.ai/api/v1/chat/completions', key: () => env.OPENROUTER_API_KEY },+ nvidia: { url: 'https://integrate.api.nvidia.com/v1/chat/completions', key: () => env.NVIDIA_API_KEY },+ sambanova: { url: 'https://api.sambanova.ai/v1/chat/completions', key: () => env.SAMBANOVA_API_KEY },+ mistral: { url: 'https://api.mistral.ai/v1/chat/completions', key: () => env.MISTRAL_API_KEY },+ zai: { url: 'https://api.z.ai/api/paas/v4/chat/completions', key: () => env.ZAI_API_KEY },+ openai: { url: 'https://api.openai.com/v1/chat/completions', key: () => env.OPENAI_API_KEY },+ grok: { url: 'https://api.x.ai/v1/chat/completions', key: () => env.GROK_API_KEY },+};++/** The OpenRouter mirror id for a first-party Anthropic id: `claude-haiku-4-5-20251001` → `anthropic/claude-haiku-4.5`. */+export function anthropicMirrorId(model) {+ const bare = String(model).replace(/-\d{8}$/, '');+ return `anthropic/${bare.replace(/-(\d+)-(\d+)$/, '-$1.$2')}`;+}++/**+ * A single tool-loop rung that serves exactly `model`, or null when no+ * configured key can reach it. Used to honor an explicit model choice while+ * the free chain stays behind it as the failover.+ * @param {string} model a MODEL_CATALOG id+ */+export function modelRung(model) {+ const meta = MODEL_CATALOG[model];+ if (!meta || !meta.tools) return null;+ if (meta.provider === 'anthropic') {+ if (!env.OPENROUTER_API_KEY) return null;+ return {+ name: 'openrouter',+ url: LANE_ENDPOINTS.openrouter.url,+ key: env.OPENROUTER_API_KEY,+ model: anthropicMirrorId(model),+ catalogModel: model,+ extraHeaders: { 'HTTP-Referer': 'https://three.ws', 'X-Title': 'three.ws' },+ };+ }+ const lane = LANE_ENDPOINTS[meta.provider];+ const key = lane?.key();+ if (!lane || !key) return null;+ const rung = { name: meta.provider, url: lane.url, key, model, catalogModel: model };+ if (meta.provider === 'openrouter') rung.extraHeaders = { 'HTTP-Referer': 'https://three.ws', 'X-Title': 'three.ws' };+ return rung;+}++/**+ * The provider chain for a request that may name a model: the named model's+ * rung first (when reachable), then the free-first platform chain.+ * @param {string|null} [model]+ */+export function providerChainFor(model) {+ const chain = providerChain();+ if (!model) return chain;+ const rung = modelRung(model);+ return rung ? [rung, ...chain.filter((p) => !(p.name === rung.name && p.model === rung.model))] : chain;}diff --git a/api/agent/run.js b/api/agent/run.jsindex 9fbf5e5f5..61acff62b 100644--- a/api/agent/run.js+++ b/api/agent/run.js@@ -7,7 +7,7 @@// makes the loop a drop-in "model" for the chat client's Built-in lane// (model id `three-ws/agent`), with zero client-side protocol work.//-// Inside one request, @three-ws/agent-runtime's AgentRuntime drives the loop:+// Inside one request, the shared loop in api/_lib/agent-loop.js drives it:// call the LLM over the shared tool-calling chain (api/_lib/llm-tool-chain.js,// free lanes first, Vertex credits anchor last), execute any requested tools// server-side from the READ-ONLY registry (api/_lib/agent-tools.js: web@@ -25,9 +25,15 @@import { cors, error, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';import { limits, clientIp } from '../_lib/rate-limit.js';-import { providerChain, streamRound } from '../_lib/llm-tool-chain.js';+import { providerChain } from '../_lib/llm-tool-chain.js';import { agentToolSchemas, agentToolHandlers } from '../_lib/agent-tools.js';-import { AgentRuntime, GuardChain, TradeGuard } from '@three-ws/agent-runtime';+import {+ AGENT_SYSTEM_NOTE,+ createAgentLoop,+ finalAnswer,+ initialLoopState,+ loopFinished,+} from '../_lib/agent-loop.js';export const AGENT_MODEL_ID = 'three-ws/agent';@@ -35,14 +41,6 @@ const MAX_TOOL_ROUNDS = 4;const MAX_MESSAGES = 40;const MAX_BODY_BYTES = 512_000;-const guardChain = new GuardChain({ defiGuard: new TradeGuard() });--const SYSTEM_NOTE = [- 'You have server-side tools: live token prices and trends, web search, Solana balances, a rug/honeypot safety verdict, smart-money activity, and .sol name resolution.',- 'Use them instead of guessing; never invent prices, balances, or safety verdicts. If a tool returns no data, say so plainly.',- 'You cannot move funds: no tool here transfers, swaps, or signs anything.',-].join(' ');-function sanitizeMessages(raw) {if (!Array.isArray(raw)) return null;const out = [];@@ -98,7 +96,7 @@ export async function runAgentCompletion(req, res, body, opts = {}) {// The server note rides as a second system message so a client-authored// persona keeps the first slot.const sysIdx = messages[0]?.role === 'system' ? 1 : 0;- messages.splice(sysIdx, 0, { role: 'system', content: SYSTEM_NOTE });+ messages.splice(sysIdx, 0, { role: 'system', content: AGENT_SYSTEM_NOTE });const stream = body?.stream !== false;const completionId = `agentrun-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;@@ -116,134 +114,30 @@ export async function runAgentCompletion(req, res, body, opts = {}) {res.write(text);};- const toolSchemas = agentToolSchemas();- const toolHandlers = agentToolHandlers();let streamedAny = false;- let finalContent = '';-- // The model runtime the loop's built-in call_llm executor consumes: one- // round over the provider chain, failing over BEFORE any byte streams and- // aborting (not retrying) after a mid-stream death so the client never sees- // the same sentence twice.- async function* modelRuntime(payload) {- let lastErr = null;- for (const provider of chain) {- let emittedHere = false;- try {- const out = await streamRound(provider, {- messages: payload.messages,- tools: toolSchemas,- onContent: (delta) => {- emittedHere = true;- streamedAny = true;- if (stream) sse(chunkFrame(completionId, { content: delta }));- },- });- yield {- content: out.content,- tool_calls: out.toolCalls.map((tc) => ({- id: tc.id,- type: 'function',- function: { name: tc.name, arguments: tc.args || '{}' },- })),- };- return;- } catch (err) {- lastErr = err;- if (emittedHere) throw err;- }- }- throw lastErr || new Error('No LLM provider available');- }-- // The "brain": plan from the phase the runtime reports. Tool rounds are- // bounded; past the budget the model is asked to answer with what it has.- const runner = async (context, state) => {- switch (context.phase) {- case 'init':- case 'user_input':- return { type: 'call_llm', payload: { messages: state.messages } };-- case 'llm_result': {- const { result, toolCalls } = context.payload || {};- const content = result?.content || '';- const roundsUsed = state.messages.filter((m) => m.role === 'assistant' && m.tool_calls).length;-- if (Array.isArray(toolCalls) && toolCalls.length > 0 && roundsUsed < MAX_TOOL_ROUNDS) {- state.messages.push({ role: 'assistant', content: content || null, tool_calls: toolCalls });-- const allowed = [];- for (const tc of toolCalls) {- const name = tc.function?.name || '';- let args = {};- try {- args = JSON.parse(tc.function?.arguments || '{}');- } catch {- args = {};- }- if (!toolHandlers[name]) {- state.messages.push({- role: 'tool',- tool_call_id: tc.id,- content: JSON.stringify({ error: `Unknown tool: ${name}` }),- });- continue;- }- const verdict = await guardChain.evaluate({- identifier: name,- apiName: name,- arguments: args,- approvalMode: 'headless',- });- if (verdict.decision === 'block') {- state.messages.push({- role: 'tool',- tool_call_id: tc.id,- content: JSON.stringify({ blocked: true, error: verdict.reason }),- });- continue;- }- if (stream) sse(`: tool ${name}\n\n`);- allowed.push(tc);- }-- if (allowed.length > 0) return { type: 'call_tools_batch', payload: allowed };- // Everything was blocked or unknown: let the model read the errors.- return { type: 'call_llm', payload: { messages: state.messages } };- }-- finalContent = content;- state.messages.push({ role: 'assistant', content });- return { type: 'finish', reason: 'completed' };- }-- case 'tool_result':- case 'tools_batch_result':- return { type: 'call_llm', payload: { messages: state.messages } };-- case 'error':- return { type: 'finish', reason: 'error_recovery' };-- default:- return { type: 'finish', reason: 'agent_decision' };- }- };+ const loop = createAgentLoop({+ chain,+ toolSchemas: agentToolSchemas(),+ toolHandlers: agentToolHandlers(),+ maxToolRounds: MAX_TOOL_ROUNDS,+ onContent: (delta) => {+ streamedAny = true;+ if (stream) sse(chunkFrame(completionId, { content: delta }));+ },+ onEvent: (event) => {+ if (stream && event.kind === 'tool_call') sse(`: tool ${event.tool}\n\n`);+ },+ });- const agent = { runner, modelRuntime, tools: toolHandlers };- const runtime = new AgentRuntime(agent);- let state = AgentRuntime.createInitialState({+ let { state, context } = initialLoopState({operationId: completionId,+ messages,maxSteps: MAX_TOOL_ROUNDS * 2 + 3,});- state.messages = messages;- let context;try {- while (state.status !== 'done' && state.status !== 'error') {- const step = await runtime.step(state, context);- state = step.newState;- context = step.nextContext;- if (!context && state.status !== 'done' && state.status !== 'error') break;+ while (!loopFinished(state, context)) {+ ({ state, context } = await loop.step(state, context));}} catch (err) {if (sseOpen) {@@ -254,6 +148,7 @@ export async function runAgentCompletion(req, res, body, opts = {}) {}return error(res, 502, 'agent_loop_failed', String(err?.message || err).slice(0, 300));}+ const finalContent = finalAnswer(state);if (state.status === 'error') {const detail = String(state.error?.message || state.error || 'agent loop error').slice(0, 300);