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
// Sources: where messages come from.
//
// A source is an object `{ name, start(emit) => stop }`. It calls `emit(raw)`
// with anything message-shaped (the rules engine's `toMessage` normalises it)
// and returns a function that tears itself down. That is the entire contract,
// so an integrator can write one in five lines for a feed nobody here has
// heard of, and the three below cover almost everything else:
//
// pollSource any JSON endpoint, on an interval, with visibility backoff
// sseSource any EventSource endpoint (server-sent events)
// railSource the three.ws delivery rail: your terminal, CI, or an agent
// POSTs, and the browser you are looking at says it out loud
/**
* Poll a JSON endpoint and emit what it returns.
*
* Polling stops while the tab is hidden and resumes (with an immediate read) on
* return, because a poll nobody is looking at is a request nobody needed.
*
* @param {object} opts
* @param {string} opts.url endpoint returning an array, or an object with an array
* @param {number} [opts.intervalMs=30000]
* @param {(body:any)=>any[]} [opts.select] pull the array out of the response
* @param {(item:any)=>any} [opts.map] shape one item into a message
* @param {RequestInit} [opts.fetchOptions] credentials, headers, and the rest
* @param {typeof fetch} [opts.fetchImpl]
*/
export function pollSource({
url,
intervalMs = 30_000,
select = defaultSelect,
map = (x) => x,
fetchOptions = { credentials: 'include' },
fetchImpl = globalThis.fetch?.bind(globalThis),
}) {
return {
name: `poll:${url}`,
start(emit) {
let timer = 0;
let stopped = false;
const tick = async () => {
if (stopped) return;
try {
const res = await fetchImpl(url, fetchOptions);
if (res.ok) {
const body = await res.json();
for (const item of select(body) || []) emit(map(item));
}
} catch {
/* a network blip is not an error worth surfacing to a human */
}
schedule();
};
const schedule = () => {
clearTimeout(timer);
if (stopped) return;
timer = setTimeout(tick, intervalMs);
};
const onVisibility = () => {
if (globalThis.document?.visibilityState === 'visible') tick();
else clearTimeout(timer);
};
globalThis.document?.addEventListener?.('visibilitychange', onVisibility);
tick();
return () => {
stopped = true;
clearTimeout(timer);
globalThis.document?.removeEventListener?.('visibilitychange', onVisibility);
};
},
};
}
function defaultSelect(body) {
if (Array.isArray(body)) return body;
for (const key of ['messages', 'items', 'notifications', 'events', 'data']) {
if (Array.isArray(body?.[key])) return body[key];
}
return [];
}
/**
* Subscribe to a server-sent-events endpoint.
* @param {object} opts
* @param {string} opts.url
* @param {string[]} [opts.events=['message']] event names to listen for
* @param {boolean} [opts.withCredentials=true]
* @param {(data:any)=>any} [opts.map]
* @param {() => void} [opts.onOpen] the stream connected
* @param {(err:any) => void} [opts.onError] the stream dropped; EventSource
* reconnects on its own, so this is for status, not for recovery
* @param {typeof EventSource} [opts.EventSourceImpl]
*/
export function sseSource({
url,
events = ['message'],
withCredentials = true,
map = (x) => x,
onOpen,
onError,
EventSourceImpl = globalThis.EventSource,
}) {
return {
name: `sse:${url}`,
start(emit) {
if (!EventSourceImpl) {
onError?.(new Error('EventSource is unavailable in this environment'));
return () => {};
}
const es = new EventSourceImpl(url, { withCredentials });
if (onOpen) es.addEventListener('open', () => onOpen());
if (onError) es.addEventListener('error', (e) => onError(e));
const handler = (e) => {
let payload = e.data;
try {
payload = JSON.parse(e.data);
} catch {
/* a plain string line is a valid message */
}
emit(map(payload));
};
for (const name of events) es.addEventListener(name, handler);
return () => {
for (const name of events) es.removeEventListener(name, handler);
es.close();
};
},
};
}
/**
* The three.ws delivery rail.
*
* Anything that can make an HTTPS request (a deploy script, a CI job, a cron,
* an AI agent holding an API key) POSTs to /api/herald/announce, and this
* source hands it to the avatar in the browser the human is actually looking
* at. The stream is per-account and session-authenticated: nobody can address
* your avatar but you and the keys you issued.
*
* @param {object} [opts]
* @param {string} [opts.origin='https://three.ws'] rail origin
* @param {() => void} [opts.onOpen]
* @param {(err:any) => void} [opts.onError]
* @param {typeof EventSource} [opts.EventSourceImpl]
*/
export function railSource({ origin = 'https://three.ws', onOpen, onError, EventSourceImpl } = {}) {
const base = String(origin || '').replace(/\/$/, '');
const source = sseSource({
url: `${base}/api/herald/stream`,
events: ['announce'],
onOpen,
onError,
EventSourceImpl,
});
return { ...source, name: 'rail' };
}
/**
* A source fed by hand. `herald.announce()` uses one of these internally; it is
* exported because bridging an in-page event bus is a two-liner with it.
*/
export function manualSource() {
let push = null;
const pending = [];
return {
name: 'manual',
start(emit) {
push = emit;
while (pending.length) emit(pending.shift());
return () => {
push = null;
};
},
/** Feed a message in. Safe before start(): it is queued, not lost. */
send(message) {
if (push) push(message);
else pending.push(message);
},
};
}