Skip to content

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.

14.1 KB
Raw Blame
// The X mention bot's `avatar` flow against real Postgres semantics (PGlite),
// the real migrations, the real parser, the real moderation and copy code.
// Replaced at the network edge only: the CDN download (a Response with real
// PNG bytes), the vision verdict, the image store, the 3D generator and the
// rigger, each returning the shape the real service answers with.

import { readFileSync } from 'node:fs';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { PGlite } from '@electric-sql/pglite';

const dbState = { pg: null };

vi.mock('../api/_lib/db.js', () => {
	const sql = async (strings, ...values) => {
		const text = strings.reduce((acc, part, i) => acc + part + (i < values.length ? `$${i + 1}` : ''), '');
		const out = await dbState.pg.query(text, values);
		return out.rows;
	};
	return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };
});

const av = await import('../api/_lib/x-mention-avatar.js');
const media = await import('../api/_lib/x-media-image.js');
const store = await import('../api/_lib/x-mention-store.js');
const { parseMentionIntent } = await import('../api/_lib/x-mention-intents.js');
const { weightedLength, X_POST_MAX_WEIGHT } = await import('../api/_lib/x-text-weight.js');

const MIG = new URL('../api/_lib/migrations/', import.meta.url);
const read = (f) => readFileSync(new URL(f, MIG), 'utf8');

const BASE_SCHEMA = `
	create table users (
		id uuid primary key default gen_random_uuid(), email text not null unique, display_name text, username text,
		plan text not null default 'free', email_verified boolean not null default false,
		service_account boolean not null default false, created_at timestamptz default now(), updated_at timestamptz default now()
	);
	create unique index users_username_unique on users(lower(username)) where username is not null;
	create table forge_creations (id uuid primary key, user_id uuid, visibility text, updated_at timestamptz default now());
`;

const BASE = 'https://three.test';
const CREATION = '7a2e4b63-1d3f-4c8f-8b69-2a1b0b5c8d21';
const MESH = 'https://cdn.three.test/forge/me.glb';
const RIGGED = 'https://cdn.three.test/forge/me-rigged.glb';
const ASKER = '1800000000000000042';
const OTHER = '1800000000000000099';
const OWN_PFP = 'https://pbs.twimg.com/profile_images/1800000000000000001/AbCdEfGh_normal.jpg';
const OTHER_PFP = 'https://pbs.twimg.com/profile_images/1800000000000000002/ZyXwVuTs_normal.jpg';
const DEFAULT_PFP = 'https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png';
const ACCOUNT = { kind: 'company', ref: 'trythreews', userId: '1700000000000000001', handle: 'trythreews' };
const PNG = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.alloc(2048, 7)]);
const meshJob = { status: 'done', glb_url: MESH, creation_id: CREATION };
let seq = 0;

const cdn = (body = PNG, headers = { 'content-type': 'image/png' }, status = 200) => vi.fn(async () => new Response(body, { status, headers }));
const okReview = vi.fn(async () => ({ json: { safe: true, usable: true } }));
const persist = vi.fn(async () => 'https://cdn.three.test/forge/refs/pfp.png');
const startRig = vi.fn(async () => ({ job_id: 'rig-job-1' }));
const pollRigged = vi.fn(async () => ({ status: 'done', glb_url: RIGGED }));

async function row({ text = '@trythreews make me an avatar', pfp = OWN_PFP, dryRun = true, extra = {} } = {}) {
	seq += 1;
	const id = String(1900000000000000000n + BigInt(seq));
	const mention = {
		id, userId: ASKER, username: 'asker', text, createdAt: new Date().toISOString(),
		conversationId: id, account: ACCOUNT, mentions: [{ username: 'trythreews', id: ACCOUNT.userId }], urls: [],
		author: { id: ASKER, username: 'asker', profileImageUrl: pfp },
		media: [], inReplyToUserId: null, repliedTo: null, quoted: null, isRetweet: false, fromSelf: false, ...extra,
	};
	const parsed = parseMentionIntent(mention, ACCOUNT);
	await store.recordMention({ mention, parsed, dryRun });
	return { mention, parsed, event: { tweetId: id, authorId: ASKER, author: mention.author, dryRun } };
}

