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
// Automation mode against a real local HTTP server and a real local JSON-RPC
// node: every documented exit code is triggered, --json keeps stdout to one
// JSON document, --non-interactive never prompts, and the HTML report is a
// single self-contained file.
import fs from 'node:fs';
import http from 'node:http';
import os from 'node:os';
import path from 'node:path';
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import { generateKeyPairSigner } from '@solana/kit';
import { main } from '../src/cli.js';
import { EXIT_CODES, exitCodeFor } from '../src/automation.js';
import { ApiError } from '../src/http.js';
import { buildRunReport } from '../src/report/run-report.js';
import { createKeystore } from '../src/pay/keystore.js';
import { USDC_MAINNET } from '../src/pay/permissions.js';
const AGENT = '11111111-1111-4111-8111-111111111111';
const RUN = '22222222-2222-4222-8222-222222222222';
const GOAL = 'Watch the pool and report if liquidity drops <b>below</b> 50k';
const HEAD = 'a'.repeat(64);
const run = {
id: RUN,
agentId: AGENT,
goal: GOAL,
status: 'completed',
model: 'fixture-model',
maxSteps: 8,
budget: { creditsUsd: 0.5, usd: 0 },
spent: { creditsUsd: 0.0123, usd: 0 },
result: 'Liquidity held above 50k for the whole window.',
summary: 'Completed after 2 model turns.',
createdAt: '2026-10-20T10:00:00.000Z',
startedAt: '2026-10-20T10:00:01.000Z',
finishedAt: '2026-10-20T10:00:41.000Z',
};
const steps = [
{ seq: 1, kind: 'status', output: { status: 'queued' }, receipt: null },
{ seq: 2, kind: 'model_call', model: 'fixture-model', output: { content: 'I will read the pool first.', toolCalls: [{ name: 'get_pool' }] }, receipt: 'b'.repeat(64), at: run.startedAt },
{ seq: 3, kind: 'tool_call', tool: 'get_pool', input: { pool: 'synthetic-pool' }, receipt: 'c'.repeat(64) },
{ seq: 4, kind: 'tool_result', tool: 'get_pool', input: { pool: 'synthetic-pool' }, output: { liquidityUsd: 61000 }, receipt: 'd'.repeat(64), latencyMs: 120 },
{ seq: 5, kind: 'model_call', model: 'fixture-model', output: { content: 'Liquidity is fine; trying a swap quote.', toolCalls: [{ name: 'swap_quote' }] }, receipt: 'e'.repeat(64) },
{ seq: 6, kind: 'tool_blocked', tool: 'swap_quote', input: { amount: 1 }, output: { reason: 'not in the allowed tool set' }, receipt: 'f'.repeat(64) },
{ seq: 7, kind: 'final', output: { result: run.result }, receipt: HEAD },
];
const toolTraces = [
{ tool: 'get_pool', input: { pool: 'synthetic-pool' }, callSeq: 3, status: 'ok', output: { liquidityUsd: 61000 }, resultSeq: 4, receipt: 'd'.repeat(64), latencyMs: 120 },
{ tool: 'swap_quote', input: { amount: 1 }, callSeq: null, status: 'blocked', output: { reason: 'not in the allowed tool set' }, resultSeq: 6, receipt: 'f'.repeat(64), latencyMs: null },
];
const trail = { agent_id: AGENT, status: 'verified_unanchored', ok: true, chain: { ok: true, count: 3, head_hash: '9'.repeat(64) }, anchor: null, checked_at: '2026-10-20T11:00:00.000Z' };
let server;
let origin;
let rpcServer;
let rpcUrl;
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'three-ws-automation-'));
function reply(res, status, body) {
res.writeHead(status, { 'content-type': 'application/json' });
res.end(JSON.stringify(body));
}
beforeAll(async () => {
server = http.createServer((req, res) => {
const url = new URL(req.url, 'http://x');
const auth = req.headers.authorization || '';
if (url.pathname === '/api/skills/community/ext-skill') return reply(res, 200, { skill: { origin: 'external', name: 'Ext', slug: 'ext-skill', source: 'example/skills', ref: 'abc1234', license: 'MIT', tree_url: 'https://example.invalid/tree', import: { registry: 'r', skill: 's' } } });
if (url.pathname.endsWith('/decision-trail/verify')) return reply(res, 200, trail);
if (auth === 'Bearer sk_live_revoked') return reply(res, 401, { error: 'invalid_token', error_description: 'revoked' });
if (auth === 'Bearer sk_live_guarded') return reply(res, 403, { error: 'firewall_blocked', error_description: 'blocked by the trade firewall' });
if (auth === 'Bearer sk_live_pay') return reply(res, 402, { error: 'payment_required', error_description: 'upgrade your plan' });
if (auth !== 'Bearer sk_live_ok') return reply(res, 401, { error: 'unauthorized' });
if (url.pathname === `/api/agents/${AGENT}/custom-skills` && req.method === 'POST') return reply(res, 404, { error: 'not_found' });
if (url.pathname === '/api/agents' && req.method === 'POST') return reply(res, 201, { agent: { id: AGENT, name: 'x' } });
if (url.pathname === '/api/agents') return reply(res, 200, { agents: [{ id: AGENT, name: 'Scout', solana_address: 'SyntheticWalletAddress11111111111111111111111', avatar_id: 'av1' }] });
if (url.pathname === '/api/agents/balances') return reply(res, 200, { data: { [AGENT]: { sol: 1.5, usdc: 20, usd: 250 } } });
if (url.pathname === '/api/agent-run-replay' && url.searchParams.get('agent')) return reply(res, 200, { data: { runs: [run], hasMore: false, nextBefore: null } });
if (url.pathname === '/api/agent-run-replay' && url.searchParams.get('run') === RUN) {
return reply(res, 200, { data: { run, live: false, steps, toolTraces, receiptChain: { verified: true, checked: 6, brokenAt: null }, nextAfter: 7, hasMore: false } });
}
if (url.pathname === `/api/agents/${AGENT}/orders`) return reply(res, 200, { data: { orders: [{ id: 'o1', status: 'active', type: 'limit', side: 'buy', symbol: 'THREE' }], summary: { active: 1 } } });
return reply(res, 404, { error: 'not_found' });
});
await new Promise((r) => server.listen(0, '127.0.0.1', r));
origin = `http://127.0.0.1:${server.address().port}`;
rpcServer = http.createServer(async (req, res) => {
let body = '';
for await (const chunk of req) body += chunk;
const call = JSON.parse(body);
let result;
if (call.method === 'getBalance') result = { context: { slot: 1 }, value: 2_500_000_000 };
if (call.method === 'getTokenAccountsByOwner') {
result = { context: { slot: 1 }, value: [{ pubkey: 'x', account: { data: { parsed: { info: { tokenAmount: { amount: '7500000' } } } } } }] };
}
reply(res, 200, result === undefined ? { jsonrpc: '2.0', id: call.id, error: { code: -32601, message: 'unexpected' } } : { jsonrpc: '2.0', id: call.id, result });
});
await new Promise((r) => rpcServer.listen(0, '127.0.0.1', r));
rpcUrl = `http://127.0.0.1:${rpcServer.address().port}`;
});
afterAll(async () => {
await new Promise((r) => server.close(r));
await new Promise((r) => rpcServer.close(r));
});
afterEach(() => vi.restoreAllMocks());
function envWith(key, extra = {}) {
const home = fs.mkdtempSync(path.join(scratch, 'home-'));
const vars = { THREE_WS_NO_BROWSER: '1', NO_COLOR: '1', XDG_CONFIG_HOME: path.join(home, '.config'), ...extra };
if (key) vars.THREE_WS_API_KEY = key;
return { home, platform: 'linux', cwd: home, vars };
}
async function cli(argv, env) {
let out = '';
let err = '';
vi.spyOn(process.stdout, 'write').mockImplementation((c) => ((out += c.toString()), true));
vi.spyOn(process.stderr, 'write').mockImplementation((c) => ((err += c.toString()), true));
const code = await main(argv, env);
vi.restoreAllMocks();
return { code, out, err };
}
describe('exit-code table', () => {
it('0: success, with --json stdout a single document and stderr empty', async () => {
const r = await cli(['agents', 'list', '--json', '--origin', origin], envWith('sk_live_ok'));
expect(r.code).toBe(EXIT_CODES.OK);
expect(JSON.parse(r.out).agents).toHaveLength(1);
expect(r.out.trim().split('\n').filter((l) => l.startsWith('{')).length).toBe(1);
expect(r.err).toBe('');
});
it('1: an error with no better code (the server does not know the run)', async () => {
const r = await cli(['runs', 'get', '33333333-3333-4333-8333-333333333333', '--json', '--origin', origin], envWith('sk_live_ok'));
expect(r.code).toBe(EXIT_CODES.ERROR);
expect(JSON.parse(r.out)).toMatchObject({ error: 'not_found', exit: 1 });
});
it('2: usage, for an unknown flag, a missing agent, an unknown command and a bad run id', async () => {
const env = envWith('sk_live_ok');
expect((await cli(['agents', 'list', '--bogus'], env)).code).toBe(2);
expect((await cli(['frobnicate', '--json'], env)).code).toBe(2);
const noAgent = await cli(['runs', 'list', '--json', '--origin', origin], env);
expect(noAgent.code).toBe(2);
expect(JSON.parse(noAgent.out)).toMatchObject({ error: 'missing_input', exit: 2 });
expect((await cli(['runs', 'get', 'not-a-uuid', '--origin', origin], env)).code).toBe(2);
});
it('3: auth, with no credential and with a revoked key', async () => {
const none = await cli(['agents', 'list', '--json', '--origin', origin], envWith(null));
expect(none.code).toBe(EXIT_CODES.AUTH);
expect(JSON.parse(none.out).error).toBe('login_required');
expect((await cli(['agents', 'list', '--origin', origin], envWith('sk_live_revoked'))).code).toBe(3);
});
it('4: refused by a guard, from the server and from the external-skill confirmation', async () => {
const r = await cli(['agents', 'list', '--json', '--origin', origin], envWith('sk_live_guarded'));
expect(r.code).toBe(EXIT_CODES.GUARD);
expect(JSON.parse(r.out).error).toBe('firewall_blocked');
expect(exitCodeFor(new ApiError('x', { status: 403, code: 'spend_policy' }))).toBe(4);
});
it('5: payment required', async () => {
const r = await cli(['agents', 'list', '--json', '--origin', origin], envWith('sk_live_pay'));
expect(r.code).toBe(EXIT_CODES.PAYMENT);
expect(JSON.parse(r.out).exit).toBe(5);
});
it('6: network, for an unreachable host and for a server fault', async () => {
const dead = await cli(['agents', 'list', '--json', '--origin', 'http://127.0.0.1:1'], envWith('sk_live_ok'));
expect(dead.code).toBe(EXIT_CODES.NETWORK);
expect(JSON.parse(dead.out).error).toBe('error');
expect(exitCodeFor(new ApiError('x', { status: 503 }))).toBe(6);
expect(exitCodeFor(new ApiError('x', { status: 429 }))).toBe(6);
});
it('keeps pay\'s own exit codes untouched', () => {
expect(exitCodeFor(Object.assign(new Error('x'), { exit: 11 }))).toBe(11);
});
});
describe('stdout purity under --json', () => {
it('puts exactly one JSON document on stdout for every command, success and failure', async () => {
const env = envWith('sk_live_ok', { THREE_WS_SOLANA_RPC_URL: rpcUrl });
const argvs = [
['agents', 'list'],
['agents', 'get', 'Scout'],
['runs', 'list', '--agent', 'Scout'],
['runs', 'get', RUN],
['orders', 'list', '--agent', AGENT],
['wallet', 'balance', '--agent', AGENT],
['agents', 'get', 'nobody'],
['version'],
];
for (const argv of argvs) {
const r = await cli([...argv, '--json', '--origin', origin], env);
expect(() => JSON.parse(r.out), argv.join(' ')).not.toThrow();
}
});
it('reads the orders and run views from the real endpoints', async () => {
const env = envWith('sk_live_ok');
const orders = JSON.parse((await cli(['orders', 'list', '--agent', 'Scout', '--json', '--origin', origin], env)).out);
expect(orders.orders[0]).toMatchObject({ id: 'o1', symbol: 'THREE' });
const detail = JSON.parse((await cli(['runs', 'get', RUN, '--json', '--origin', origin], env)).out);
expect(detail.receiptChain).toMatchObject({ verified: true });
expect(detail.toolTraces).toHaveLength(2);
});
it('reads the local pay wallet balance from Solana RPC', async () => {
const env = envWith(null, { THREE_WS_SOLANA_RPC_URL: rpcUrl, THREE_WS_WALLET_PASSPHRASE: 'correct horse battery staple' });
const made = await createKeystore({ env }).init({ storage: 'file' });
const r = await cli(['wallet', 'balance', '--json'], env);
expect(r.code).toBe(0);
expect(JSON.parse(r.out)).toMatchObject({ source: 'pay-wallet', address: made.address, sol: 2.5, usdc: 7.5, network: 'mainnet' });
expect(USDC_MAINNET).toBeTruthy();
});
it('reads an agent wallet balance', async () => {
const r = await cli(['wallet', 'balance', '--agent', 'Scout', '--json', '--origin', origin], envWith('sk_live_ok'));
expect(JSON.parse(r.out)).toMatchObject({ source: 'agent-wallet', usdc: 20, sol: 1.5 });
});
});
describe('--non-interactive', () => {
it('never signs in with a browser: exit 3 and no request is made', async () => {
const spy = vi.fn();
const probe = http.createServer((req, res) => (spy(), reply(res, 500, {})));
await new Promise((r) => probe.listen(0, '127.0.0.1', r));
const o = `http://127.0.0.1:${probe.address().port}`;
const r = await cli(['login', '--non-interactive', '--json', '--origin', o], envWith(null));
await new Promise((res) => probe.close(res));
expect(r.code).toBe(3);
expect(JSON.parse(r.out).error).toBe('login_required');
expect(spy).not.toHaveBeenCalled();
});
it('treats missing input as a usage error instead of asking', async () => {
const r = await cli(['create', '--non-interactive', '--json', '--origin', origin], envWith('sk_live_ok'));
expect(r.code).toBe(2);
expect(JSON.parse(r.out).exit).toBe(2);
});
it('refuses an external skill install without --yes (exit 4), never asking', async () => {
const r2 = await cli(['skill', 'install', 'ext-skill', '--agent', AGENT, '--non-interactive', '--origin', origin], envWith('sk_live_ok'));
expect(r2.code).toBe(EXIT_CODES.GUARD);
expect(r2.out + r2.err).toContain('Not installed');
});
});
describe('run report', () => {
const html = buildRunReport({ run, steps, toolTraces, receiptChain: { verified: true, checked: 6, brokenAt: null }, trail, origin: 'https://three.ws', generatedAt: '2026-10-20T12:00:00.000Z' });
it('contains the goal, tool calls, decisions, outcome and both head hashes, escaped', () => {
expect(html).toContain('Watch the pool and report if liquidity drops <b>below</b> 50k');
expect(html).not.toContain('<b>below</b>');
expect(html).toContain('get_pool');
expect(html).toContain('I will read the pool first.');
expect(html).toContain('Liquidity held above 50k');
expect(html).toContain(HEAD);
expect(html).toContain('9'.repeat(64));
expect(html).toContain('not in the allowed tool set');
});
it('names trade-like calls under Trades and says so when there are none', () => {
expect(html).toMatch(/<h2>Trades<\/h2>[\s\S]*swap_quote/);
const none = buildRunReport({ run, steps: [], toolTraces: [{ ...toolTraces[0] }], trail: null });
expect(none).toContain('No trade, swap, order or transfer tool was called');
expect(none).toContain('decision trail could not be fetched');
});
it('references no external URL at all', () => {
expect(html).not.toMatch(/https?:\/\//i);
expect(html).not.toMatch(/<(script|link|img|iframe)\b[^>]*\b(src|href)=/i);
expect(html).not.toMatch(/@import|url\(/i);
expect(html).not.toMatch(new RegExp(String.fromCharCode(0x2014) + '|' + String.fromCharCode(0x2013)));
});
it('is written by `report run` to --out as one file', async () => {
const file = path.join(scratch, 'out', 'run.html');
const r = await cli(['report', 'run', RUN, '--out', file, '--json', '--origin', origin], envWith('sk_live_ok'));
expect(r.code).toBe(0);
const summary = JSON.parse(r.out);
expect(summary).toMatchObject({ run: RUN, file, decision_trail_head: '9'.repeat(64) });
const written = fs.readFileSync(file, 'utf8');
expect(written.startsWith('<!doctype html>')).toBe(true);
expect(written).toContain(HEAD);
expect(written).not.toMatch(/https?:\/\//i);
});
it('requires --out', async () => {
const r = await cli(['report', 'run', RUN, '--json', '--origin', origin], envWith('sk_live_ok'));
expect(r.code).toBe(2);
});
});