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';
import { Runtime } from '../../src/runtime/index.js';
import { NullProvider } from '../../src/runtime/providers.js';
import { BUILTIN_HANDLERS, BUILTIN_TOOLS } from '../../src/runtime/tools.js';
// Disable voice in all Runtime instances — avoids BrowserTTS/BrowserSTT in tests
const NO_VOICE = { tts: { provider: 'none' }, stt: { provider: 'none' } };
// ── Mock provider factory ─────────────────────────────────────────────────────
function mockProvider(responses) {
let idx = 0;
return {
complete: vi.fn(() => {
const r = responses[idx < responses.length ? idx++ : responses.length - 1];
return Promise.resolve(r);
}),
formatAssistantWithToolCalls(text, toolCalls) {
const content = [];
if (text) content.push({ type: 'text', text });
for (const c of toolCalls)
content.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input });
return { role: 'assistant', content };
},
formatToolResults(results) {
return {
role: 'user',
content: results.map((r) => ({
type: 'tool_result',
tool_use_id: r.id,
content: JSON.stringify(r.output),
is_error: !!r.isError,
})),
};
},
};
}
// Shorthand response shapes
const textResp = (text) => ({ text, toolCalls: [], thinking: '', stopReason: 'end_turn' });
const toolResp = (name, input = {}, id = 'call_1') => ({
text: '',
toolCalls: [{ id, name, input }],
thinking: '',
stopReason: 'tool_use',
});
// Build a Runtime with a mock provider and optional overrides
function makeRuntime(provider, { viewer = null, memory = null, skills = null, manifest = {} } = {}) {
const rt = new Runtime({
manifest,
viewer,
memory,
skills,
providerConfig: { provider: 'none' },
voiceConfig: NO_VOICE,
});
rt.provider = provider;
return rt;
}
// Collect CustomEvent detail objects from a Runtime EventTarget
function collect(runtime, eventName) {
const events = [];
runtime.addEventListener(eventName, (e) => events.push(e.detail));
return events;
}
// ── NullProvider ──────────────────────────────────────────────────────────────
describe('NullProvider', () => {
it('complete() resolves immediately without making HTTP calls', async () => {
const fetchSpy = vi.spyOn(globalThis, 'fetch');
const p = new NullProvider();
const result = await p.complete({ system: '', messages: [], tools: [] });
expect(result.text).toBe('');
expect(result.toolCalls).toEqual([]);
expect(result.stopReason).toBe('end_turn');
expect(fetchSpy).not.toHaveBeenCalled();
fetchSpy.mockRestore();
});
});
// ── Text response flow ────────────────────────────────────────────────────────
describe('Runtime — text response', () => {
it('calls provider.complete with user message and returns final text', async () => {
const provider = mockProvider([textResp('Hello world')]);
const rt = makeRuntime(provider);
const result = await rt.send('Hi');
expect(provider.complete).toHaveBeenCalledOnce();
expect(provider.complete.mock.calls[0][0].messages[0]).toMatchObject({
role: 'user',
content: 'Hi',
});
expect(result.text).toBe('Hello world');
});
it('emits brain:message for user turn then assistant turn', async () => {
const provider = mockProvider([textResp('Hello world')]);
const rt = makeRuntime(provider);
const events = collect(rt, 'brain:message');
await rt.send('Hi');
expect(events).toHaveLength(2);
expect(events[0]).toMatchObject({ role: 'user', content: 'Hi' });
expect(events[1]).toMatchObject({ role: 'assistant', content: 'Hello world' });
});
it('appends both turns to runtime.messages', async () => {
const provider = mockProvider([textResp('Reply')]);
const rt = makeRuntime(provider);
await rt.send('Hello');
expect(rt.messages).toHaveLength(2);
expect(rt.messages[0]).toMatchObject({ role: 'user', content: 'Hello' });
expect(rt.messages[1]).toMatchObject({ role: 'assistant', content: 'Reply' });
});
});
// ── Thinking ──────────────────────────────────────────────────────────────────
describe('Runtime — thinking events', () => {
it('emits brain:thinking when provider returns thinking content', async () => {
const provider = mockProvider([
{ text: 'Answer', toolCalls: [], thinking: 'Reasoning here', stopReason: 'end_turn' },
]);
const rt = makeRuntime(provider);
const events = collect(rt, 'brain:thinking');
await rt.send('question');
expect(events).toHaveLength(2);
const done = events.find(e => !e.thinking && e.content === 'Reasoning here');
expect(done).toBeDefined();
});
it('does not emit brain:thinking when thinking is empty', async () => {
const provider = mockProvider([textResp('answer')]);
const rt = makeRuntime(provider);
const events = collect(rt, 'brain:thinking');
await rt.send('question');
// Two events are still fired (start + end), but no content event
const contentEvents = events.filter(e => !e.thinking && e.content);
expect(contentEvents).toHaveLength(0);
});
});
// ── Tool call dispatch ────────────────────────────────────────────────────────
describe('Runtime — tool dispatch', () => {
it('calls the built-in handler when provider returns a tool call', async () => {
const provider = mockProvider([toolResp('lookAt', { target: 'user' }), textResp('Done')]);
const viewer = { lookAt: vi.fn() };
const rt = makeRuntime(provider, { viewer });
await rt.send('look at me');
expect(viewer.lookAt).toHaveBeenCalledWith('user');
});
it('emits skill:tool-called after each tool execution', async () => {
const provider = mockProvider([toolResp('lookAt', { target: 'camera' }), textResp('Done')]);
const rt = makeRuntime(provider, { viewer: { lookAt: vi.fn() } });
const events = collect(rt, 'skill:tool-called');
await rt.send('look');
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({ tool: 'lookAt', args: { target: 'camera' } });
});
it('sends tool results back to provider on the next complete() call', async () => {
const provider = mockProvider([
toolResp('lookAt', { target: 'user' }, 'call_abc'),
textResp('Done'),
]);
const rt = makeRuntime(provider, { viewer: { lookAt: vi.fn() } });
await rt.send('look');
expect(provider.complete).toHaveBeenCalledTimes(2);
const secondMessages = provider.complete.mock.calls[1][0].messages;
const toolResultMsg = secondMessages.find(
(m) => m.role === 'user' && Array.isArray(m.content),
);
expect(toolResultMsg).toBeDefined();
expect(toolResultMsg.content[0].tool_use_id).toBe('call_abc');
});
it('skill-provided tool shadows built-in when skills.findSkillForTool returns a match', async () => {
const provider = mockProvider([toolResp('wave', {}), textResp('Done')]);
const skillInvoke = vi.fn().mockResolvedValue({ ok: true, from: 'skill' });
const skills = {
findSkillForTool: vi.fn().mockReturnValue({ invoke: skillInvoke }),
allTools: () => [],
systemPrompt: () => '',
};
const rt = makeRuntime(provider, { skills });
await rt.send('wave');
expect(skillInvoke).toHaveBeenCalledWith('wave', {}, expect.any(Object));
});
});
// ── Skill access gate ────────────────────────────────────────────────────────
describe('Runtime — skill access gate', () => {
it('blocks paid skill, dispatches skill:payment-required, returns 402 result to the LLM', async () => {
const provider = mockProvider([toolResp('premium_search', {}), textResp('blocked')]);
const skillInvoke = vi.fn().mockResolvedValue({ ok: true });
const skills = {
findSkillForTool: vi.fn().mockReturnValue({ invoke: skillInvoke }),
allTools: () => [],
systemPrompt: () => '',
};
const skillAccess = vi.fn().mockResolvedValue({
allowed: false,
price: { amount: '1000000', currency_mint: 'EPjF...', chain: 'solana' },
});
const rt = makeRuntime(provider, { skills });
rt.skillAccess = skillAccess;
const events = collect(rt, 'skill:payment-required');
await rt.send('use premium_search');
expect(skillInvoke).not.toHaveBeenCalled();
expect(skillAccess).toHaveBeenCalledWith('premium_search');
expect(events).toHaveLength(1);
expect(events[0].skill).toBe('premium_search');
expect(events[0].price).toEqual({ amount: '1000000', currency_mint: 'EPjF...', chain: 'solana' });
// The 402 result is fed back to the LLM as a tool_result with is_error=true
const secondCall = provider.complete.mock.calls[1][0];
const toolResultMsg = secondCall.messages.find(
(m) => m.role === 'user' && Array.isArray(m.content),
);
expect(toolResultMsg).toBeDefined();
expect(toolResultMsg.content[0].is_error).toBe(true);
const parsed = JSON.parse(toolResultMsg.content[0].content);
expect(parsed.error).toBe('payment_required');
expect(parsed.skill).toBe('premium_search');
});
it('allows paid skill once skillAccess returns allowed:true (purchased state)', async () => {
const provider = mockProvider([toolResp('premium_search', {}), textResp('done')]);
const skillInvoke = vi.fn().mockResolvedValue({ ok: true, data: 'results' });
const skills = {
findSkillForTool: vi.fn().mockReturnValue({ invoke: skillInvoke }),
allTools: () => [],
systemPrompt: () => '',
};
const rt = makeRuntime(provider, { skills });
rt.skillAccess = vi.fn().mockResolvedValue({ allowed: true });
const events = collect(rt, 'skill:payment-required');
await rt.send('use premium_search');
expect(skillInvoke).toHaveBeenCalled();
expect(events).toHaveLength(0);
});
it('default skillAccess (alwaysAllow) does not gate any tool', async () => {
const provider = mockProvider([toolResp('any_skill', {}), textResp('ok')]);
const skillInvoke = vi.fn().mockResolvedValue({ result: 'free' });
const skills = {
findSkillForTool: vi.fn().mockReturnValue({ invoke: skillInvoke }),
allTools: () => [],
systemPrompt: () => '',
};
const rt = makeRuntime(provider, { skills });
await rt.send('use any_skill');
expect(skillInvoke).toHaveBeenCalled();
});
it('built-in tools bypass the gate even when skillAccess would deny them', async () => {
const provider = mockProvider([toolResp('lookAt', { target: 'user' }), textResp('ok')]);
const rt = makeRuntime(provider);
// A pathological gate that denies everything — should not affect built-ins
rt.skillAccess = vi.fn().mockResolvedValue({ allowed: false });
const events = collect(rt, 'skill:payment-required');
await rt.send('hi');
expect(rt.skillAccess).not.toHaveBeenCalled();
expect(events).toHaveLength(0);
});
});
// ── MAX_TOOL_ITERATIONS guard ─────────────────────────────────────────────────
describe('Runtime — MAX_TOOL_ITERATIONS', () => {
it('exits the loop after 8 iterations even if provider keeps returning tool calls', async () => {
const infiniteProvider = {
complete: vi.fn(() => Promise.resolve(toolResp('lookAt', { target: 'user' }))),
formatAssistantWithToolCalls(text, toolCalls) {
return {
role: 'assistant',
content: toolCalls.map((c) => ({
type: 'tool_use',
id: c.id,
name: c.name,
input: c.input,
})),
};
},
formatToolResults(results) {
return {
role: 'user',
content: results.map((r) => ({
type: 'tool_result',
tool_use_id: r.id,
content: JSON.stringify(r.output),
})),
};
},
};
const rt = makeRuntime(infiniteProvider, { viewer: { lookAt: vi.fn() } });
const result = await rt.send('go');
expect(infiniteProvider.complete).toHaveBeenCalledTimes(8);
expect(result.text).toBe('');
});
});
// ── Error handling ────────────────────────────────────────────────────────────
describe('Runtime — tool error handling', () => {
it('records isError and continues loop without throwing when tool is unknown', async () => {
const provider = mockProvider([toolResp('nonexistent_tool', {}), textResp('Recovered')]);
const rt = makeRuntime(provider);
const toolEvents = collect(rt, 'skill:tool-called');
const result = await rt.send('do something');
expect(result.text).toBe('Recovered');
expect(toolEvents[0].result).toMatchObject({ error: expect.stringContaining('Unknown tool') });
});
it('records isError when tool handler throws and still reaches final response', async () => {
const provider = mockProvider([toolResp('lookAt', { target: 'user' }), textResp('OK')]);
const viewer = {
lookAt: vi.fn(() => {
throw new Error('viewer not ready');
}),
};
const rt = makeRuntime(provider, { viewer });
const toolEvents = collect(rt, 'skill:tool-called');
const result = await rt.send('look');
expect(result.text).toBe('OK');
expect(toolEvents[0].result).toMatchObject({ error: 'viewer not ready' });
});
});
// ── Busy guard ────────────────────────────────────────────────────────────────
describe('Runtime — busy guard', () => {
it('throws if send() is called while a turn is in progress', async () => {
const provider = mockProvider([textResp('ok')]);
const rt = makeRuntime(provider);
const first = rt.send('first');
await expect(rt.send('second')).rejects.toThrow('Runtime busy');
await first;
});
it('clears busy flag after send() completes', async () => {
const provider = mockProvider([textResp('ok'), textResp('ok2')]);
const rt = makeRuntime(provider);
await rt.send('first');
await expect(rt.send('second')).resolves.toMatchObject({ text: 'ok2' });
});
});
// ── Runtime.listen() ──────────────────────────────────────────────────────────
describe('Runtime, listen() voice:listen-start/listen-end symmetry', () => {
it('fires listen-start then listen-end around a successful transcript', async () => {
const rt = makeRuntime(mockProvider([textResp('ok')]));
rt.stt = { listen: vi.fn().mockResolvedValue('hello') };
const events = [];
rt.addEventListener('voice:listen-start', () => events.push('start'));
rt.addEventListener('voice:listen-end', () => events.push('end'));
const text = await rt.listen();
expect(text).toBe('hello');
expect(events).toEqual(['start', 'end']);
});
it('still fires listen-end when the STT call rejects (try/finally, not just the happy path)', async () => {
const rt = makeRuntime(mockProvider([textResp('ok')]));
rt.stt = { listen: vi.fn().mockRejectedValue(new Error('mic denied')) };
const events = [];
rt.addEventListener('voice:listen-start', () => events.push('start'));
rt.addEventListener('voice:listen-end', () => events.push('end'));
await expect(rt.listen()).rejects.toThrow('mic denied');
expect(events).toEqual(['start', 'end']);
});
it('throws without dispatching anything when no STT is configured', async () => {
const rt = makeRuntime(mockProvider([textResp('ok')]));
rt.stt = null;
const events = collect(rt, 'voice:listen-start');
await expect(rt.listen()).rejects.toThrow('STT not configured');
expect(events).toEqual([]);
});
});
// ── BUILTIN_HANDLERS ──────────────────────────────────────────────────────────
describe('BUILTIN_HANDLERS.speak', () => {
it('calls ctx.speak with the text and returns ok', async () => {
const ctx = { speak: vi.fn().mockResolvedValue(undefined) };
const result = await BUILTIN_HANDLERS.speak({ text: 'Hello there' }, ctx);
expect(ctx.speak).toHaveBeenCalledWith('Hello there');
expect(result).toEqual({ ok: true });
});
});
describe('BUILTIN_HANDLERS.remember', () => {
it('writes to ctx.memory and returns ok with the saved key', async () => {
const ctx = { memory: { write: vi.fn() } };
const args = {
key: 'user_role',
name: 'User role',
description: 'What the user does',
type: 'user',
body: 'The user is a developer.',
};
const result = await BUILTIN_HANDLERS.remember(args, ctx);
expect(ctx.memory.write).toHaveBeenCalledWith('user_role', {
name: 'User role',
description: 'What the user does',
type: 'user',
body: 'The user is a developer.',
});
expect(result).toEqual({ ok: true, saved: 'user_role' });
});
});
describe('BUILTIN_HANDLERS.lookAt', () => {
it('calls ctx.viewer.lookAt with the target and returns ok', async () => {
const ctx = { viewer: { lookAt: vi.fn() } };
const result = await BUILTIN_HANDLERS.lookAt({ target: 'camera' }, ctx);
expect(ctx.viewer.lookAt).toHaveBeenCalledWith('camera');
expect(result).toEqual({ ok: true, target: 'camera' });
});
it('defaults target to "user" when not provided', async () => {
const ctx = { viewer: { lookAt: vi.fn() } };
const result = await BUILTIN_HANDLERS.lookAt({}, ctx);
expect(ctx.viewer.lookAt).toHaveBeenCalledWith('user');
expect(result.target).toBe('user');
});
});
describe('BUILTIN_HANDLERS.setExpression', () => {
it('calls ctx.viewer.setExpression with preset and intensity', async () => {
const ctx = { viewer: { setExpression: vi.fn() } };
const result = await BUILTIN_HANDLERS.setExpression({ preset: 'happy', intensity: 0.8 }, ctx);
expect(ctx.viewer.setExpression).toHaveBeenCalledWith('happy', 0.8);
expect(result).toEqual({ ok: true, preset: 'happy' });
});
it('defaults intensity to 1 when not provided', async () => {
const ctx = { viewer: { setExpression: vi.fn() } };
await BUILTIN_HANDLERS.setExpression({ preset: 'sad' }, ctx);
expect(ctx.viewer.setExpression).toHaveBeenCalledWith('sad', 1);
});
});
describe('gesture tool, LLM-composable body language', () => {
it('enumerates every animation slot except the rest state "idle"', () => {
const tool = BUILTIN_TOOLS.find((t) => t.name === 'gesture');
const names = tool.input_schema.properties.name.enum;
expect(names).toContain('nod');
expect(names).toContain('wave');
expect(names).not.toContain('idle');
});
it('resolves the slot name through resolveAnimationSlot before playing it', async () => {
const ctx = {
viewer: {
resolveAnimationSlot: vi.fn().mockReturnValue('Armature|Nod'),
playClipByName: vi.fn().mockReturnValue(true),
},
};
const result = await BUILTIN_HANDLERS.gesture({ name: 'nod' }, ctx);
expect(ctx.viewer.resolveAnimationSlot).toHaveBeenCalledWith('nod');
expect(ctx.viewer.playClipByName).toHaveBeenCalledWith('Armature|Nod', {
loop: false,
fade_ms: 200,
});
expect(result).toEqual({ ok: true, name: 'nod', resolved: 'Armature|Nod' });
});
it('reports failure instead of throwing when the resolved clip is missing from the library', async () => {
const ctx = {
viewer: {
resolveAnimationSlot: vi.fn().mockReturnValue('nod'),
playClipByName: vi.fn().mockReturnValue(false),
},
};
const result = await BUILTIN_HANDLERS.gesture({ name: 'nod' }, ctx);
expect(result).toEqual({ ok: false, error: 'No clip for gesture "nod"' });
});
});