beforeEach(async () => {
	dbState.pg = new PGlite();
	await dbState.pg.exec(BASE_SCHEMA);
	await dbState.pg.exec(read('20261008170000_x_mention_events.sql'));
	await dbState.pg.exec(read('20261009201500_forge_creations_x_author.sql'));
	await dbState.pg.query('insert into forge_creations (id) values ($1)', [CREATION]);
	okReview.mockClear();
	persist.mockClear();
	startRig.mockClear();
	pollRigged.mockClear();
});

const deps = (extra = {}) => ({ base: BASE, fetchImpl: cdn(), describe: okReview, persist, startForge: async () => meshJob, startRig, pollJob: pollRigged, ...extra });

describe('own profile image', () => {
	it('upgrades _normal to _400x400, rigs, and replies with the render, creation link and pose link', async () => {
		const { parsed, event } = await row();
		expect(parsed.intent).toBe('avatar');
		const fetchImpl = cdn();
		const startForge = vi.fn(async () => meshJob);
		const res = await av.handleAvatar(event, deps({ fetchImpl, startForge }));
		expect(fetchImpl.mock.calls[0][0]).toBe('https://pbs.twimg.com/profile_images/1800000000000000001/AbCdEfGh_400x400.jpg');
		expect(fetchImpl.mock.calls[0][1].redirect).toBe('manual');
		expect(startForge).toHaveBeenCalledWith(BASE, expect.objectContaining({ imageUrls: ['https://cdn.three.test/forge/refs/pfp.png'], tier: 'high', internal: true }));
		expect(startRig).toHaveBeenCalledWith(BASE, MESH);
		expect(res).toMatchObject({ outcome: 'reply', reason: 'avatar_done', link: `${BASE}/pose?src=${encodeURIComponent(RIGGED)}` });
		expect(res.text).toContain(`${BASE}/m/${CREATION}`);
		expect(res.text).toContain(`${BASE}/pose?src=${encodeURIComponent(RIGGED)}`);
		expect(weightedLength(res.text)).toBeLessThanOrEqual(X_POST_MAX_WEIGHT);
		expect(res.mediaUrl).toContain(encodeURIComponent(RIGGED));
		expect(await store.getMentionEvent(event.tweetId)).toMatchObject({ decision: 'reply', reason: 'avatar_done', dry_run: true, creation_id: CREATION });
		const [creation] = (await dbState.pg.query('select * from forge_creations where id = $1', [CREATION])).rows;
		expect(creation).toMatchObject({ x_author_id: ASKER, visibility: 'unlisted' });
	});

	it('sends nothing in a dry run and hands a live row to the adapter once', async () => {
		const dry = await row();
		const deliver = vi.fn();
		await av.handleAvatar(dry.event, deps({ deliver }));
		expect(deliver).not.toHaveBeenCalled();
		const live = await row({ dryRun: false });
		const liveDeliver = vi.fn(async () => '2000000000000000007');
		await av.handleAvatar(live.event, deps({ deliver: liveDeliver }));
		expect(liveDeliver).toHaveBeenCalledTimes(1);
		expect((await store.getMentionEvent(live.event.tweetId)).reply_tweet_id).toBe('2000000000000000007');
	});

	it('hands back the unrigged mesh when the rig fails, as forge_avatar does', async () => {
		const { event } = await row();
		const res = await av.handleAvatar(event, deps({ pollJob: vi.fn(async () => { throw Object.assign(new Error('rig failed'), { code: 'generation_failed' }); }) }));
		expect(res.reason).toBe('avatar_done_unrigged:generation_failed');
		expect(res.text).toContain(`${BASE}/m/${CREATION}`);
	});
});

