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 registry — loads skill bundles and exposes the ctx API.
// See specs/SKILL_SPEC.md
import { resolveURI } from '../ipfs.js';
import { getHost } from './sandbox-host.js';
import { startDataReactive } from '../runtime/data-reactive.js';
import { log } from '../shared/log.js';
import { credentialsFor } from '../shared/embed-api-origin.js';
/** Injected into every skill handler ctx as ctx.dataReactive */
const dataReactive = { start: startDataReactive };
const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
function parseFrontmatter(text) {
const m = text.match(FRONTMATTER_RE);
if (!m) return { meta: {}, body: text };
const meta = {};
for (const line of m[1].split('\n')) {
const [k, ...rest] = line.split(':');
if (!k) continue;
const val = rest.join(':').trim();
// Handle simple arrays
if (val.startsWith('-')) continue; // skip, multi-line array
meta[k.trim()] = val;
}
return { meta, body: m[2] };
}
// The origin of an http(s) URL (a root-relative one resolves against the page),
// or '' for anything else.
function originOf(url) {
try {
const u = new URL(url, typeof location !== 'undefined' ? location.href : undefined);
return u.protocol === 'https:' || u.protocol === 'http:' ? u.origin : '';
} catch {
return '';
}
}
function joinURI(base, rel) {
if (/^([a-z]+:|\/)/i.test(rel)) return rel;
if (!base.endsWith('/')) base += '/';
return base + rel;
}
export class Skill {
constructor({ uri, manifest, instructions, tools, handlers, handlersSrc, mainThread = false }) {
this.uri = uri;
this.manifest = manifest;
this.name = manifest.name;
this.version = manifest.version;
this.instructions = instructions;
this.tools = tools || [];
// trusted-main-thread: populated from dynamic import; sandbox: populated from handlersSrc
this.handlers = handlers || {};
this.handlersSrc = handlersSrc || null;
// Decided by SkillRegistry, never read straight off the manifest: a
// manifest is authored by whoever hosts the bundle.
this.mainThread = Boolean(mainThread);
}
async invoke(toolName, args, ctx) {
const paymentProof = ctx?.agentId
? await checkPaymentGate(toolName, ctx.agentId, ctx.apiOrigin || '')
: null;
const scoped = {
...ctx,
skillBaseURI: this.uri,
dataReactive,
...(paymentProof && { paymentProof }),
};
// A skill the registry cleared for the main thread (see mayRunOnMainThread).
if (this.mainThread) {
const handler = this.handlers[toolName];
if (!handler) {
throw new Error(`Skill "${this.name}" has no handler for tool "${toolName}"`);
}
return handler(args, scoped);
}
if (!this.handlersSrc) {
throw new Error(`Skill "${this.name}" has no handler source for tool "${toolName}"`);
}
return getHost().invoke(this.uri, toolName, args, this.handlersSrc, scoped);
}
systemPromptFragment() {
// The LLM sees the skill's markdown body as part of its system context.
if (!this.instructions) return '';
return `\n\n<skill name="${this.name}" version="${this.version}">\n${this.instructions}\n</skill>`;
}
}
export class SkillRegistry {
constructor({
fetchFn = fetch.bind(globalThis),
trust = 'owned-only',
ownerAddress,
mainThreadOrigins,
trustedAuthors = [],
trustedOrigins = [],
} = {}) {
this.fetchFn = fetchFn;
this.trust = trust;
this.ownerAddress = ownerAddress?.toLowerCase();
this.mainThreadOrigins = new Set(
(mainThreadOrigins ?? [typeof location !== 'undefined' ? location.origin : ''])
.map(originOf)
.filter(Boolean),
);
// `whitelist` trust: a bundle installs only when its manifest author or its
// serving origin is listed here. Empty lists admit nothing.
this.trustedAuthors = new Set(trustedAuthors.map((a) => String(a).toLowerCase()));
this.trustedOrigins = new Set(trustedOrigins.map(originOf).filter(Boolean));
this.skills = new Map();
}
/**
* Whether a bundle's handlers may be imported into the page instead of the
* worker. `sandboxPolicy: "trusted-main-thread"` is only a request: the
* manifest is written by whoever hosts the bundle, and an on-chain agent's
* skill URIs are written by whoever minted it, so honoring the flag on its
* own let any such bundle run arbitrary code in the embedding page. The
* request is granted only for bundles served from an origin the host trusts
* (by default the page's own) and never under `any` trust.
* @param {object} manifest
* @param {string} uri resolved bundle URI
*/
mayRunOnMainThread(manifest, uri) {
if (manifest?.sandboxPolicy !== 'trusted-main-thread') return false;
if (this.trust === 'any') return false;
const origin = originOf(uri);
return Boolean(origin) && this.mainThreadOrigins.has(origin);
}
async install(spec, { bundleBase } = {}) {
// spec: { uri, version? } — uri may be relative, ipfs://, or https://
const uri = this._resolveBundleURI(spec.uri, bundleBase);
if (this.skills.has(uri)) return this.skills.get(uri);
const manifest = await this._fetchJSON(`${uri}manifest.json`);
this._enforceTrust(manifest, uri);
const isTrusted = this.mayRunOnMainThread(manifest, uri);
if (manifest.sandboxPolicy === 'trusted-main-thread' && !isTrusted) {
log.warn(
`[skills] "${manifest.name}" asked for the main thread from an untrusted origin; running it in the sandbox`,
);
}
const [instructions, toolsJSON, handlersData] = await Promise.all([
this._fetchText(`${uri}SKILL.md`).catch(() => ''),
this._fetchJSON(`${uri}tools.json`).catch(() => ({ tools: [] })),
isTrusted
? this._fetchHandlers(`${uri}handlers.js`).catch(() => null)
: this._fetchHandlersSrc(`${uri}handlers.js`).catch(() => null),
]);
const skill = new Skill({
uri,
manifest,
instructions,
tools: toolsJSON.tools || [],
handlers: isTrusted ? handlersData || {} : {},
handlersSrc: isTrusted ? null : handlersData,
mainThread: isTrusted,
});
// Recursively install skill dependencies
if (manifest.dependencies) {
for (const [depURI, depVer] of Object.entries(manifest.dependencies)) {
await this.install({ uri: depURI, version: depVer });
}
}
this.skills.set(uri, skill);
return skill;
}
uninstall(name) {
for (const [uri, skill] of this.skills) {
if (skill.name === name) {
this.skills.delete(uri);
return true;
}
}
return false;
}
all() {
return Array.from(this.skills.values());
}
allTools() {
// Merge tool schemas from all skills. Later skills override earlier on name collision.
const merged = new Map();
for (const skill of this.skills.values()) {
for (const tool of skill.tools) {
if (merged.has(tool.name)) {
log.warn(
`[skills] tool "${tool.name}" overridden by skill "${skill.name}"`,
);
}
merged.set(tool.name, { ...tool, _skill: skill.name });
}
}
return Array.from(merged.values());
}
findSkillForTool(toolName) {
for (const skill of this.skills.values()) {
if (skill.tools.some((t) => t.name === toolName)) return skill;
}
return null;
}
systemPrompt() {
return this.all()
.map((s) => s.systemPromptFragment())
.join('');
}
_resolveBundleURI(uri, base) {
let resolved = uri;
if (!/^([a-z]+:|\/)/i.test(uri) && base) {
resolved = joinURI(base, uri);
}
// Normalize trailing slash
if (!resolved.endsWith('/')) resolved += '/';
// Resolve ipfs:// → https gateway
if (resolved.startsWith('ipfs://') || resolved.startsWith('ar://')) {
resolved = resolveURI(resolved);
}
return resolved;
}
async _fetchJSON(url) {
const res = await this.fetchFn(url);
if (!res.ok) throw new Error(`Fetch failed: ${url} (${res.status})`);
return res.json();
}
async _fetchText(url) {
const res = await this.fetchFn(url);
if (!res.ok) throw new Error(`Fetch failed: ${url} (${res.status})`);
return res.text();
}
async _fetchHandlers(url) {
// Used only for trusted-main-thread skills — direct import into main thread.
try {
const mod = await import(/* @vite-ignore */ url);
return mod;
} catch (e) {
log.warn(`[skills] handlers load failed: ${url}`, e);
return null;
}
}
async _fetchHandlersSrc(url) {
// Fetch handler source as text for sandboxed execution in the worker.
const res = await this.fetchFn(url);
if (!res.ok) throw new Error(`Fetch failed: ${url} (${res.status})`);
return res.text();
}
_enforceTrust(manifest, uri = '') {
if (this.trust === 'any') return;
if (this.trust === 'owned-only') {
const author = (manifest.author || '').toLowerCase();
if (author && this.ownerAddress && author !== this.ownerAddress) {
throw new Error(
`Skill "${manifest.name}" author ${author} not trusted under owned-only policy`,
);
}
}
if (this.trust === 'whitelist') {
const author = String(manifest.author || '').toLowerCase();
const origin = originOf(uri);
const allowed =
(author && this.trustedAuthors.has(author)) ||
(origin && this.trustedOrigins.has(origin));
if (!allowed) {
throw new Error(
`Skill "${manifest.name}" is not on the whitelist (author ${author || 'unknown'}, origin ${origin || 'unknown'})`,
);
}
}
}
}
// ── Payment gate ──────────────────────────────────────────────────────────────
const KNOWN_MINT_SYMBOLS = {
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: 'USDC',
'4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU': 'USDC',
So11111111111111111111111111111111111111112: 'SOL',
};
function mintSymbol(mint) {
return KNOWN_MINT_SYMBOLS[mint] || `${String(mint).slice(0, 4)}…${String(mint).slice(-4)}`;
}
// `apiOrigin` is the three.ws origin an <agent-3d> embed was loaded from; ''
// keeps these reads relative on three.ws's own pages.
function apiCredentials(apiOrigin) {
return credentialsFor(apiOrigin, typeof location !== 'undefined' ? location.origin : '');
}
async function fetchAgentSnippet(agentId, apiOrigin = '') {
try {
const r = await fetch(`${apiOrigin}/api/agents/${encodeURIComponent(agentId)}`, {
credentials: apiCredentials(apiOrigin),
});
if (!r.ok) return {};
const data = await r.json();
const payments = data?.agent?.payments || data?.agent?.meta?.payments || data?.payments;
return { payments, meta: { payments } };
} catch {
return {};
}
}
/**
* Returns the intentId string if payment was collected, null if the skill is free.
* Throws (with code=PAYMENT_CANCELLED) if the user dismisses the modal.
*/
async function checkPaymentGate(toolName, agentId, apiOrigin = '') {
if (typeof document === 'undefined') return null;
let manifest;
try {
const r = await fetch(
`${apiOrigin}/api/agents/x402/manifest?agent_id=${encodeURIComponent(agentId)}&skill=${encodeURIComponent(toolName)}`,
{ credentials: apiCredentials(apiOrigin) },
);
if (r.status !== 200) return null;
manifest = await r.json();
if (manifest?.version !== 'x402/0.1' || manifest?.kind !== 'agent-skill') return null;
} catch {
return null;
}
const [{ showPaymentGateModal }, { getPaymentsAdapter }, { getAdapter }] = await Promise.all([
import('../components/payment-gate-modal.jsx'),
import('../onchain/payments/index.js'),
import('../onchain/adapters/index.js'),
]);
const progressLabels = {
connect: 'Connecting wallet…',
prep: 'Building payment…',
sign: 'Sign in your wallet…',
submit: 'Submitting…',
confirm: 'Verifying…',
};
return showPaymentGateModal({
skill: toolName,
amount: manifest.amount,
currencySymbol: mintSymbol(manifest.currency),
chain: 'Solana',
onPay: async ({ setStatus }) => {
const wallet = getAdapter('solana');
if (!wallet.isAvailable()) {
throw Object.assign(
new Error('No Solana wallet detected. Please install Phantom or Backpack.'),
{ code: 'NO_PROVIDER' },
);
}
const agentSnippet = await fetchAgentSnippet(agentId, apiOrigin);
const adapter = getPaymentsAdapter('pumpfun');
const paid = await adapter.payAgent({
agent: { id: agentId, ...agentSnippet },
currencyMint: manifest.currency,
amount: manifest.amount,
onProgress: (step) => setStatus(progressLabels[step] || step),
});
return paid.intentId;
},
onCancel: () => {},
});
}