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
// Real HTTP access to the three.ws Concierge API and to arbitrary web pages
// concierge_ask grounds its answers in. No mocks, no fixtures, every call is a
// live request. Errors are normalized into a single shape so tool handlers can
// surface a clean message + status to the MCP client.
import { THREE_WS_BASE, HTTP_TIMEOUT_MS, PAGE_FETCH_TIMEOUT_MS, USER_AGENT } from '../config.js';
const MAX_PAGE_BYTES = 2_000_000; // never buffer more than ~2MB of HTML
/**
* Fetch a web page's HTML for grounding. Follows redirects (fetch default),
* enforces a byte cap and timeout, and rejects non-HTML responses.
* @param {string} url http(s) URL
* @returns {Promise<string>} the HTML text (truncated to the byte cap)
*/
export async function fetchPage(url) {
let parsed;
try {
parsed = new URL(url);
} catch {
throw Object.assign(new Error(`not a valid URL: ${url}`), { code: 'bad_request' });
}
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
throw Object.assign(new Error(`only http(s) URLs are supported (got ${parsed.protocol})`), {
code: 'bad_request',
});
}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), PAGE_FETCH_TIMEOUT_MS);
let res;
try {
res = await fetch(parsed, {
headers: { accept: 'text/html,application/xhtml+xml', 'user-agent': USER_AGENT },
signal: controller.signal,
redirect: 'follow',
});
} catch (err) {
clearTimeout(timer);
if (err?.name === 'AbortError') {
throw Object.assign(new Error(`fetching ${url} timed out after ${PAGE_FETCH_TIMEOUT_MS}ms`), {
code: 'timeout',
});
}
throw Object.assign(new Error(`failed to fetch ${url}: ${err?.message || err}`), {
code: 'network_error',
});
}
clearTimeout(timer);
if (!res.ok) {
throw Object.assign(new Error(`${url} returned HTTP ${res.status}`), {
code: 'upstream_error',
status: res.status,
});
}
const ct = res.headers.get('content-type') || '';
if (ct && !/html|xml|text\/plain/i.test(ct)) {
throw Object.assign(new Error(`${url} is not an HTML page (content-type: ${ct})`), {
code: 'unsupported_media',
});
}
// Read with a byte cap so a giant page can't exhaust memory.
const reader = res.body?.getReader();
if (!reader) return await res.text();
const decoder = new TextDecoder();
let html = '';
let bytes = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
bytes += value.length;
html += decoder.decode(value, { stream: true });
if (bytes >= MAX_PAGE_BYTES) {
try {
await reader.cancel();
} catch {
/* already closed */
}
break;
}
}
html += decoder.decode();
return html;
}
/**
* Ask the three.ws Concierge a question and accumulate the streamed answer.
* Posts the same body the browser widget posts and reads the SSE response.
*
* @param {{ question: string, site: object,
* history?: {role:'user'|'assistant', content:string}[],
* persona?: string, lang?: string }} params
* @returns {Promise<{ answer: string, provider: string|null, model: string|null }>}
*/
export async function askConcierge({ question, site, history = [], persona, lang }) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
let res;
try {
res = await fetch(`${THREE_WS_BASE}/api/concierge`, {
method: 'POST',
headers: {
'content-type': 'application/json',
accept: 'text/event-stream',
'user-agent': USER_AGENT,
},
body: JSON.stringify({ message: question, history, site, persona, lang }),
signal: controller.signal,
});
} catch (err) {
clearTimeout(timer);
if (err?.name === 'AbortError') {
throw Object.assign(new Error(`concierge answer timed out after ${HTTP_TIMEOUT_MS}ms`), {
code: 'timeout',
});
}
throw Object.assign(new Error(`concierge request failed: ${err?.message || err}`), {
code: 'network_error',
});
}
if (!res.ok) {
clearTimeout(timer);
let detail = '';
try {
detail = (await res.json())?.message || '';
} catch {
/* non-JSON error body */
}
throw Object.assign(new Error(detail || `concierge returned HTTP ${res.status}`), {
code: 'upstream_error',
status: res.status,
});
}
// Read the SSE stream: accumulate `chunk` text, capture `done` metadata.
let answer = '';
let provider = null;
let model = null;
let streamError = null;
let buf = '';
const decoder = new TextDecoder();
const reader = res.body.getReader();
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
let idx;
while ((idx = buf.indexOf('\n\n')) !== -1) {
const frame = buf.slice(0, idx);
buf = buf.slice(idx + 2);
const data = frame
.split('\n')
.filter((l) => l.startsWith('data:'))
.map((l) => l.slice(5).trim())
.join('\n');
if (!data || data === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(data);
} catch {
continue;
}
if (evt.type === 'chunk' && typeof evt.text === 'string') answer += evt.text;
else if (evt.type === 'done') {
provider = evt.provider ?? provider;
model = evt.model ?? model;
} else if (evt.type === 'error') {
streamError = evt.error || 'concierge stream error';
}
}
}
} finally {
clearTimeout(timer);
}
if (streamError && !answer) {
throw Object.assign(new Error(streamError), { code: 'stream_error' });
}
return { answer: answer.trim(), provider, model };
}