describe('never another account\'s image', () => {
	it.each([
		'@trythreews make me an avatar of @someone_else',
		'@trythreews make me an avatar using @someone_else profile picture',
		'@trythreews 3d my pfp but use @someone_else pic',
	])('text naming another account still uses only the author\'s picture: %s', async (text) => {
		const { parsed, event } = await row({ text, extra: { mentions: [{ username: 'trythreews', id: ACCOUNT.userId }, { username: 'someone_else', id: OTHER }] } });
		expect(parsed.intent).toBe('avatar');
		expect(JSON.stringify(parsed.args)).not.toContain('someone_else');
		const fetchImpl = cdn();
		await av.handleAvatar(event, deps({ fetchImpl }));
		expect(fetchImpl).toHaveBeenCalledTimes(1);
		expect(fetchImpl.mock.calls[0][0]).toContain('/1800000000000000001/');
		expect(fetchImpl.mock.calls[0][0]).not.toContain('1800000000000000002');
	});

	it('a reply to another account\'s post does not borrow that account\'s picture', async () => {
		const { event } = await row({
			extra: {
				inReplyToUserId: OTHER,
				repliedTo: { id: '1899999999999999000', available: true, text: 'hi', author: { id: OTHER, username: 'someone', profileImageUrl: OTHER_PFP }, media: [] },
			},
		});
		const fetchImpl = cdn();
		await av.handleAvatar(event, deps({ fetchImpl }));
		expect(fetchImpl.mock.calls[0][0]).toContain('/1800000000000000001/');
	});

	it('skips as not_own_image when the author object is not the asker, with no fetch', async () => {
		const { event } = await row();
		const fetchImpl = cdn();
		const res = await av.handleAvatar({ ...event, author: { id: OTHER, profileImageUrl: OTHER_PFP } }, deps({ fetchImpl }));
		expect(res).toMatchObject({ outcome: 'skip', reason: 'not_own_image' });
		expect(fetchImpl).not.toHaveBeenCalled();
		expect(await store.getMentionEvent(event.tweetId)).toMatchObject({ decision: 'skip', reason: 'not_own_image', reply_text: null });
		const missing = await av.handleAvatar({ ...event, author: null }, deps({ fetchImpl }));
		expect(missing.reason).toBe('not_own_image');
	});
});

describe('default profile image', () => {
	it('replies with the avatar studio link, records default_avatar, and generates nothing', async () => {
		const { event } = await row({ pfp: DEFAULT_PFP });
		const startForge = vi.fn();
		const fetchImpl = cdn();
		const res = await av.handleAvatar(event, deps({ startForge, fetchImpl }));
		expect(res).toMatchObject({ outcome: 'reply', reason: 'default_avatar', link: `${BASE}/create` });
		expect(res.text).toContain(`${BASE}/create`);
		expect(startForge).not.toHaveBeenCalled();
		expect(fetchImpl).not.toHaveBeenCalled();
		expect(await store.getMentionEvent(event.tweetId)).toMatchObject({ decision: 'reply', reason: 'default_avatar' });
	});
});

