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, afterEach, vi } from 'vitest';
import { AgentProtocol } from '../src/agent-protocol.js';
// Node 18+ provides EventTarget, CustomEvent, and performance globally.
// These tests use vi.useFakeTimers() to control setTimeout and performance.now().
describe('AgentProtocol throttle policies', () => {
let protocol;
beforeEach(() => {
vi.useFakeTimers();
protocol = new AgentProtocol();
});
afterEach(() => {
vi.useRealTimers();
});
// ─── gesture: leading-edge throttle, 600 ms ───────────────────────────────
describe('gesture — leading-edge throttle (600 ms)', () => {
it('fires the first event immediately', () => {
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
expect(received).toHaveLength(1);
expect(received[0].payload.name).toBe('wave');
});
it('drops events within the 600 ms interval', () => {
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
vi.advanceTimersByTime(300);
protocol.emit({ type: 'gesture', payload: { name: 'nod' } });
protocol.emit({ type: 'gesture', payload: { name: 'shrug' } });
expect(received).toHaveLength(1);
expect(protocol.droppedCount('gesture')).toBe(2);
});
it('fires again after the interval elapses', () => {
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
vi.advanceTimersByTime(600);
protocol.emit({ type: 'gesture', payload: { name: 'nod' } });
expect(received).toHaveLength(2);
expect(received[1].payload.name).toBe('nod');
});
it('does not fire trailing events even after the interval', () => {
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
protocol.emit({ type: 'gesture', payload: { name: 'nod' } }); // dropped
vi.advanceTimersByTime(700); // no timer set for leading throttle
expect(received).toHaveLength(1);
});
});
// ─── look-at: trailing-edge debounce, 100 ms ─────────────────────────────
describe('look-at — trailing-edge debounce (100 ms)', () => {
it('does not emit until after the quiet window', () => {
const received = [];
protocol.on('look-at', (a) => received.push(a));
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
expect(received).toHaveLength(0);
vi.advanceTimersByTime(100);
expect(received).toHaveLength(1);
});
it('resets the timer on each new event and emits only the last', () => {
const received = [];
protocol.on('look-at', (a) => received.push(a));
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
vi.advanceTimersByTime(50);
protocol.emit({ type: 'look-at', payload: { target: 'user' } });
vi.advanceTimersByTime(50);
protocol.emit({ type: 'look-at', payload: { target: 'camera' } });
vi.advanceTimersByTime(100);
expect(received).toHaveLength(1);
expect(received[0].payload.target).toBe('camera');
});
it('counts superseded pending events as dropped', () => {
const received = [];
protocol.on('look-at', (a) => received.push(a));
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
protocol.emit({ type: 'look-at', payload: { target: 'user' } });
protocol.emit({ type: 'look-at', payload: { target: 'camera' } });
vi.advanceTimersByTime(100);
expect(received).toHaveLength(1);
expect(received[0].payload.target).toBe('camera');
expect(protocol.droppedCount('look-at')).toBe(2);
});
});
// ─── emote: coalesce by trigger, max weight, 150 ms window ───────────────
describe('emote — coalesce by trigger, max weight (150 ms)', () => {
it('merges same-trigger events to the max weight', () => {
const received = [];
protocol.on('emote', (a) => received.push(a));
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.3 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.9 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.5 } });
vi.advanceTimersByTime(150);
expect(received).toHaveLength(1);
expect(received[0].payload.trigger).toBe('celebration');
expect(received[0].payload.weight).toBe(0.9);
});
it('counts merged events as dropped', () => {
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.3 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.9 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.5 } });
vi.advanceTimersByTime(150);
// 3 events → 1 emitted, 2 dropped (2nd and 3rd merged into bucket)
expect(protocol.droppedCount('emote')).toBe(2);
});
it('emits separate events for different triggers', () => {
const received = [];
protocol.on('emote', (a) => received.push(a));
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.8 } });
protocol.emit({ type: 'emote', payload: { trigger: 'concern', weight: 0.6 } });
vi.advanceTimersByTime(150);
expect(received).toHaveLength(2);
const triggers = received.map((a) => a.payload.trigger);
expect(triggers).toContain('celebration');
expect(triggers).toContain('concern');
});
it('does not emit before the window closes', () => {
const received = [];
protocol.on('emote', (a) => received.push(a));
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.5 } });
vi.advanceTimersByTime(100);
expect(received).toHaveLength(0);
});
it('a 1000-event burst produces one emitted event per trigger', () => {
const received = [];
protocol.on('emote', (a) => received.push(a));
for (let i = 0; i < 1000; i++) {
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: Math.random() } });
}
vi.advanceTimersByTime(150);
expect(received).toHaveLength(1);
expect(protocol.droppedCount('emote')).toBe(999);
});
});
// ─── passthrough events ───────────────────────────────────────────────────
describe('speak — passthrough (no delay)', () => {
it('emits immediately', () => {
const received = [];
protocol.on('speak', (a) => received.push(a));
protocol.emit({ type: 'speak', payload: { text: 'hello', sentiment: 0.8 } });
expect(received).toHaveLength(1);
expect(received[0].payload.text).toBe('hello');
});
it('all speak events pass through in order', () => {
const received = [];
protocol.on('speak', (a) => received.push(a));
for (let i = 0; i < 4; i++) {
protocol.emit({ type: 'speak', payload: { text: `msg${i}`, sentiment: 0 } });
}
expect(received).toHaveLength(4);
expect(received.map((a) => a.payload.text)).toEqual(['msg0', 'msg1', 'msg2', 'msg3']);
});
it('droppedCount stays 0 for speak', () => {
protocol.emit({ type: 'speak', payload: { text: 'hi', sentiment: 0 } });
expect(protocol.droppedCount('speak')).toBe(0);
});
});
describe('think — passthrough', () => {
it('emits immediately without queuing', () => {
const received = [];
protocol.on('think', (a) => received.push(a));
protocol.emit({ type: 'think', payload: { thought: 'processing…' } });
expect(received).toHaveLength(1);
});
});
// ─── setThrottlePolicy override ───────────────────────────────────────────
describe('setThrottlePolicy override', () => {
it('can override gesture to passthrough', () => {
protocol.setThrottlePolicy('gesture', { mode: 'passthrough' });
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
protocol.emit({ type: 'gesture', payload: { name: 'nod' } });
expect(received).toHaveLength(2);
});
it('can set a custom throttle interval on gesture', () => {
protocol.setThrottlePolicy('gesture', { mode: 'throttle', leading: true, intervalMs: 200 });
const received = [];
protocol.on('gesture', (a) => received.push(a));
protocol.emit({ type: 'gesture', payload: { name: 'wave' } }); // fires
vi.advanceTimersByTime(150);
protocol.emit({ type: 'gesture', payload: { name: 'nod' } }); // dropped (150 < 200)
vi.advanceTimersByTime(60);
protocol.emit({ type: 'gesture', payload: { name: 'shrug' } }); // fires (210 >= 200)
expect(received).toHaveLength(2);
expect(received[0].payload.name).toBe('wave');
expect(received[1].payload.name).toBe('shrug');
});
it('can override emote to passthrough', () => {
protocol.setThrottlePolicy('emote', { mode: 'passthrough' });
const received = [];
protocol.on('emote', (a) => received.push(a));
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.5 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.9 } });
expect(received).toHaveLength(2);
});
it('cancels pending debounce timer when policy is replaced', () => {
const received = [];
protocol.on('look-at', (a) => received.push(a));
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
// Replace policy before timer fires
protocol.setThrottlePolicy('look-at', { mode: 'passthrough' });
vi.advanceTimersByTime(200);
// Pending event was cancelled; nothing emitted
expect(received).toHaveLength(0);
});
});
// ─── droppedCount accuracy ────────────────────────────────────────────────
describe('droppedCount accuracy', () => {
it('returns 0 before any events', () => {
expect(protocol.droppedCount('gesture')).toBe(0);
expect(protocol.droppedCount('emote')).toBe(0);
expect(protocol.droppedCount('look-at')).toBe(0);
expect(protocol.droppedCount('speak')).toBe(0);
});
it('accumulates across multiple drops for throttle', () => {
protocol.emit({ type: 'gesture', payload: { name: 'wave' } }); // emitted
protocol.emit({ type: 'gesture', payload: { name: 'nod' } }); // dropped
protocol.emit({ type: 'gesture', payload: { name: 'shrug' } }); // dropped
protocol.emit({ type: 'gesture', payload: { name: 'point' } }); // dropped
expect(protocol.droppedCount('gesture')).toBe(3);
});
it('does not count passthrough events as dropped', () => {
protocol.emit({ type: 'speak', payload: { text: 'a', sentiment: 0 } });
protocol.emit({ type: 'speak', payload: { text: 'b', sentiment: 0 } });
protocol.emit({ type: 'speak', payload: { text: 'c', sentiment: 0 } });
expect(protocol.droppedCount('speak')).toBe(0);
});
});
// ─── wildcard subscription ────────────────────────────────────────────────
describe("wildcard '*' subscription", () => {
it('sees only emitted events, not dropped ones', () => {
const wildcardReceived = [];
protocol.on('*', (a) => wildcardReceived.push(a));
// gesture: leading throttle → 1 emitted, 2 dropped
protocol.emit({ type: 'gesture', payload: { name: 'wave' } });
protocol.emit({ type: 'gesture', payload: { name: 'nod' } });
protocol.emit({ type: 'gesture', payload: { name: 'shrug' } });
// speak: passthrough → 1 emitted
protocol.emit({ type: 'speak', payload: { text: 'hi', sentiment: 0 } });
// look-at: debounced → emits after 100 ms
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
vi.advanceTimersByTime(100);
const byType = (t) => wildcardReceived.filter((a) => a.type === t);
expect(byType('gesture')).toHaveLength(1);
expect(byType('speak')).toHaveLength(1);
expect(byType('look-at')).toHaveLength(1);
});
it('does not see emote events merged into a bucket', () => {
const wildcardReceived = [];
protocol.on('*', (a) => wildcardReceived.push(a));
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.5 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.9 } });
vi.advanceTimersByTime(150);
const emoteEvents = wildcardReceived.filter((a) => a.type === 'emote');
expect(emoteEvents).toHaveLength(1);
expect(emoteEvents[0].payload.weight).toBe(0.9);
});
});
// ─── history ring buffer ──────────────────────────────────────────────────
describe('history ring buffer', () => {
it('records emitted events', () => {
protocol.emit({ type: 'speak', payload: { text: 'hello', sentiment: 0 } });
expect(protocol.history).toHaveLength(1);
expect(protocol.history[0].type).toBe('speak');
});
it('does not record dropped throttle events', () => {
protocol.emit({ type: 'gesture', payload: { name: 'wave' } }); // emitted
protocol.emit({ type: 'gesture', payload: { name: 'nod' } }); // dropped
expect(protocol.history.filter((a) => a.type === 'gesture')).toHaveLength(1);
});
it('records debounce event only after the timer fires', () => {
protocol.emit({ type: 'look-at', payload: { target: 'model' } });
expect(protocol.history.filter((a) => a.type === 'look-at')).toHaveLength(0);
vi.advanceTimersByTime(100);
expect(protocol.history.filter((a) => a.type === 'look-at')).toHaveLength(1);
});
it('records coalesced emote only after the window closes', () => {
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.3 } });
protocol.emit({ type: 'emote', payload: { trigger: 'celebration', weight: 0.9 } });
expect(protocol.history.filter((a) => a.type === 'emote')).toHaveLength(0);
vi.advanceTimersByTime(150);
const emoteHistory = protocol.history.filter((a) => a.type === 'emote');
expect(emoteHistory).toHaveLength(1);
expect(emoteHistory[0].payload.weight).toBe(0.9);
});
});
});