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
import { describe, it, expect, beforeEach, vi } from 'vitest';
// Mock pumpfun side-effect modules before AgentSkills is imported
vi.mock('../../src/agent-skills-pumpfun.js', () => ({ registerPumpFunSkills: vi.fn() }));
vi.mock('../../src/agent-skills-pumpfun-watch.js', () => ({ registerPumpFunWatchSkills: vi.fn() }));
vi.mock('../../src/agent-skills-pumpfun-autonomous.js', () => ({
registerPumpFunAutonomousSkills: vi.fn(),
}));
vi.mock('../../src/agent-skills-pumpfun-compose.js', () => ({
registerPumpFunComposeSkills: vi.fn(),
}));
vi.mock('../../src/agent-skills-pumpfun-hooks.js', () => ({ attachPumpFunMemoryHooks: vi.fn() }));
// Mock sandbox host so worker code doesn't run in Node
vi.mock('../../src/skills/sandbox-host.js', () => ({
getHost: vi.fn(() => ({ invoke: vi.fn() })),
}));
import { AgentSkills } from '../../src/agent-skills.js';
import { AgentProtocol, ACTION_TYPES } from '../../src/agent-protocol.js';
import { SkillRegistry } from '../../src/skills/index.js';
// ── helpers ───────────────────────────────────────────────────────────────────
function makeResponse(data, { ok = true, status = 200, asText = false } = {}) {
return {
ok,
status,
json: () => Promise.resolve(data),
text: () => Promise.resolve(asText ? data : JSON.stringify(data)),
};
}
/**
* Build a fetch stub that returns responses keyed by URL suffix.
* Keys are matched via String.includes(); the first match wins.
*/
function makeFetch(routes = {}) {
return vi.fn(async (url) => {
const str = url.toString();
for (const [pattern, response] of Object.entries(routes)) {
if (str.includes(pattern)) return response;
}
return makeResponse(null, { ok: false, status: 404 });
});
}
function fixtureManifest(overrides = {}) {
return {
name: 'test-skill',
version: '1.0.0',
description: 'A test skill',
author: '0xowner',
sandboxPolicy: 'sandboxed',
...overrides,
};
}
function fixtureRoutes(manifest = fixtureManifest(), { instructions = '', tools = [] } = {}) {
return {
'manifest.json': makeResponse(manifest),
'SKILL.md': makeResponse(instructions, { asText: true }),
'tools.json': makeResponse({ tools }),
'handlers.js': makeResponse('export default {}', { asText: true }),
};
}
// ── SkillRegistry – Installation & trust ─────────────────────────────────────
describe('SkillRegistry.install – trust modes', () => {
it('any trust accepts a skill with any author', async () => {
const manifest = fixtureManifest({ author: '0xstranger' });
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(manifest)),
trust: 'any',
});
const skill = await registry.install({ uri: 'https://example.com/skill/' });
expect(skill.name).toBe('test-skill');
});
it('owned-only rejects a skill whose author does not match ownerAddress', async () => {
const manifest = fixtureManifest({ author: '0xstranger' });
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(manifest)),
trust: 'owned-only',
ownerAddress: '0xowner',
});
await expect(registry.install({ uri: 'https://example.com/skill/' })).rejects.toThrow(
/not trusted under owned-only/,
);
});
it('owned-only accepts a skill whose author matches ownerAddress (case-insensitive)', async () => {
const manifest = fixtureManifest({ author: '0xOwner' });
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(manifest)),
trust: 'owned-only',
ownerAddress: '0xowner',
});
const skill = await registry.install({ uri: 'https://example.com/skill/' });
expect(skill.name).toBe('test-skill');
});
it('owned-only allows any skill when ownerAddress is not set', async () => {
const manifest = fixtureManifest({ author: '0xanyone' });
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(manifest)),
trust: 'owned-only',
});
const skill = await registry.install({ uri: 'https://example.com/skill/' });
expect(skill.name).toBe('test-skill');
});
it('whitelist mode fails closed with no allowlist configured', async () => {
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes()),
trust: 'whitelist',
});
await expect(registry.install({ uri: 'https://example.com/skill/' })).rejects.toThrow(
/not on the whitelist/,
);
});
it('whitelist mode admits a listed author or a listed origin only', async () => {
const byAuthor = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(fixtureManifest({ author: '0xOwner' }))),
trust: 'whitelist',
trustedAuthors: ['0xowner'],
});
expect((await byAuthor.install({ uri: 'https://example.com/skill/' })).name).toBe('test-skill');
const byOrigin = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(fixtureManifest({ author: '0xstranger' }))),
trust: 'whitelist',
trustedOrigins: ['https://example.com'],
});
expect((await byOrigin.install({ uri: 'https://example.com/skill/' })).name).toBe('test-skill');
await expect(byOrigin.install({ uri: 'https://evil.example/skill/' })).rejects.toThrow(/whitelist/);
});
});
describe('SkillRegistry.install: main-thread opt-out', () => {
const mainThreadManifest = () => fixtureManifest({ sandboxPolicy: 'trusted-main-thread' });
it('sandboxes a trusted-main-thread bundle served from an untrusted origin', async () => {
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(mainThreadManifest())),
trust: 'owned-only',
mainThreadOrigins: ['https://three.ws'],
});
const skill = await registry.install({ uri: 'https://cdn.jsdelivr.net/npm/[email protected]/' });
expect(skill.mainThread).toBe(false);
expect(skill.handlersSrc).toBe('export default {}');
});
it('never grants the main thread under any trust, even from a trusted origin', async () => {
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(mainThreadManifest())),
trust: 'any',
mainThreadOrigins: ['https://three.ws'],
});
const skill = await registry.install({ uri: 'https://three.ws/skills/tip-jar/' });
expect(skill.mainThread).toBe(false);
});
it('grants the main thread to a bundle from a trusted origin', () => {
const registry = new SkillRegistry({
fetchFn: makeFetch({}),
trust: 'owned-only',
mainThreadOrigins: ['https://three.ws'],
});
expect(registry.mayRunOnMainThread(mainThreadManifest(), 'https://three.ws/skills/tip-jar/')).toBe(true);
expect(registry.mayRunOnMainThread(fixtureManifest(), 'https://three.ws/skills/tip-jar/')).toBe(false);
expect(registry.mayRunOnMainThread(mainThreadManifest(), 'https://three.ws.evil.example/x/')).toBe(false);
expect(registry.mayRunOnMainThread(mainThreadManifest(), 'data:text/javascript,alert(1)')).toBe(false);
});
it('routes a downgraded skill through the sandbox host on invoke', async () => {
const { getHost } = await import('../../src/skills/sandbox-host.js');
const invoke = vi.fn(async () => ({ ok: true }));
getHost.mockReturnValue({ invoke });
const registry = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(mainThreadManifest())),
trust: 'owned-only',
mainThreadOrigins: ['https://three.ws'],
});
const skill = await registry.install({ uri: 'https://attacker.example/skill/' });
await skill.invoke('do_it', {}, {});
expect(invoke).toHaveBeenCalledWith(
'https://attacker.example/skill/',
'do_it',
{},
'export default {}',
expect.any(Object),
);
});
});
describe('SkillRegistry.install – dependency loading', () => {
it('recursively installs each dependency URI listed in manifest.dependencies', async () => {
const depManifest = fixtureManifest({ name: 'dep-skill', dependencies: undefined });
const rootManifest = fixtureManifest({
dependencies: { 'https://cdn.example.com/dep/': '1.0.0' },
});
const fetchFn = makeFetch({
// root skill
'example.com/skill/manifest.json': makeResponse(rootManifest),
'example.com/skill/SKILL.md': makeResponse('', { asText: true }),
'example.com/skill/tools.json': makeResponse({ tools: [] }),
'example.com/skill/handlers.js': makeResponse('', { asText: true }),
// dependency
'cdn.example.com/dep/manifest.json': makeResponse(depManifest),
'cdn.example.com/dep/SKILL.md': makeResponse('', { asText: true }),
'cdn.example.com/dep/tools.json': makeResponse({ tools: [] }),
'cdn.example.com/dep/handlers.js': makeResponse('', { asText: true }),
});
const registry = new SkillRegistry({ fetchFn, trust: 'any' });
await registry.install({ uri: 'https://example.com/skill/' });
const names = registry.all().map((s) => s.name);
expect(names).toContain('dep-skill');
});
it('installing the same URI twice returns the cached skill and does not duplicate', async () => {
const fetchFn = makeFetch(fixtureRoutes());
const registry = new SkillRegistry({ fetchFn, trust: 'any' });
await registry.install({ uri: 'https://example.com/skill/' });
await registry.install({ uri: 'https://example.com/skill/' });
expect(registry.all()).toHaveLength(1);
// fetchFn called only for the first install (3 files; handlers.js is a 4th)
expect(fetchFn).toHaveBeenCalledTimes(4);
});
});
// ── SkillRegistry – Skill lookup ──────────────────────────────────────────────
describe('SkillRegistry – skill lookup', () => {
let registry;
beforeEach(async () => {
registry = new SkillRegistry({ fetchFn: makeFetch(fixtureRoutes()), trust: 'any' });
await registry.install({ uri: 'https://example.com/skill/' });
});
it('installed skill is discoverable via all()', () => {
const found = registry.all().find((s) => s.name === 'test-skill');
expect(found).toBeDefined();
expect(found.name).toBe('test-skill');
});
it('uninstalled skill name returns undefined from all().find()', () => {
const found = registry.all().find((s) => s.name === 'nonexistent');
expect(found).toBeUndefined();
});
it('findSkillForTool returns null for an unknown tool', () => {
expect(registry.findSkillForTool('ghost-tool')).toBeNull();
});
it('findSkillForTool returns the skill that owns a registered tool', async () => {
const tools = [{ name: 'do-thing', description: 'does thing' }];
const reg2 = new SkillRegistry({
fetchFn: makeFetch(fixtureRoutes(fixtureManifest({ name: 'tool-skill' }), { tools })),
trust: 'any',
});
await reg2.install({ uri: 'https://cdn.example.com/tool-skill/' });
const skill = reg2.findSkillForTool('do-thing');
expect(skill).not.toBeNull();
expect(skill.name).toBe('tool-skill');
});
});
// ── SkillRegistry – Manifest loading ─────────────────────────────────────────
describe('SkillRegistry – manifest loading', () => {
it('loads a skill from an https:// URL, normalizing the trailing slash', async () => {
const fetchFn = makeFetch(fixtureRoutes());
const registry = new SkillRegistry({ fetchFn, trust: 'any' });
// No trailing slash — should be added automatically
const skill = await registry.install({ uri: 'https://example.com/skill' });
expect(skill).toBeDefined();
expect(skill.uri).toBe('https://example.com/skill/');
});
it('resolves an ipfs:// URI to the primary gateway URL before fetching', async () => {
// ipfs://QmTest → https://ipfs.filebase.io/ipfs/QmTest/
const fetchFn = makeFetch({
'ipfs.filebase.io/ipfs/QmTest/manifest.json': makeResponse(fixtureManifest()),
'ipfs.filebase.io/ipfs/QmTest/SKILL.md': makeResponse('', { asText: true }),
'ipfs.filebase.io/ipfs/QmTest/tools.json': makeResponse({ tools: [] }),
'ipfs.filebase.io/ipfs/QmTest/handlers.js': makeResponse('', { asText: true }),
});
const registry = new SkillRegistry({ fetchFn, trust: 'any' });
const skill = await registry.install({ uri: 'ipfs://QmTest' });
expect(skill).toBeDefined();
expect(skill.uri).toContain('ipfs.filebase.io/ipfs/QmTest');
});
});
// ── AgentSkills – Execution lifecycle ────────────────────────────────────────
describe('AgentSkills.perform – execution lifecycle', () => {
let protocol, memory, skills;
beforeEach(() => {
protocol = new AgentProtocol();
memory = { add: vi.fn(() => 'mem-1'), query: vi.fn(() => []) };
skills = new AgentSkills(protocol, memory);
// Register a minimal custom skill for execution tests
skills.register({
name: 'echo',
description: 'echoes args',
handler: vi.fn(async (args) => ({ success: true, output: args.text ?? 'ok' })),
});
});
it('invokes the handler with (args, ctx)', async () => {
const handler = skills.get('echo').handler;
await skills.perform('echo', { text: 'hello' });
expect(handler).toHaveBeenCalledOnce();
const [args, ctx] = handler.mock.calls[0];
expect(args).toEqual({ text: 'hello' });
expect(ctx).toHaveProperty('protocol', protocol);
expect(ctx).toHaveProperty('memory', memory);
});
it('emits PERFORM_SKILL before the handler runs', async () => {
const events = [];
protocol.on(ACTION_TYPES.PERFORM_SKILL, (a) => events.push(a));
const handler = skills.get('echo').handler;
handler.mockImplementation(async () => {
expect(events).toHaveLength(1); // already emitted
return { success: true, output: 'ok' };
});
await skills.perform('echo', {});
expect(events[0].payload.skill).toBe('echo');
});
it('emits SKILL_DONE with the result on success', async () => {
const done = vi.fn();
protocol.on(ACTION_TYPES.SKILL_DONE, done);
await skills.perform('echo', { text: 'hi' });
expect(done).toHaveBeenCalledOnce();
expect(done.mock.calls[0][0].payload).toMatchObject({
skill: 'echo',
result: { success: true, output: 'hi' },
});
});
it('emits SKILL_ERROR and returns a failure result when the handler throws', async () => {
skills.register({
name: 'bad-skill',
description: 'always throws',
handler: async () => {
throw new Error('something went wrong');
},
});
const errEvents = vi.fn();
protocol.on(ACTION_TYPES.SKILL_ERROR, errEvents);
const result = await skills.perform('bad-skill', {});
expect(result.success).toBe(false);
expect(result.output).toContain('something went wrong');
expect(errEvents).toHaveBeenCalledOnce();
expect(errEvents.mock.calls[0][0].payload).toMatchObject({
skill: 'bad-skill',
error: 'something went wrong',
});
});
it('returns a failure result for an unknown skill without throwing', async () => {
const result = await skills.perform('no-such-skill', {});
expect(result.success).toBe(false);
expect(result.output).toContain('no-such-skill');
});
it('auto-speaks the result output when isBrowser is true', async () => {
const speaks = vi.fn();
protocol.on(ACTION_TYPES.SPEAK, speaks);
await skills.perform('echo', { text: 'greetings' }, { isBrowser: true });
expect(speaks).toHaveBeenCalledOnce();
expect(speaks.mock.calls[0][0].payload.text).toBe('greetings');
});
it('does not auto-speak when isBrowser is false', async () => {
const speaks = vi.fn();
protocol.on(ACTION_TYPES.SPEAK, speaks);
await skills.perform('echo', { text: 'greetings' }, { isBrowser: false });
expect(speaks).not.toHaveBeenCalled();
});
});
// ── AgentSkills – Built-in skill: remember ────────────────────────────────────
describe('AgentSkills built-in – remember', () => {
let protocol, memory, skills;
beforeEach(() => {
protocol = new AgentProtocol();
memory = { add: vi.fn(() => 'mem-42'), query: vi.fn(() => []) };
skills = new AgentSkills(protocol, memory);
});
it('emits REMEMBER on the protocol when isBrowser is true', async () => {
const remembered = vi.fn();
protocol.on(ACTION_TYPES.REMEMBER, remembered);
await skills.perform('remember', { content: 'unit test ran' }, { isBrowser: true });
expect(remembered).toHaveBeenCalledOnce();
expect(remembered.mock.calls[0][0].payload.content).toBe('unit test ran');
});
it('does not emit REMEMBER when isBrowser is false', async () => {
const remembered = vi.fn();
protocol.on(ACTION_TYPES.REMEMBER, remembered);
await skills.perform('remember', { content: 'silent' }, { isBrowser: false });
expect(remembered).not.toHaveBeenCalled();
});
it('stores the memory entry via memory.add()', async () => {
await skills.perform('remember', { content: 'important fact' }, { isBrowser: false });
expect(memory.add).toHaveBeenCalledWith(
expect.objectContaining({ content: 'important fact' }),
);
});
it('returns failure when content is missing', async () => {
const result = await skills.perform('remember', {}, { isBrowser: false });
expect(result.success).toBe(false);
});
});
// ── AgentSkills – Registry API ────────────────────────────────────────────────
describe('AgentSkills – registry API', () => {
let skills;
beforeEach(() => {
skills = new AgentSkills(new AgentProtocol(), {
add: vi.fn(),
query: vi.fn(() => []),
});
});
it('get(name) returns the skill def for a registered skill', () => {
const def = skills.get('greet');
expect(def).toBeDefined();
expect(def.name).toBe('greet');
expect(typeof def.handler).toBe('function');
});
it('get(name) returns undefined for an unregistered skill', () => {
expect(skills.get('not-here')).toBeUndefined();
});
it('list() includes all built-in skills', () => {
const names = skills.list().map((s) => s.name);
expect(names).toContain('greet');
expect(names).toContain('remember');
expect(names).toContain('help');
expect(names).toContain('think');
});
it('unregister removes the skill from the registry', () => {
skills.register({ name: 'temp', description: 'temp', handler: vi.fn() });
expect(skills.get('temp')).toBeDefined();
skills.unregister('temp');
expect(skills.get('temp')).toBeUndefined();
});
it('toMcpTools() returns only mcpExposed skills', () => {
const tools = skills.toMcpTools();
// All returned tools should come from MCP-exposed skills
const exposedNames = skills.list().filter((s) => s.mcpExposed).map((s) => s.name);
expect(tools.length).toBe(exposedNames.length);
// 'help' and 'think' are not MCP-exposed
expect(tools.map((t) => t.name)).not.toContain('skill_help');
expect(tools.map((t) => t.name)).not.toContain('skill_think');
});
});