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
/**
* Agora economy read model (api/agora/[action].js) — shapes + empty/error paths.
*
* The 3D Commons and every dashboard read this endpoint, so its contract matters:
* an unknown action 404s, a non-GET 405s, a rate-limit 429s, an empty economy
* returns an HONEST empty state (never fabricated citizens), the board degrades
* gracefully when the x402 bazaar is down (200 + errors[], AgenC tasks still
* render), and the passport validates its selector / 404s an unknown citizen.
*
* We drive the REAL wrapped handler and mock only the I/O boundary — the DB
* (a query-aware fake `sql`, same approach as tests/launcher-engine.test.js), the
* x402 Bazaar, the rate limiter, and the on-chain SDK — so no mock ships in app
* code and the handler's own shaping/branching runs unchanged.
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
const H = vi.hoisted(() => ({
citizens: [],
openTasks: [],
pop: [{ total: 0, agents: 0, humans: 0, active_24h: 0 }],
prof: [],
status: [],
flow: [{ three_atomic: '0', payouts: 0 }],
completed: [{ n: 0 }],
recent: [],
topEarners: [],
avatars: [],
passportRow: undefined, // undefined ⇒ not found
activity: [],
bazaarItems: [],
bazaarThrows: false,
rlSuccess: true,
}));
// Query-aware fake `sql`: route by the joined template text, ignore interpolated
// values (fragments compose in as opaque objects). Mirrors launcher-engine.test.
vi.mock('../api/_lib/db.js', () => {
const sql = (strings, ...vals) => {
if (!Array.isArray(strings)) return { __frag: true };
const q = strings.join(' ').toLowerCase();
let rows = [];
if (q.includes('as three_atomic')) rows = H.flow;
else if (q.includes('as total')) rows = H.pop;
else if (q.includes('group by profession')) rows = H.prof;
else if (q.includes('group by status')) rows = H.status;
else if (q.includes("'completed_task'") && q.includes('count(')) rows = H.completed;
else if (q.includes('earned_three_atomic > 0')) rows = H.topEarners;
else if (q.includes('from agora_activity') && q.includes('citizen_id =')) rows = H.activity;
// The board's open lane filters on `a.kind in ('posted_task', 'hired')`, so the
// 'posted_task' literal identifies it precisely. Match that BEFORE the pulse
// `recent` query (which also selects a.task_pda + joins agora_citizens) so the
// two don't collide.
else if (q.includes('from agora_activity') && q.includes("'posted_task'")) rows = H.openTasks;
else if (q.includes('order by a.created_at desc') && q.includes('join agora_citizens')) rows = H.recent;
else if (q.includes('from agora_citizens where id')) rows = H.passportRow === undefined ? [] : [H.passportRow];
else if (q.includes('from agora_citizens where agenc_agent_pda')) rows = H.passportRow === undefined ? [] : [H.passportRow];
else if (q.includes('from agora_citizens where agenc_agent_id')) rows = H.passportRow === undefined ? [] : [H.passportRow];
else if (q.includes('from agora_citizens')) rows = H.citizens;
// The batch avatar resolve behind `avatarUrl` (public/unlisted only); the
// visibility filter lives in the SQL, so the fake returns what it selected.
else if (q.includes('from avatars')) rows = H.avatars;
return Promise.resolve(rows);
};
return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };
});
vi.mock('../api/_lib/zauth.js', () => ({ instrument: () => false, drain: async () => {} }));
vi.mock('../api/_lib/rate-limit.js', () => ({
clientIp: () => '1.2.3.4',
limits: { publicIp: async () => ({ success: H.rlSuccess, limit: 60, remaining: 0, reset: Date.now() + 1000 }) },
}));
vi.mock('../api/_lib/x402/bazaar-client.js', () => ({
Bazaar: class {
async list() {
if (H.bazaarThrows) throw new Error('bazaar_unavailable');
return { items: H.bazaarItems, errors: [] };
}
},
filterByNetwork: (items) => items,
filterByMaxPrice: (items) => items,
}));
// Object storage is an I/O boundary like the DB: give publicUrl a domain so the
// citizens batch resolve can build a real URL without S3 config in the test env.
vi.mock('../api/_lib/r2.js', () => ({
publicUrlOrNull: (key) => (key ? `https://cdn.example/${key}` : null),
}));
vi.mock('@tetsuo-ai/sdk', () => ({ getAgent: async () => null }));
import handler from '../api/agora/[action].js';
function makeRes() {
return {
statusCode: 200,
headers: {},
body: undefined,
ended: false,
setHeader(k, v) { this.headers[String(k).toLowerCase()] = v; },
getHeader(k) { return this.headers[String(k).toLowerCase()]; },
removeHeader(k) { delete this.headers[String(k).toLowerCase()]; },
end(b) { this.body = b; this.ended = true; },
get headersSent() { return this.ended; },
get writableEnded() { return this.ended; },
};
}
async function call(action, { method = 'GET', query = {} } = {}) {
const req = { method, url: `/api/agora/${action}`, headers: {}, query: { action, ...query } };
const res = makeRes();
await handler(req, res);
return { status: res.statusCode, body: res.body ? JSON.parse(res.body) : null, res };
}
beforeEach(() => {
H.citizens = [];
H.avatars = [];
H.openTasks = [];
H.pop = [{ total: 0, agents: 0, humans: 0, active_24h: 0 }];
H.prof = []; H.status = [];
H.flow = [{ three_atomic: '0', payouts: 0 }];
H.completed = [{ n: 0 }];
H.recent = []; H.topEarners = [];
H.passportRow = undefined; H.activity = [];
H.bazaarItems = []; H.bazaarThrows = false;
H.rlSuccess = true;
});
describe('router', () => {
it('404s an unknown action', async () => {
const { status, body } = await call('nonsense');
expect(status).toBe(404);
expect(body.error).toBe('not_found');
});
it('405s a non-GET method', async () => {
const { status } = await call('citizens', { method: 'POST' });
expect(status).toBe(405);
});
it('429s when the rate limiter denies, with a retry-after a poller can obey', async () => {
H.rlSuccess = false;
const { status, body, res } = await call('pulse');
expect(status).toBe(429);
expect(body.error).toBe('rate_limited');
// The 3D Commons polls board + pulse on a timer, so the 429 has to say how
// long to wait rather than leaving the client to guess.
expect(Number(res.getHeader('retry-after'))).toBeGreaterThan(0);
expect(body.retry_after).toBeGreaterThan(0);
});
});
describe('citizens', () => {
it('returns an honest empty state on zero rows (never fabricated)', async () => {
const { status, body } = await call('citizens');
expect(status).toBe(200);
expect(body.ok).toBe(true);
expect(body.empty).toBe(true);
expect(body.count).toBe(0);
expect(body.citizens).toEqual([]);
expect(Array.isArray(body.professions)).toBe(true);
expect(body.professions.length).toBe(8); // the documented bit map
});
it('shapes a projected row into the world-renderable contract', async () => {
H.citizens = [{
id: 'c1', kind: 'agent', display_name: 'Aria', avatar_url: 'https://a/glb',
profession: 'sculptor', capability_bits: 2, status: 'idle',
agenc_agent_id: 'abc', agenc_agent_pda: 'PDA1', agenc_cluster: 'devnet', identity_source: 'handle',
pos_x: 1, pos_z: 2, home_x: 0, home_z: 0,
reputation: 5, stake_lamports: 1000, earned_three_atomic: 250000, tasks_completed: 3, tasks_posted: 1,
}];
const { body } = await call('citizens');
expect(body.empty).toBe(false);
expect(body.count).toBe(1);
const c = body.citizens[0];
expect(c.displayName).toBe('Aria');
expect(c.capabilityBits).toBe('2'); // BigInt-safe string
expect(c.stakeLamports).toBe('1000');
expect(c.earnedThreeAtomic).toBe('250000');
expect(c.agenc.registered).toBe(true);
expect(c.professions.map((p) => p.key)).toContain('sculptor'); // bit 1 set
});
// agora_citizens.avatar_url holds an avatars.id, not a URL. The Commons used to
// take the column at its name and resolve every citizen with its own
// /api/avatars/<id> round trip, which cost 184 requests on a full square and
// starved the economy poller of connections. The endpoint resolves the page in
// one batch read now, so the field means what it says.
it('resolves a citizen avatar id into a loadable URL in one batch read', async () => {
H.citizens = [
{ id: 'c1', display_name: 'Aria', avatar_url: '11111111-1111-4111-8111-111111111111', capability_bits: 0 },
{ id: 'c2', display_name: 'Sol', avatar_url: 'https://already/a.glb', capability_bits: 0 },
{ id: 'c3', display_name: 'Nyx', avatar_url: null, capability_bits: 0 },
];
H.avatars = [{ id: '11111111-1111-4111-8111-111111111111', storage_key: 'u/aria/model.glb' }];
const { body } = await call('citizens');
const [aria, sol, nyx] = body.citizens;
expect(aria.avatarUrl).toBe('https://cdn.example/u/aria/model.glb');
expect(aria.avatarId).toBe('11111111-1111-4111-8111-111111111111');
// A URL already in the column is passed through untouched.
expect(sol.avatarUrl).toBe('https://already/a.glb');
expect(nyx.avatarUrl).toBe(null);
});
// A private avatar would need a presigned credential minted per citizen for a
// world anyone can watch, so it stays unresolved and its citizen renders on the
// shared default rig rather than blocking or leaking a signed URL.
it('leaves an unresolvable avatar id alone rather than inventing a URL', async () => {
H.citizens = [{ id: 'c1', display_name: 'Aria', avatar_url: '22222222-2222-4222-8222-222222222222', capability_bits: 0 }];
H.avatars = []; // private / deleted: the visibility-filtered read returns nothing
const { body } = await call('citizens');
expect(body.citizens[0].avatarUrl).toBe('22222222-2222-4222-8222-222222222222');
expect(body.citizens[0].avatarId).toBe('22222222-2222-4222-8222-222222222222');
});
});
describe('board', () => {
it('is honestly empty when both lanes are empty', async () => {
const { status, body } = await call('board');
expect(status).toBe(200);
expect(body.empty).toBe(true);
expect(body.tasks).toEqual([]);
expect(body.services).toEqual([]);
});
it('degrades gracefully when the bazaar lane is down (200 + errors[], AgenC tasks still render)', async () => {
H.bazaarThrows = true;
H.openTasks = [{
kind: 'posted_task', task_pda: 'T1', task_id: 'id1', profession: 'fetcher',
amount_atomic: 1000, reward_mint: null, reward_label: '0.001 SOL', narrative: 'a job',
created_at: '2026-07-02T00:00:00Z', tx_signature: 'sig', meta: {},
creator_id: 'c1', creator_name: 'Aria', agenc_cluster: 'devnet',
}];
const { status, body } = await call('board');
expect(status).toBe(200);
expect(body.tasks.length).toBe(1);
expect(body.tasks[0].taskPda).toBe('T1');
expect(body.errors.some((e) => e.source === 'x402')).toBe(true);
expect(body.empty).toBe(false); // AgenC lane still populated
});
});
describe('pulse', () => {
it('returns an honest empty snapshot for a fresh economy', async () => {
const { status, body } = await call('pulse');
expect(status).toBe(200);
expect(body.empty).toBe(true);
expect(body.coin.symbol).toBe('$THREE');
expect(body.population.total).toBe(0);
expect(body.economy.threeEarned24hAtomic).toBe('0');
expect(body.topEarners).toEqual([]);
});
it('reports a populated economy', async () => {
H.pop = [{ total: 12, agents: 9, humans: 3, active_24h: 4 }];
H.completed = [{ n: 7 }];
H.flow = [{ three_atomic: '999', payouts: 2 }];
H.topEarners = [{ id: 'c1', display_name: 'Aria', profession: 'sculptor', reputation: 20, earned_three_atomic: 999, tasks_completed: 7 }];
H.recent = [{ id: 'a1', kind: 'completed_task', narrative: 'Aria sculpted a fox', reward_label: '999 $THREE', created_at: '2026-07-02T00:00:00Z', task_pda: 'T1', deliverable_url: 'https://cdn/x.glb', citizen_id: 'c1', actor: 'Aria', profession: 'sculptor' }];
const { body } = await call('pulse');
expect(body.empty).toBe(false);
expect(body.population.total).toBe(12);
expect(body.economy.tasksCompleted24h).toBe(7);
expect(body.economy.threeEarned24hAtomic).toBe('999');
expect(body.topEarners[0].displayName).toBe('Aria');
// recent narration is routed correctly (not stolen by the board branch)
expect(body.recent).toHaveLength(1);
expect(body.recent[0].narrative).toBe('Aria sculpted a fox');
expect(body.recent[0].actor).toBe('Aria');
});
});
describe('passport', () => {
it('400s when no selector is supplied', async () => {
const { status, body } = await call('passport');
expect(status).toBe(400);
expect(body.error).toBe('validation_error');
});
it('404s an unknown citizen', async () => {
const { status, body } = await call('passport', { query: { id: '00000000-0000-4000-8000-00000000dead' } });
expect(status).toBe(404);
expect(body.error).toBe('not_found');
});
it('404s a non-uuid id without touching the database (probe strings must not 500)', async () => {
const { status, body } = await call('passport', { query: { id: 'verification-probe-citizen' } });
expect(status).toBe(404);
expect(body.error).toBe('not_found');
});
it('returns the projection + activity for a found citizen (on-chain best-effort, null pda ⇒ no RPC)', async () => {
// agora_citizens.id is a uuid column — the fixture must use one, matching
// what production Postgres would accept (a bare 'c1' throws 22P02 there).
const cid = '11111111-1111-4111-8111-111111111111';
H.passportRow = {
id: cid, kind: 'agent', display_name: 'Aria', profession: 'scribe', capability_bits: 4,
status: 'idle', agenc_agent_id: 'abc', agenc_agent_pda: null, agenc_cluster: 'devnet',
pos_x: 0, pos_z: 0, home_x: 0, home_z: 0, reputation: 3,
stake_lamports: 0, earned_three_atomic: 0, tasks_completed: 0, tasks_posted: 0,
};
H.activity = [{
id: 'a1', kind: 'registered', narrative: 'Aria registered', profession: 'scribe',
task_pda: null, task_id: null, amount_atomic: null, reward_mint: null, reward_label: null,
tx_signature: 'sig', proof_hash: null, deliverable_url: null, rep_before: null, rep_after: 3,
created_at: '2026-07-02T00:00:00Z',
}];
const { status, body } = await call('passport', { query: { id: cid } });
expect(status).toBe(200);
expect(body.ok).toBe(true);
expect(body.citizen.displayName).toBe('Aria');
expect(body.onchain).toBeNull(); // null pda ⇒ no on-chain read attempted
expect(body.activity.length).toBe(1);
expect(body.activity[0].kind).toBe('registered');
});
});