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
// @vitest-environment jsdom
//
// Core-path coverage for @three-ws/chat-plugin's host-side AgentBridge
// (chat-plugin/src/bridge.ts): the v1 postMessage envelope a LobeChat /
// SperaxOS host uses to drive the embedded avatar iframe. Verifies the
// ready handshake, request/response resolution, pre-ready queueing, the
// legacy boot.js resize channel, and pending-request rejection on unmount.
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { AgentBridge } from '../chat-plugin/src/bridge.ts';
describe('AgentBridge (chat-plugin host bridge, wire protocol v1)', () => {
let frame;
let iframeRef;
let posted;
let bridge;
beforeEach(() => {
frame = document.createElement('iframe');
document.body.appendChild(frame);
posted = [];
vi.spyOn(frame.contentWindow, 'postMessage').mockImplementation((msg) => {
posted.push(msg);
});
iframeRef = { current: frame };
});
afterEach(() => {
bridge?.unmount();
frame.remove();
});
// Deliver an iframe-side envelope to the bridge, with event.source pinned
// to the frame's contentWindow (the bridge drops messages from any other
// source once the frame is mounted).
function iframeSend(env) {
const ev = new MessageEvent('message', { data: env });
Object.defineProperty(ev, 'source', { value: frame.contentWindow });
window.dispatchEvent(ev);
}
function ready(capabilities = ['speak', 'gesture', 'emote']) {
iframeSend({
v: 1,
source: 'agent-3d',
id: 'evt-ready',
kind: 'event',
op: 'ready',
payload: { agentId: 'agent-1', capabilities },
});
}
it('fires onReady and flushes queued requests once the iframe signals ready', async () => {
const onReady = vi.fn();
bridge = new AgentBridge({ agentId: 'agent-1', iframeRef, onReady });
bridge.mount();
// Requested before the handshake: must queue, not transmit.
const speakP = bridge.speak('hello', { sentiment: 0.5 });
expect(posted).toHaveLength(0);
ready();
expect(onReady).toHaveBeenCalledWith({
agentId: 'agent-1',
capabilities: ['speak', 'gesture', 'emote'],
});
// The queued speak flushed as a v1 agent-host request envelope.
const speakEnv = posted.find((m) => m.op === 'speak');
expect(speakEnv).toMatchObject({
v: 1,
source: 'agent-host',
kind: 'request',
payload: { text: 'hello', sentiment: 0.5 },
});
expect(typeof speakEnv.id).toBe('string');
// Responding with inReplyTo resolves the caller's promise.
iframeSend({
v: 1,
source: 'agent-3d',
id: 'resp-1',
inReplyTo: speakEnv.id,
kind: 'response',
op: 'speak',
payload: { ok: true },
});
await expect(speakP).resolves.toEqual({ ok: true });
});
it('transmits gesture/emote/setAgent immediately after ready, with defaults applied', () => {
bridge = new AgentBridge({ agentId: 'agent-1', iframeRef });
bridge.mount();
ready();
posted.length = 0;
bridge.gesture('wave').catch(() => undefined);
bridge.emote({ trigger: 'joy' }).catch(() => undefined);
bridge.setAgent('agent-2').catch(() => undefined);
expect(posted.map((m) => m.op)).toEqual(['gesture', 'emote', 'setAgent']);
expect(posted[0].payload).toEqual({ name: 'wave' });
expect(posted[1].payload).toEqual({ trigger: 'joy', weight: 1 });
expect(posted[2].payload).toEqual({ agentId: 'agent-2' });
});
it('ignores envelopes not sourced from the mounted iframe', () => {
const onReady = vi.fn();
bridge = new AgentBridge({ agentId: 'agent-1', iframeRef, onReady });
bridge.mount();
// No pinned source: event.source is null, not frame.contentWindow.
window.dispatchEvent(
new MessageEvent('message', {
data: {
v: 1,
source: 'agent-3d',
id: 'evt-x',
kind: 'event',
op: 'ready',
payload: { agentId: 'spoofed', capabilities: [] },
},
}),
);
expect(onReady).not.toHaveBeenCalled();
});
it('handles the legacy boot.js channel: embed:resize drives onResize, embed:ready drives onReady', () => {
const onReady = vi.fn();
const onResize = vi.fn();
bridge = new AgentBridge({ agentId: 'agent-1', iframeRef, onReady, onResize });
bridge.mount();
iframeSend({ ns: '3d-agent', type: 'embed:resize', payload: { height: 512 } });
expect(onResize).toHaveBeenCalledWith(512);
iframeSend({ ns: '3d-agent', type: 'embed:ready', payload: { capabilities: ['speak'] } });
expect(onReady).toHaveBeenCalledWith({ agentId: 'agent-1', capabilities: ['speak'] });
});
it('rejects every pending request on unmount', async () => {
bridge = new AgentBridge({ agentId: 'agent-1', iframeRef });
bridge.mount();
ready();
const p = bridge.speak('bye');
bridge.unmount();
await expect(p).rejects.toThrow('Bridge unmounted');
});
});