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
// @three-ws/create-agent: the one-command path from a sentence to a rigged 3D
// character.
//
// The network half is exercised through an injected fetch (the real free lane
// takes minutes and costs GPU time); the file half runs against a real temp
// directory, because "it wrote a project you can open" is the whole promise.
import { describe, it, expect, vi } from 'vitest';
import { mkdtemp, readFile, readdir } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { parseArgs } from '../packages/create-agent/src/args.js';
import { readForgeResult, callForge, ForgeError } from '../packages/create-agent/src/forge.js';
import {
slugify,
titleFrom,
embedSnippet,
demoPage,
projectFiles,
LOADER_URL,
} from '../packages/create-agent/src/scaffold.js';
import { createAgent } from '../packages/create-agent/src/index.js';
const RESULT = {
kind: 'avatar',
glbUrl: 'https://three.ws/cdn/creations/abc/rigged.glb',
viewerUrl: 'https://three.ws/viewer?src=abc',
studioUrl: 'https://three.ws/studio/abc',
rigged: true,
backend: 'hunyuan3d',
durationMs: 84_000,
};
function rpcOk(structured = RESULT) {
return {
ok: true,
status: 200,
json: async () => ({ jsonrpc: '2.0', id: 1, result: { structuredContent: structured } }),
};
}
describe('parseArgs', () => {
it('takes the description as bare words, so quoting is optional', () => {
expect(parseArgs(['a', 'friendly', 'astronaut']).prompt).toBe('a friendly astronaut');
});
it('defaults to a rigged humanoid with a local model file', () => {
const opts = parseArgs(['a knight']);
expect(opts.rig).toBe(true);
expect(opts.download).toBe(true);
});
it('reads every documented flag', () => {
const opts = parseArgs([
'a knight',
'--out',
'./k',
'--name',
'Sir',
'--object',
'--no-download',
'--json',
'--origin',
'http://localhost:3000',
]);
expect(opts).toMatchObject({
prompt: 'a knight',
out: './k',
name: 'Sir',
rig: false,
download: false,
json: true,
origin: 'http://localhost:3000',
});
});
it('flags an unknown option rather than silently ignoring it', () => {
expect(parseArgs(['a knight', '--turbo']).unknown).toBe('--turbo');
});
it('accepts a reference image instead of a description', () => {
expect(parseArgs(['--photo', 'https://example.com/me.jpg']).imageUrl).toBe(
'https://example.com/me.jpg',
);
});
});
describe('readForgeResult', () => {
it('normalizes the tool payload into one shape', () => {
const body = { result: { structuredContent: RESULT } };
expect(readForgeResult(body, { kind: 'avatar' })).toMatchObject({
glbUrl: RESULT.glbUrl,
rigged: true,
backend: 'hunyuan3d',
});
});
it('accepts riggedGlbUrl, which the avatar lane returns instead', () => {
const body = { result: { riggedGlbUrl: 'https://three.ws/x.glb' } };
expect(readForgeResult(body, { kind: 'avatar' }).glbUrl).toBe('https://three.ws/x.glb');
});
it('synthesizes a viewer link when the tool did not send one', () => {
const body = { result: { glbUrl: 'https://three.ws/x.glb' } };
expect(readForgeResult(body, { kind: 'model' }).viewerUrl).toBe(
'https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fx.glb',
);
});
it('surfaces a JSON-RPC error as a readable failure', () => {
expect(() => readForgeResult({ error: { message: 'prompt rejected' } }, { kind: 'avatar' })).toThrow(
/prompt rejected/,
);
});
it('refuses a response with no model rather than scaffolding an empty project', () => {
expect(() => readForgeResult({ result: {} }, { kind: 'avatar' })).toThrow(/without a model URL/);
});
});
describe('callForge', () => {
it('calls the public JSON-RPC endpoint with the tool and arguments', async () => {
const fetchImpl = vi.fn(async () => rpcOk());
await callForge({ tool: 'forge_avatar', args: { prompt: 'a knight' }, fetchImpl });
const [url, init] = fetchImpl.mock.calls[0];
expect(String(url)).toBe('https://three.ws/api/mcp-studio');
expect(JSON.parse(init.body)).toMatchObject({
method: 'tools/call',
params: { name: 'forge_avatar', arguments: { prompt: 'a knight' } },
});
expect(init.signal).toBeDefined();
});
it('reports the phases a caller can actually show', async () => {
const seen = [];
await callForge({
tool: 'forge_avatar',
args: { prompt: 'a knight' },
fetchImpl: async () => rpcOk(),
onProgress: (e) => seen.push(e.phase),
});
expect(seen).toEqual(['submitted', 'done']);
});
it('turns an HTTP failure into a ForgeError carrying the status', async () => {
const fetchImpl = async () => ({ ok: false, status: 503, json: async () => ({}) });
await expect(callForge({ tool: 'forge_free', args: {}, fetchImpl })).rejects.toMatchObject({
name: 'ForgeError',
code: 'http_503',
});
});
it('explains an unreachable host instead of leaking a socket error', async () => {
const fetchImpl = async () => {
throw new Error('ENOTFOUND');
};
await expect(callForge({ tool: 'forge_free', args: {}, fetchImpl })).rejects.toThrow(
/could not reach three\.ws/,
);
});
});
describe('scaffold', () => {
it('derives a short directory name and a display name from the prompt', () => {
expect(slugify('a friendly cartoon astronaut in a glossy white suit')).toBe(
'a-friendly-cartoon-astronaut',
);
expect(titleFrom('a friendly cartoon astronaut')).toBe('Friendly Cartoon Astronaut');
// A name is the subject, not the first four words of the sentence: the
// real runs produced "Friendly Cartoon Astronaut In" and
// "Knight With Worn Steel" before this cut at the first preposition.
expect(titleFrom('a friendly cartoon astronaut in a glossy white suit')).toBe(
'Friendly Cartoon Astronaut',
);
expect(titleFrom('a knight with worn steel armor')).toBe('Knight');
expect(slugify('!!!')).toBe('agent');
expect(titleFrom('')).toBe('Agent');
});
it('emits an embed snippet that is the whole integration', () => {
const snippet = embedSnippet({ name: 'Astro', glbUrl: 'https://three.ws/a.glb' });
expect(snippet).toContain(LOADER_URL);
expect(snippet).toContain('body="https://three.ws/a.glb"');
expect(snippet).toContain('name="Astro"');
});
it('escapes a prompt that would otherwise break the generated page', () => {
const page = demoPage({
name: '<img onerror=alert(1)>',
prompt: 'a "quoted" & dangerous <script>',
glbUrl: 'https://three.ws/a.glb',
viewerUrl: 'https://three.ws/viewer',
rigged: true,
});
expect(page).not.toContain('<script>a');
expect(page).toContain('<img onerror=alert(1)>');
expect(page).toContain('&');
});
it('points the demo page at the hosted model so a double click still works', () => {
const page = demoPage({
name: 'Astro',
prompt: 'astronaut',
glbUrl: 'https://three.ws/a.glb',
viewerUrl: 'https://three.ws/viewer',
rigged: true,
});
expect(page).toContain('body="https://three.ws/a.glb"');
expect(page).not.toContain('body="agent.glb"');
});
it('writes three files, and says in the README which is which', () => {
const files = projectFiles({ name: 'Astro', prompt: 'astronaut', result: RESULT, dir: 'astro' });
expect(Object.keys(files).sort()).toEqual(['README.md', 'agent.json', 'index.html']);
expect(JSON.parse(files['agent.json'])).toMatchObject({
name: 'Astro',
prompt: 'astronaut',
glbUrl: RESULT.glbUrl,
rigged: true,
madeWith: '@three-ws/create-agent',
});
expect(files['README.md']).toContain('agent.glb');
});
});
describe('createAgent', () => {
it('refuses to call the forge with nothing to make', async () => {
await expect(createAgent({})).rejects.toThrow(/describe what to make/);
await expect(createAgent({ prompt: 'ab' })).rejects.toThrow(/at least 3 characters/);
await expect(createAgent({ imageUrl: 'http://example.com/x.jpg' })).rejects.toThrow(
/public https url/,
);
});
it('writes a runnable project, model included', async () => {
const out = join(await mkdtemp(join(tmpdir(), 'create-agent-')), 'astro');
const glb = Buffer.from('glTF binary bytes');
const fetchImpl = vi.fn(async (url) =>
String(url).endsWith('.glb')
? { ok: true, status: 200, arrayBuffer: async () => glb }
: rpcOk(),
);
const made = await createAgent({ prompt: 'a friendly astronaut', out, fetchImpl });
expect(made.name).toBe('Friendly Astronaut');
expect(made.bytes).toBe(glb.length);
expect((await readdir(out)).sort()).toEqual(['README.md', 'agent.glb', 'agent.json', 'index.html']);
expect(await readFile(join(out, 'agent.glb'))).toEqual(glb);
expect(await readFile(join(out, 'index.html'), 'utf8')).toContain(RESULT.glbUrl);
});
it('skips the download when asked, and still writes the project', async () => {
const out = join(await mkdtemp(join(tmpdir(), 'create-agent-')), 'astro');
const fetchImpl = vi.fn(async () => rpcOk());
const made = await createAgent({ prompt: 'a knight', out, download: false, fetchImpl });
expect(made.bytes).toBe(0);
expect(await readdir(out)).not.toContain('agent.glb');
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
it('routes an object to the free mesh lane instead of the rigging lane', async () => {
const out = join(await mkdtemp(join(tmpdir(), 'create-agent-')), 'frog');
const fetchImpl = vi.fn(async () => rpcOk({ ...RESULT, kind: 'model', rigged: false }));
await createAgent({ prompt: 'a ceramic frog', out, rig: false, download: false, fetchImpl });
expect(JSON.parse(fetchImpl.mock.calls[0][1].body).params).toMatchObject({
name: 'forge_free',
arguments: { prompt: 'a ceramic frog', tier: 'draft' },
});
});
it('sends a reference image as image_url on the avatar lane', async () => {
const out = join(await mkdtemp(join(tmpdir(), 'create-agent-')), 'me');
const fetchImpl = vi.fn(async () => rpcOk());
await createAgent({
imageUrl: 'https://example.com/me.jpg',
out,
download: false,
fetchImpl,
});
expect(JSON.parse(fetchImpl.mock.calls[0][1].body).params.arguments).toEqual({
image_url: 'https://example.com/me.jpg',
});
});
it('propagates a forge failure instead of leaving half a project', async () => {
const out = join(await mkdtemp(join(tmpdir(), 'create-agent-')), 'nope');
const fetchImpl = async () => ({
ok: true,
status: 200,
json: async () => ({ error: { message: 'safety filter' } }),
});
await expect(createAgent({ prompt: 'a knight', out, fetchImpl })).rejects.toBeInstanceOf(
ForgeError,
);
await expect(readdir(out)).rejects.toThrow();
});
});
describe('a job that outlives the inline wait', () => {
// The normal path for a rigged character: the endpoint hands back a public
// poll handle instead of a model, and the client has to collect it.
function pendingRpc(stage, jobId = 'job_1') {
return {
ok: true,
status: 200,
json: async () => ({
result: {
structuredContent: {
status: 'pending',
jobId,
pollUrl: `https://three.ws/api/gpt-forge?job=${jobId}`,
stage,
etaRemainingSeconds: 40,
},
},
}),
};
}
const jobDone = (glb) => ({ ok: true, status: 200, json: async () => ({ status: 'done', glb_url: glb }) });
const jobQueued = { ok: true, status: 200, json: async () => ({ status: 'queued' }) };
it('reads a pending answer as a job to collect, not as a failure', () => {
const body = { result: { structuredContent: { status: 'pending', jobId: 'j', pollUrl: 'p', stage: 'rig' } } };
expect(readForgeResult(body, { kind: 'avatar' })).toMatchObject({
pending: true,
jobId: 'j',
stage: 'rig',
});
});
it('polls the job until it is done, through a queued tick', async () => {
const calls = [];
const fetchImpl = vi.fn(async (url) => {
calls.push(String(url));
if (String(url).includes('mcp-studio')) return pendingRpc('rig');
return calls.filter((c) => c.includes('gpt-forge')).length === 1
? jobQueued
: jobDone('https://three.ws/cdn/x/rigged.glb');
});
const made = await callForge({ tool: 'forge_avatar', args: { prompt: 'a knight' }, fetchImpl });
expect(made).toMatchObject({ glbUrl: 'https://three.ws/cdn/x/rigged.glb', rigged: true });
}, 20_000);
it('rigs a collected mesh instead of handing back a T-posed figure', async () => {
const tools = [];
const fetchImpl = vi.fn(async (url, init) => {
if (String(url).includes('mcp-studio')) {
const name = JSON.parse(init.body).params.name;
tools.push(name);
return name === 'forge_avatar'
? pendingRpc('mesh')
: {
ok: true,
status: 200,
json: async () => ({
result: { structuredContent: { glbUrl: 'https://three.ws/cdn/x/rigged.glb', kind: 'avatar', rigged: true } },
}),
};
}
return jobDone('https://three.ws/cdn/x/mesh.glb');
});
const made = await callForge({ tool: 'forge_avatar', args: { prompt: 'a knight' }, fetchImpl });
expect(tools).toEqual(['forge_avatar', 'rig_mesh']);
expect(made).toMatchObject({ glbUrl: 'https://three.ws/cdn/x/rigged.glb', rigged: true });
}, 20_000);
it('surfaces a failed job with its reason', async () => {
const fetchImpl = vi.fn(async (url) =>
String(url).includes('mcp-studio')
? pendingRpc('rig')
: { ok: true, status: 200, json: async () => ({ status: 'failed', error: 'the rigger could not find a spine' }) },
);
await expect(callForge({ tool: 'forge_avatar', args: {}, fetchImpl })).rejects.toThrow(
/could not find a spine/,
);
}, 20_000);
});