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
// Skill runtime — server-side dispatcher for in-process skill invocation.
//
// Skills under examples/skills/<name>/handlers.js export tool functions.
// This module gives them the `ctx` they expect:
// ctx.skills.invoke('skill.tool', args) → call sibling skill
// ctx.skillConfig → manifest.config merged with overrides
// ctx.memory.note(tag, value) → no-op stub (DB persistence is opt-in)
// ctx.fetch → globalThis.fetch (overridable in tests)
// ctx.wallet → injected by callers that need signing
//
// Cold-start friendly: skill modules are imported lazily on first use.
const SKILL_MAP = {
'pump-fun': '../../examples/skills/pump-fun/handlers.js',
'pump-fun-trade': '../../examples/skills/pump-fun-trade/handlers.js',
'pump-fun-compose': '../../examples/skills/pump-fun-compose/handlers.js',
'pump-fun-strategy': '../../examples/skills/pump-fun-strategy/handlers.js',
'solana-wallet': '../../examples/skills/solana-wallet/handlers.js',
};
const MANIFEST_MAP = {
'pump-fun': '../../examples/skills/pump-fun/manifest.json',
'pump-fun-trade': '../../examples/skills/pump-fun-trade/manifest.json',
'pump-fun-compose': '../../examples/skills/pump-fun-compose/manifest.json',
'pump-fun-strategy': '../../examples/skills/pump-fun-strategy/manifest.json',
'solana-wallet': '../../examples/skills/solana-wallet/manifest.json',
};
const _modCache = new Map();
const _cfgCache = new Map();
async function loadSkill(name) {
if (_modCache.has(name)) return _modCache.get(name);
const path = SKILL_MAP[name];
if (!path) throw new Error(`unknown skill: ${name}`);
const mod = await import(path);
_modCache.set(name, mod);
return mod;
}
async function loadManifest(name) {
if (_cfgCache.has(name)) return _cfgCache.get(name);
const path = MANIFEST_MAP[name];
if (!path) return {};
try {
const mod = await import(path, { with: { type: 'json' } });
_cfgCache.set(name, mod.default ?? mod);
return mod.default ?? mod;
} catch {
_cfgCache.set(name, {});
return {};
}
}
// ── Server-side fetch for isomorphic skills ────────────────────────────────
// Skill handlers are shared with the browser, where a relative `/api/...` URL
// resolves against the page origin. On the server there is no origin, and
// Node's fetch throws `Failed to parse URL from /api/pump-fun-mcp`: that one
// line was every scan tick of every strategy run in production (2026-09-01),
// so no backtest or simulated session ever sourced a mint. Two rungs:
// 1. POST /api/pump-fun-mcp tools/call dispatches IN-PROCESS to the same tool
// handlers the HTTP route runs, wrapped in the JSON-RPC envelope the skill
// unwraps. No loopback hop, and the strategy loop (four tools per mint,
// every few seconds) stops spending the server's own per-IP MCP limit.
// 2. Any other relative path resolves against APP_ORIGIN.
// Absolute URLs and Request objects pass straight through untouched.
async function serverFetch(input, init) {
const url = typeof input === 'string' ? input : input?.url;
if (typeof url !== 'string' || !url.startsWith('/')) return globalThis.fetch(input, init);
const path = url.split('?')[0];
const isPost = String(init?.method || 'GET').toUpperCase() === 'POST';
let rpc = null;
if (path === '/api/pump-fun-mcp' && isPost) {
try { rpc = JSON.parse(typeof init?.body === 'string' ? init.body : '{}'); } catch { rpc = null; }
}
if (rpc?.method === 'tools/call') {
const id = rpc.id ?? null;
let envelope;
try {
const { callPumpFunTool } = await import('../pump-fun-mcp.js');
const data = await callPumpFunTool(rpc.params?.name, rpc.params?.arguments ?? {});
envelope = {
jsonrpc: '2.0',
id,
result: { content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data },
};
} catch (err) {
envelope = {
jsonrpc: '2.0',
id,
error: { code: err?.rpcCode ?? -32603, message: err?.message ?? 'tool error' },
};
}
return new Response(JSON.stringify(envelope), {
status: 200,
headers: { 'content-type': 'application/json' },
});
}
const { env } = await import('./env.js');
return globalThis.fetch(new URL(url, env.APP_ORIGIN).href, init);
}
/**
* Build a context for invoking skills from a serverless endpoint.
*
* @param {object} opts
* @param {object} [opts.configOverrides] - per-skill config overrides keyed by skill name
* @param {object} [opts.wallet] - solana wallet contract for signing skills
* @param {(event: object) => void} [opts.onEvent] - notified on every memory.note call
* @param {object} [opts.fetch] - fetch impl (defaults to serverFetch: in-process for /api/pump-fun-mcp, APP_ORIGIN for other relative paths)
* @param {string} [opts.agentId] - if set, every memory.note is persisted to agent_actions
* @param {(skillName: string, tag: string) => boolean} [opts.shouldPersist] - return false to skip persisting a note (caller records it itself)
* @param {string} [opts.signerAddress] - persisted with each agent_actions row when agentId is set
* @param {Record<string, { skill_id: string, author_id: string }>} [opts.skillMeta] - DB-sourced royalty metadata keyed by skill name
*/
export function makeRuntime(opts = {}) {
const { configOverrides = {}, wallet, onEvent, fetch = serverFetch, agentId, signerAddress, skillMeta = {}, shouldPersist = null } = opts;
let _sql;
// Map skill-internal tags to canonical action types so existing
// aggregations (spend-policy, portfolio cost-basis) keep working.
function canonicalType(skillName, tag) {
const [, op] = (tag ?? '').split(':');
if (skillName === 'pump-fun-trade') {
if (op === 'buy') return 'pumpfun.buy';
if (op === 'sell') return 'pumpfun.sell';
if (op === 'create') return 'pumpfun.create';
}
return op || tag || 'note';
}
async function persistAction(skillName, tag, value) {
if (!agentId) return;
if (shouldPersist && !shouldPersist(skillName, tag)) return;
try {
if (!_sql) _sql = (await import('./db.js')).sql;
await _sql`
INSERT INTO agent_actions (agent_id, type, payload, source_skill, signature, signer_address)
VALUES (
${agentId},
${canonicalType(skillName, tag)},
${JSON.stringify(value ?? {})}::jsonb,
${skillName},
${value?.sig ?? null},
${signerAddress ?? null}
)
`;
} catch (e) {
// Persistence is best-effort; never break the strategy on a DB hiccup.
console.error('[skill-runtime] persistAction failed', e?.message);
}
}
async function invoke(qualified, args) {
const [skillName, toolName] = qualified.split('.');
if (!skillName || !toolName) return { ok: false, error: `bad tool: ${qualified}` };
let mod;
try { mod = await loadSkill(skillName); }
catch (e) { return { ok: false, error: e.message }; }
const fn = mod[toolName];
if (typeof fn !== 'function') {
return { ok: false, error: `tool not found: ${qualified}` };
}
const manifest = await loadManifest(skillName);
const skillConfig = { ...(manifest.config ?? {}), ...(configOverrides[skillName] ?? {}) };
const ctx = {
skills: { invoke },
skillConfig,
wallet,
fetch,
memory: {
note: (tag, value) => {
try { onEvent?.({ skill: skillName, tool: toolName, tag, value, t: Date.now() }); } catch {}
// Fire and forget — don't block the strategy loop on disk writes.
persistAction(skillName, tag, value);
},
recall: async () => null,
},
};
let result;
try {
result = await fn(args ?? {}, ctx);
} catch (e) {
return { ok: false, error: e?.message ?? String(e) };
}
// Fire-and-forget royalty billing for paid skills.
if (result?.ok !== false && agentId && manifest.price_per_call_usd > 0) {
const meta = skillMeta[skillName];
if (meta?.skill_id && meta?.author_id) {
queueMicrotask(() => {
import('./royalty.js')
.then(({ billSkillRoyalty }) =>
billSkillRoyalty({
skillId: meta.skill_id,
skillName,
agentId,
authorId: meta.author_id,
priceUsd: manifest.price_per_call_usd,
}),
)
.catch((e) => console.error('[skill-runtime] royalty billing failed', e?.message));
});
}
// Record autonomous agent payment in agent_payments ledger.
queueMicrotask(() => {
import('./agent-wallet.js')
.then(({ triggerSkillPayment }) =>
triggerSkillPayment({ agentId, skillSlug: skillName, skillId: skillMeta[skillName]?.skill_id ?? null }),
)
.catch(() => {});
});
}
return result;
}
return { invoke };
}