describe('moderation and CDN rules', () => {
	it('refuses an unsafe picture before it is stored or sent to the generator', async () => {
		const { event } = await row();
		const startForge = vi.fn();
		const res = await av.handleAvatar(event, deps({ startForge, describe: vi.fn(async () => ({ json: { safe: false, usable: true } })) }));
		expect(res).toMatchObject({ outcome: 'unsafe', reason: 'image_unsafe' });
		expect(persist).not.toHaveBeenCalled();
		expect(startForge).not.toHaveBeenCalled();
	});

	it('refuses a picture with no figure, and fails closed when no vision provider answers', async () => {
		const a = await row();
		expect((await av.handleAvatar(a.event, deps({ describe: vi.fn(async () => ({ json: { safe: true, usable: false } })) }))).reason).toBe('image_unusable');
		const b = await row();
		const startForge = vi.fn();
		const res = await av.handleAvatar(b.event, deps({ startForge, describe: vi.fn(async () => { throw new Error('no provider'); }) }));
		expect(res.reason).toBe('review_unavailable');
		expect(startForge).not.toHaveBeenCalled();
	});

	it('fetches profile pictures from the X photo CDN only', async () => {
		expect(media.xProfileImageUrl(OWN_PFP)).toBe('https://pbs.twimg.com/profile_images/1800000000000000001/AbCdEfGh_400x400.jpg');
		for (const url of ['https://evil.example/profile_images/a_normal.jpg', 'http://pbs.twimg.com/profile_images/a_normal.jpg', 'https://pbs.twimg.com.evil.example/profile_images/a_normal.jpg', 'https://pbs.twimg.com/media/a.jpg', 'https://[email protected]/profile_images/a_normal.jpg']) {
			expect(media.xProfileImageUrl(url)).toBeNull();
		}
		const { event } = await row();
		const fetchImpl = cdn();
		const res = await av.handleAvatar({ ...event, author: { id: ASKER, profileImageUrl: 'https://evil.example/profile_images/a_normal.jpg' } }, deps({ fetchImpl }));
		expect(res.reason).toBe('image_rejected:not_cdn');
		expect(fetchImpl).not.toHaveBeenCalled();
	});
});

describe('pending and follow-up', () => {
	it('keeps a mesh that is not done as pending, then rigs it and replies once', async () => {
		const { event } = await row();
		const slow = { job_id: 'mesh-job-1', creation_id: CREATION, status: 'queued' };
		const res = await av.handleAvatar(event, deps({ startForge: async () => slow, pollJob: vi.fn(async () => ({ _timedOut: true })) }));
		expect(res).toMatchObject({ outcome: 'pending', reason: 'avatar_pending' });
		const pending = await store.getMentionEvent(event.tweetId);
		expect(pending).toMatchObject({ decision: 'pending', reason: 'avatar_pending' });
		expect(pending.args.avatar).toMatchObject({ stage: 'mesh', job_id: 'mesh-job-1' });

		const waiting = await av.finishPendingAvatars({}, { base: BASE, pollOnce: async () => ({ status: 'running' }) });
		expect(waiting).toMatchObject({ checked: 1, waiting: 1 });

		const advanced = await av.finishPendingAvatars({}, { base: BASE, startRig, pollOnce: async () => ({ status: 'done', glb_url: MESH, creation_id: CREATION }) });
		expect(advanced.advanced).toBe(1);
		expect((await store.getMentionEvent(event.tweetId)).args.avatar).toMatchObject({ stage: 'rig', job_id: 'rig-job-1', mesh_glb_url: MESH });

		const deliver = vi.fn();
		const finished = await av.finishPendingAvatars({}, { base: BASE, deliver, pollOnce: async () => ({ status: 'done', glb_url: RIGGED }) });
		expect(finished.replied).toBe(1);
		const settled = await store.getMentionEvent(event.tweetId);
		expect(settled).toMatchObject({ decision: 'reply', reason: 'avatar_done_late' });
		expect(settled.reply_text).toContain('/pose?src=');
		expect(deliver).not.toHaveBeenCalled();
		expect((await av.finishPendingAvatars({}, { base: BASE, pollOnce: async () => ({ status: 'done', glb_url: RIGGED }) })).checked).toBe(0);
	});

	it('answers an overdue or failed job with the designed failure reply', async () => {
		const { event } = await row();
		const slow = { job_id: 'mesh-job-2', creation_id: CREATION, status: 'queued' };
		await av.handleAvatar(event, deps({ startForge: async () => slow, pollJob: vi.fn(async () => ({ _timedOut: true })) }));
		const out = await av.finishPendingAvatars({}, { base: BASE, pollOnce: async () => ({ status: 'failed' }) });
		expect(out.failed).toBe(1);
		const settled = await store.getMentionEvent(event.tweetId);
		expect(settled.reason).toBe('avatar_failed:generation_failed');
		expect(settled.reply_text).toContain(`${BASE}/create`);
	});
});