Skip to content

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.

19.5 KB
Raw Blame
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"' });
	});
});