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(agents): share one agent-turn builder between /api/agents/talk and the paid x402 agent API
nirholas198873423914
diff --git a/api/_lib/agent-turn.js b/api/_lib/agent-turn.jsnew file mode 100644index 000000000..46554db8f--- /dev/null+++ b/api/_lib/agent-turn.js@@ -0,0 +1,188 @@+// One conversational turn with an agent, server-side.+//+// Shared by POST /api/agents/talk (the authenticated, MCP-delegate surface) and+// POST /api/x402/agents/:id (the agent sold as a paid x402 API). Both build the+// same system prompt from the agent's own record: its brain instructions, the+// prompt-only custom skills its owner installed, patronage context for the+// caller's wallet, and which premium skills THIS caller has unlocked. Keeping+// that in one place means a buyer of the paid API talks to exactly the agent+// the owner configured, not a drifted copy of it.++import { sql } from './db.js';+import { normalizeLegacyPolicy } from './embed-policy.js';+import { llmComplete, LlmUnavailableError } from './llm.js';+import { hasSkillAccess } from './skill-access.js';+import { patronChatContext, patronStanding, listPerks, entitledPerks } from './patronage.js';+import { agentSkillsForPrompt } from './agent-custom-skills.js';++export const ALLOWED_MODELS = new Set([+ 'claude-haiku-4-5-20251001',+ 'claude-sonnet-4-5',+ 'claude-sonnet-4-6',+ 'claude-sonnet-5',+ 'claude-opus-4-7',+ 'claude-opus-5',+]);++const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';++// Build the agent's skill_ownership context for one requesting user. Every skill+// the agent declares is classified as premium (priced + active in+// agent_skill_prices) or free; for premium skills we resolve the caller's real+// access via hasSkillAccess (purchase / subscription / trial). Anonymous callers+// (userId === null) own no premium skill. Returns a compact, structured prompt+// section, or null when the agent has no skills worth describing.+export async function buildSkillOwnershipBlock(agent, userId, patronSkills = new Set()) {+ const skills = Array.isArray(agent.skills) ? agent.skills.filter(Boolean) : [];+ if (skills.length === 0) return null;++ // One query for all of this agent's active prices, then classify in memory,+ // avoiding a per-skill price lookup. hasSkillAccess re-checks the price row,+ // but only for skills we already know are premium.+ const priceRows = await sql`+ SELECT skill FROM agent_skill_prices+ WHERE agent_id = ${agent.id} AND is_active = true+ `;+ const pricedSkills = new Set(priceRows.map((r) => r.skill));++ const ownership = {};+ for (const skill of skills) {+ if (!pricedSkills.has(skill)) {+ ownership[skill] = { is_premium: false, is_owned: true };+ continue;+ }+ // A patron whose verified on-chain support clears a skill-perk threshold uses+ // that premium skill for free, the same gate the Support surface advertises.+ if (patronSkills.has(skill)) {+ ownership[skill] = { is_premium: true, is_owned: true, via_patron: true };+ continue;+ }+ if (!userId) {+ ownership[skill] = { is_premium: true, is_owned: false };+ continue;+ }+ const access = await hasSkillAccess(userId, agent.id, skill);+ ownership[skill] = { is_premium: true, is_owned: Boolean(access.owned) };+ }++ const hasPremium = Object.values(ownership).some((o) => o.is_premium);+ if (!hasPremium) return null; // nothing to monetize, keep the prompt lean.++ return [+ '## Skill access (current user)',+ 'The JSON below maps each of your skills to whether it is premium (paid) and whether THIS user has already unlocked it:',+ JSON.stringify(ownership),+ 'Behaviour rules:',+ '- Use any skill where is_owned is true freely, without mentioning payment.',+ '- If the user asks to use a skill where is_premium is true and is_owned is false, do NOT perform it. Politely explain it is a paid skill and invite them to unlock it from your agent profile page, then offer the free skills you can do instead.',+ "- Never invent prices, never reveal another user's access, and never claim a skill is unlocked when is_owned is false.",+ ].join('\n');+}++/**+ * The model a turn runs on: a requested model only when it is on the allowlist,+ * otherwise the agent's own brain model.+ */+export function resolveTurnModel(agent, requestedModel = null) {+ const policy = normalizeLegacyPolicy(agent.embed_policy);+ const defaultModel = policy?.brain?.model || DEFAULT_MODEL;+ return requestedModel && ALLOWED_MODELS.has(requestedModel) ? requestedModel : defaultModel;+}++/**+ * The full system prompt for one caller. `callerWallet` drives patronage (the+ * caller's standing is derived from chain truth for that wallet); `userId`+ * drives premium-skill ownership. Both are optional: an anonymous caller gets+ * the agent's persona with no unlocked premium skills.+ */+export async function buildAgentSystemPrompt(agent, { userId = null, callerWallet = null } = {}) {+ const basePrompt =+ agent.meta?.brain?.instructions || `You are ${agent.name}. ${agent.description || ''}`.trim();++ const patronSkills = new Set();+ if (callerWallet) {+ try {+ const [standing, perks] = await Promise.all([+ patronStanding(agent.id, callerWallet),+ listPerks(agent.id, { activeOnly: true }),+ ]);+ for (const p of entitledPerks(perks, standing.usd)) {+ if (p.perkType === 'skill' && p.payload?.skill) patronSkills.add(p.payload.skill);+ }+ } catch (err) {+ // Patronage is enrichment: a lookup failure never blocks the reply.+ console.warn('[agent-turn] patron standing unavailable', err?.message || err);+ }+ }+ const patronBlock = callerWallet+ ? await patronChatContext(agent.id, callerWallet).catch(() => null)+ : null;++ const ownershipBlock = await buildSkillOwnershipBlock(agent, userId, patronSkills);+ // The agent's own prompt-only custom skills (api/_lib/agent-custom-skills.js):+ // same install order and budget as /api/chat. Enrichment, never a failed reply.+ const { block: agentSkillsBlock } = await agentSkillsForPrompt(agent.id).catch(() => ({ block: '' }));+ return [basePrompt, agentSkillsBlock, patronBlock, ownershipBlock].filter(Boolean).join('\n\n');+}++// Prior turns are folded into the user message as a transcript: the LLM chain+// behind llmComplete is single-turn (system + user) across every provider rung,+// so this is the one shape every rung understands.+export function composeUserMessage(message, history = []) {+ if (!Array.isArray(history) || history.length === 0) return message;+ const lines = history.map((h) => `${h.role === 'assistant' ? 'Assistant' : 'User'}: ${h.content}`);+ return [+ 'Conversation so far:',+ ...lines,+ '',+ "Reply to the user's latest message:",+ message,+ ].join('\n');+}++/** A turn that could not produce a reply. `status` / `code` map to the HTTP answer. */+export class AgentTurnError extends Error {+ constructor(status, code, message) {+ super(message);+ this.name = 'AgentTurnError';+ this.status = status;+ this.code = code;+ }+}++/**+ * Run one turn. Resolves `{ text, model, usage }`; rejects with AgentTurnError+ * (503 llm_unavailable when every provider rung is down, 502 upstream_error on+ * any other LLM failure). Nothing here charges anyone: a paid caller settles+ * only after this resolves.+ */+export async function runAgentTurn({+ agent,+ message,+ history = [],+ userId = null,+ callerWallet = null,+ requestedModel = null,+ tool = 'agent.talk',+ maxTokens = 1024,+}) {+ const model = resolveTurnModel(agent, requestedModel);+ const system = await buildAgentSystemPrompt(agent, { userId, callerWallet });+ try {+ const result = await llmComplete({+ system,+ user: composeUserMessage(message, history),+ maxTokens,+ // Free providers serve first; if every one fails, the paid backstop uses+ // the agent's chosen Claude model on the platform key.+ anthropicModel: model,+ track: { agentId: agent.id, tool },+ });+ return { text: result.text, model: result.model, usage: result.usage ?? null };+ } catch (err) {+ if (err instanceof LlmUnavailableError) {+ throw new AgentTurnError(503, 'llm_unavailable', 'the agent cannot answer right now, every model provider is unavailable');+ }+ throw new AgentTurnError(502, 'upstream_error', `LLM call failed: ${err.message}`);+ }+}diff --git a/api/agents/talk.js b/api/agents/talk.jsindex 03f543e67..23b030f5d 100644--- a/api/agents/talk.js+++ b/api/agents/talk.js@@ -21,20 +21,8 @@ import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';import { limits, clientIp } from '../_lib/rate-limit.js';import { normalizeLegacyPolicy } from '../_lib/embed-policy.js';-import { llmComplete, LlmUnavailableError } from '../_lib/llm.js';-import { hasSkillAccess } from '../_lib/skill-access.js';import { isUuid } from '../_lib/validate.js';-import { patronChatContext, patronStanding, listPerks, entitledPerks } from '../_lib/patronage.js';-import { agentSkillsForPrompt } from '../_lib/agent-custom-skills.js';--const ALLOWED_MODELS = new Set([- 'claude-haiku-4-5-20251001',- 'claude-sonnet-4-5',- 'claude-sonnet-4-6',- 'claude-sonnet-5',- 'claude-opus-4-7',- 'claude-opus-5',-]);+import { runAgentTurn, AgentTurnError } from '../_lib/agent-turn.js';const bodySchema = z.object({agentId: z.string().min(1).max(120),@@ -42,59 +30,6 @@ const bodySchema = z.object({model: z.string().min(1).max(100).optional(),});-// Build the agent's skill_ownership context for one requesting user. Every skill-// the agent declares is classified as premium (priced + active in-// agent_skill_prices) or free; for premium skills we resolve the caller's real-// access via hasSkillAccess (purchase / subscription / trial). Anonymous callers-// (userId === null) own no premium skill. Returns a compact, structured prompt-// section, or null when the agent has no skills worth describing.-async function buildSkillOwnershipBlock(agent, userId, patronSkills = new Set()) {- const skills = Array.isArray(agent.skills) ? agent.skills.filter(Boolean) : [];- if (skills.length === 0) return null;-- // One query for all of this agent's active prices, then classify in memory —- // avoids a per-skill price lookup. hasSkillAccess re-checks the price row, but- // only for skills we already know are premium.- const priceRows = await sql`- SELECT skill FROM agent_skill_prices- WHERE agent_id = ${agent.id} AND is_active = true- `;- const pricedSkills = new Set(priceRows.map((r) => r.skill));-- const ownership = {};- for (const skill of skills) {- if (!pricedSkills.has(skill)) {- ownership[skill] = { is_premium: false, is_owned: true };- continue;- }- // A patron whose verified on-chain support clears a skill-perk threshold uses- // that premium skill for free — the same gate the Support surface advertises.- if (patronSkills.has(skill)) {- ownership[skill] = { is_premium: true, is_owned: true, via_patron: true };- continue;- }- if (!userId) {- ownership[skill] = { is_premium: true, is_owned: false };- continue;- }- const access = await hasSkillAccess(userId, agent.id, skill);- ownership[skill] = { is_premium: true, is_owned: Boolean(access.owned) };- }-- const hasPremium = Object.values(ownership).some((o) => o.is_premium);- if (!hasPremium) return null; // nothing to monetize — keep the prompt lean.-- return [- '## Skill access (current user)',- 'The JSON below maps each of your skills to whether it is premium (paid) and whether THIS user has already unlocked it:',- JSON.stringify(ownership),- 'Behaviour rules:',- '- Use any skill where is_owned is true freely, without mentioning payment.',- '- If the user asks to use a skill where is_premium is true and is_owned is false, do NOT perform it. Politely explain it is a paid skill and invite them to unlock it from your agent profile page, then offer the free skills you can do instead.',- '- Never invent prices, never reveal another user\'s access, and never claim a skill is unlocked when is_owned is false.',- ].join('\n');-}-export default wrap(async (req, res) => {if (cors(req, res, { methods: 'POST,OPTIONS', credentials: false })) return;if (!method(req, res, ['POST'])) return;@@ -146,64 +81,26 @@ export default wrap(async (req, res) => {return error(res, 403, 'mcp_disabled', 'this agent has opted out of MCP delegation');}- const defaultModel = policy?.brain?.model || 'claude-haiku-4-5-20251001';- const model =- requestedModel && ALLOWED_MODELS.has(requestedModel) ? requestedModel : defaultModel;-- const basePrompt =- agent.meta?.brain?.instructions ||- `You are ${agent.name}. ${agent.description || ''}`.trim();-- // Patronage: recognize the caller as a real on-chain patron (greet them by name,- // reference the relationship) and free any premium skill their support has earned.- // The caller's identity is their linked wallet; standing derives from chain truth.- const callerWallet = session?.wallet_address || null;- const patronSkills = new Set();- if (callerWallet) {- try {- const [standing, perks] = await Promise.all([- patronStanding(agent.id, callerWallet),- listPerks(agent.id, { activeOnly: true }),- ]);- for (const p of entitledPerks(perks, standing.usd)) {- if (p.perkType === 'skill' && p.payload?.skill) patronSkills.add(p.payload.skill);- }- } catch { /* patronage is enrichment — never block the reply */ }- }- const patronBlock = await patronChatContext(agent.id, callerWallet).catch(() => null);-- // Real per-user skill-ownership context: lets the agent know which of its- // skills are premium and whether THIS caller has already unlocked them, so it- // can use owned skills freely and offer to sell the ones the user lacks.- const ownershipBlock = await buildSkillOwnershipBlock(agent, userId, patronSkills);- // The agent's own prompt-only custom skills (api/_lib/agent-custom-skills.js):- // same install order and budget as /api/chat, so an agent reached over MCP- // follows the skills its owner installed. Enrichment, never a failed reply.- const { block: agentSkillsBlock } = await agentSkillsForPrompt(agent.id).catch(() => ({ block: '' }));- const systemPrompt = [basePrompt, agentSkillsBlock, patronBlock, ownershipBlock].filter(Boolean).join('\n\n');-+ // The turn itself (persona, custom skills, patronage, premium-skill access,+ // the LLM failover chain) is shared with the paid agent API in+ // api/_lib/agent-turn.js so both surfaces answer as the same agent.const started = Date.now();let result;try {- result = await llmComplete({- system: systemPrompt,- user: message,- maxTokens: 1024,- // Free providers serve first; if every one fails, the paid backstop- // uses the agent's chosen Claude model on the platform key.- anthropicModel: model,- track: { agentId: agent.id, tool: 'agent.talk' },+ result = await runAgentTurn({+ agent,+ message,+ userId,+ callerWallet: session?.wallet_address || null,+ requestedModel,+ tool: 'agent.talk',});} catch (err) {- if (err instanceof LlmUnavailableError) {- return error(- res,- 503,- 'llm_unavailable',- 'agent delegation is not available right now',- );+ if (err instanceof AgentTurnError && err.code === 'llm_unavailable') {+ return error(res, 503, 'llm_unavailable', 'agent delegation is not available right now');}- return error(res, 502, 'upstream_error', `LLM call failed: ${err.message}`);+ if (err instanceof AgentTurnError) return error(res, err.status, err.code, err.message);+ throw err;}return json(res, 200, {