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
import { describe, it, expect, beforeEach, vi } from 'vitest';
process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';
// ── Per-user payer (money core) — mocked; we test orchestration, not fund movement ──
const payerState = {
spendEnabled: true,
walletStatus: null,
payResult: null,
payError: null,
};
// The real-funds agreement gate has its own suite (tests/real-funds-agreement.test.js).
vi.mock('../../api/_lib/real-funds-agreement.js', () => ({
currentSignatureFor: vi.fn(async () => ({ signedAt: '2026-09-17T00:00:00.000Z', signatureName: 'Test Signer', context: null })),
agreementRequirement: () => ({ version: 2, sign_url: 'https://three.ws/legal/agreements', documents: [] }),
}));
vi.mock('../../api/_lib/x402-user-payer.js', () => ({
resolveSpendEnabled: () => payerState.spendEnabled,
getUserWalletStatus: vi.fn(async () => payerState.walletStatus),
payExternalX402: vi.fn(async () => {
if (payerState.payError) throw payerState.payError;
return payerState.payResult;
}),
}));
// ── Bazaar (live discovery) ──────────────────────────────────────────────────
const bazState = { search: vi.fn(async () => ({ resources: [], errors: [] })) };
vi.mock('../../api/_lib/x402/bazaar-client.js', async (orig) => {
const real = await orig();
return { ...real, Bazaar: class { search(...a) { return bazState.search(...a); } } };
});
// ── x402 price probe (the network boundary pay_quote reads) ─────────────────
// probePrice is the only call that leaves the process; selectRail and the rest
// of the module stay real so the quote picks its rail the way production does.
const probeState = { result: null };
vi.mock('../../api/_lib/pay/probe.js', async (orig) => {
const real = await orig();
return { ...real, probePrice: vi.fn(async () => probeState.result) };
});
// ── Rate limits ──────────────────────────────────────────────────────────────
const rl = { agent: { success: true, reset: 0 }, pay: { success: true, reset: 0 } };
vi.mock('../../api/_lib/rate-limit.js', async (importOriginal) => ({
...(await importOriginal()),
limits: {
mcpAgent: vi.fn(async () => rl.agent),
mcpAgentPay: vi.fn(async () => rl.pay),
},
clientIp: vi.fn(() => '203.0.113.5'),
}));
vi.mock('../../api/_lib/usage.js', () => ({
recordEvent: vi.fn(),
logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
}));
const payer = await import('../../api/_lib/x402-user-payer.js');
const probe = await import('../../api/_lib/pay/probe.js');
const { dispatch, isPublicTool } = await import('../../api/_mcpagent/dispatch.js');
// A synthetic seller: one Solana USDC accept for one cent.
const SELLER = 'THREEsyntheticSe11er1111111111111111111111';
function pricedAt(amountAtomics, network = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') {
return {
kind: 'priced',
status: 402,
description: null,
rails: [probe.describeRail({ network, asset: probe.USDC_SOLANA_MINT, payTo: SELLER, amount: String(amountAtomics) })],
};
}
const ANON = { userId: null, rateKey: 'x402:anon', scope: '', source: 'x402' };
const USER = { userId: 'user-1', rateKey: 'user-1', scope: 'wallet:read wallet:write', source: 'bearer' };
// Read grant only: may look at the wallet, may never spend from it.
const READONLY = { userId: 'user-1', rateKey: 'user-1', scope: 'wallet:read', source: 'bearer' };
// A token from a client that was never granted anything wallet-shaped, e.g. a
// dynamically-registered client holding the default avatars:read.
const NOSCOPE = { userId: 'user-1', rateKey: 'user-1', scope: 'avatars:read', source: 'bearer' };
// Each request names its tool enablement in X-Three-Tools, the way a client
// does, so no test depends on saved settings. `default` is the platform base
// (read and write on, financial off); `x402` turns on the x402 group, which is
// what lets pay_and_call exist for the session at all.
const reqWith = (tools) => ({ url: '/api/mcp-agent', headers: tools ? { 'x-three-tools': tools } : {} });
const PAY_ON = 'default,x402';
const call = (name, args, auth = USER, tools = PAY_ON) =>
dispatch({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, auth, reqWith(tools));
// The full spend path a model has to walk: pay_quote, then pay_and_call with
// the quote_id it returned and confirm_payment: true. `quoteAuth` lets a test
// quote as one token and pay as another for the same account.
async function quoteThenPay(args, auth = USER, { quoteAuth = auth } = {}) {
const quote = await call('pay_quote', { resource_url: args.resource_url }, quoteAuth);
const quoteId = quote.result._meta?.['three.ws/preview']?.quote_id;
expect(quoteId, 'pay_quote issued a quote_id').toMatch(/^q_/);
return call('pay_and_call', { ...args, quote_id: quoteId, confirm_payment: true }, auth);
}
beforeEach(() => {
payerState.spendEnabled = true;
payerState.walletStatus = null;
payerState.payResult = null;
payerState.payError = null;
payer.payExternalX402.mockClear();
payer.getUserWalletStatus.mockClear();
bazState.search.mockClear();
probeState.result = pricedAt(10_000);
probe.probePrice.mockClear();
rl.agent = { success: true, reset: 0 };
rl.pay = { success: true, reset: 0 };
});
describe('threews-agent MCP', () => {
it('lists the wallet toolset behind a free getting_started tool, with spend tools off by default', async () => {
const r = await dispatch({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, USER, reqWith('default'));
const names = r.result.tools.map((t) => t.name);
expect(names.slice(0, 8)).toEqual([
'getting_started',
'wallet_status',
'find_services',
'pay_quote',
'provision_wallet',
'monetize_endpoint',
'read_resource',
'get_linked_accounts',
]);
// Every tool that moves funds is financial tier: hidden until the session
// turns its group on, so a default connection can never spend.
for (const spend of ['pay_and_call', 'buy_now', 'place_bid', 'accept_marketplace_bid', 'predictions_open', 'predictions_redeem']) {
expect(names, spend).not.toContain(spend);
}
// Every preview a money-moving tool depends on stays visible.
expect(names).toEqual(expect.arrayContaining(['pay_quote', 'preview_marketplace_action', 'predictions_open_preview']));
});
it('shows pay_and_call, with its confirm flag and quote_id, once the x402 group is on', async () => {
const r = await dispatch({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, USER, reqWith(PAY_ON));
const pay = r.result.tools.find((t) => t.name === 'pay_and_call');
expect(pay).toBeDefined();
expect(pay._meta['three.ws/policy']).toMatchObject({
group: 'x402',
tier: 'financial',
confirmFlag: 'confirm_payment',
previewTool: 'pay_quote',
previewArg: 'quote_id',
});
expect(Object.keys(pay.inputSchema.properties)).toEqual(expect.arrayContaining(['confirm_payment', 'quote_id']));
expect(pay.description).toContain('Call pay_quote first');
});
it('lists pay_and_call with its confirm flag and quote argument once the connection turns it on', async () => {
const r = await dispatch({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, USER, { ...PAY_ON });
const pay = r.result.tools.find((t) => t.name === 'pay_and_call');
expect(pay).toBeDefined();
expect(Object.keys(pay.inputSchema.properties)).toEqual(
expect.arrayContaining(['resource_url', 'confirm_payment', 'quote_id']),
);
expect(pay._meta['three.ws/policy']).toMatchObject({ tier: 'financial', previewTool: 'pay_quote' });
});
it('refuses pay_and_call on a connection that has not turned it on, before any payment call', async () => {
const r = await call('pay_and_call', { resource_url: 'https://paid.test/x' });
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toMatchObject({ reason: 'tool_disabled', group: 'x402', tier: 'financial' });
expect(payer.payExternalX402).not.toHaveBeenCalled();
});
it('refuses pay_and_call without a pay_quote preview for the same resource', async () => {
const noPreview = await call('pay_and_call', { resource_url: 'https://paid.test/x', confirm_payment: true }, USER, PAY_ON);
expect(noPreview.result.structuredContent.reason).toBe('preview_required');
const quote = await call('pay_quote', { resource_url: 'https://paid.test/cheap' }, USER, PAY_ON);
const quoteId = quote.result._meta['three.ws/preview'].quote_id;
const swapped = await call(
'pay_and_call',
{ resource_url: 'https://paid.test/expensive', quote_id: quoteId, confirm_payment: true },
USER,
PAY_ON,
);
expect(swapped.result.structuredContent.reason).toBe('preview_mismatch');
expect(payer.payExternalX402).not.toHaveBeenCalled();
});
it('getting_started is free and callable with no sign-in', async () => {
expect(isPublicTool('getting_started')).toBe(true);
expect(isPublicTool('pay_and_call')).toBe(false);
const r = await dispatch(
{ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'getting_started', arguments: {} } },
{ userId: null, rateKey: null, scope: '', source: 'free' },
);
expect(r.result.structuredContent.server).toBe('three.ws Agent');
expect(r.result.structuredContent.tools.map((t) => t.name)).toEqual(
expect.arrayContaining(['wallet_status', 'pay_and_call']),
);
});
it('wallet_status requires sign-in', async () => {
const r = await call('wallet_status', {}, ANON);
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent.signed_in).toBe(false);
expect(payer.getUserWalletStatus).not.toHaveBeenCalled();
});
it('wallet_status reports balance + caps for a signed-in user', async () => {
payerState.walletStatus = {
provisioned: true,
agent_id: 'a1',
agent_name: 'Scout',
address: 'SoLaddr',
network: 'solana',
balances: { sol: 0.2, usdc: 5 },
spend_enabled: true,
caps: { max_per_call_usdc: 0.1, max_per_hour_usdc: 1, max_per_day_usdc: 10 },
};
const r = await call('wallet_status', {});
expect(payer.getUserWalletStatus).toHaveBeenCalledWith('user-1');
expect(r.result.structuredContent).toMatchObject({ signed_in: true, address: 'SoLaddr', balances: { usdc: 5 } });
expect(r.result.content[0].text).toContain('5 USDC');
});
it('wallet_status refuses a token with no wallet grant', async () => {
const r = await call('wallet_status', {}, NOSCOPE);
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toMatchObject({
reason: 'insufficient_scope',
required: 'wallet:read',
});
expect(payer.getUserWalletStatus).not.toHaveBeenCalled();
});
it('wallet_status accepts wallet:write as proof of read access', async () => {
payerState.walletStatus = {
provisioned: false,
balances: {},
caps: {},
spend_enabled: false,
};
const r = await call(
'wallet_status',
{},
{ userId: 'user-1', rateKey: 'user-1', scope: 'wallet:write', source: 'bearer' },
);
expect(r.result.isError).toBeUndefined();
expect(r.result.structuredContent.signed_in).toBe(true);
});
it('find_services searches the live bazaar', async () => {
bazState.search.mockResolvedValue({
resources: [{ resource: 'https://svc.test', serviceName: 'Svc', minPriceLabel: '$0.01', networks: ['solana:*'], toolName: '' }],
errors: [],
});
const r = await call('find_services', { query: 'weather' });
expect(bazState.search).toHaveBeenCalledWith({ query: 'weather', type: 'http' });
expect(r.result.structuredContent.services[0]).toMatchObject({ resource: 'https://svc.test', price: '$0.01' });
});
it('pay_quote prices the endpoint without paying and issues a quote_id', async () => {
payerState.walletStatus = {
provisioned: true,
address: 'SoLaddr',
balances: { sol: 0.2, usdc: 5 },
spend_enabled: true,
caps: { max_per_call_usdc: 0.1, max_per_hour_usdc: 1, max_per_day_usdc: 10 },
};
const r = await call('pay_quote', { resource_url: 'https://paid.test/weather' });
expect(probe.probePrice).toHaveBeenCalledWith('https://paid.test/weather', { method: 'GET', body: null });
expect(payer.payExternalX402).not.toHaveBeenCalled();
expect(r.result.isError).toBeUndefined();
expect(r.result.structuredContent).toMatchObject({
ok: true,
recipient: SELLER,
amount_usd: 0.01,
token: 'USDC',
network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
from: 'SoLaddr',
per_call_limit_usd: 0.1,
blockers: [],
});
const text = r.result.content.map((c) => c.text).join('\n');
expect(text).toContain(`Recipient: ${SELLER}`);
expect(text).toContain('Amount: 0.01 USDC');
expect(text).toContain('Chain: Solana');
expect(r.result._meta['three.ws/preview']).toMatchObject({ unlocks: ['pay_and_call'] });
});
it('pay_quote refuses, and issues no quote_id, for a price over the per-call limit', async () => {
probeState.result = pricedAt(250_000);
const r = await call('pay_quote', { resource_url: 'https://paid.test/x', max_usd: 0.05 });
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent.blockers.map((b) => b.code)).toContain('over_per_call_limit');
expect(r.result._meta?.['three.ws/preview']).toBeUndefined();
});
it('pay_quote refuses an endpoint that cannot be paid on Solana', async () => {
probeState.result = pricedAt(10_000, 'eip155:8453');
const r = await call('pay_quote', { resource_url: 'https://paid.test/x' });
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toMatchObject({ reason: 'no_solana_rail', networks: ['eip155:8453'] });
expect(r.result._meta?.['three.ws/preview']).toBeUndefined();
});
it('pay_quote passes an unreachable endpoint through as a designed refusal', async () => {
probeState.result = { kind: 'error', code: 'blocked_url', message: 'Target URL is not a reachable public endpoint' };
const r = await call('pay_quote', { resource_url: 'https://paid.test/x' });
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent.reason).toBe('blocked_url');
expect(r.result.content[0].text).toContain('Nothing was paid.');
});
it('pay_and_call is turned off until the session enables the x402 group', async () => {
const r = await call('pay_and_call', { resource_url: 'https://paid.test/x' }, USER, 'default');
expect(payer.payExternalX402).not.toHaveBeenCalled();
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toMatchObject({ reason: 'tool_disabled', tool: 'pay_and_call', group: 'x402', tier: 'financial' });
expect(r.result.content[0].text).toContain('X-Three-Tools: x402');
});
it('pay_and_call refuses without confirm_payment, then without a quote, before any payment call', async () => {
const noConfirm = await call('pay_and_call', { resource_url: 'https://paid.test/x' });
expect(noConfirm.result.structuredContent).toMatchObject({ reason: 'confirmation_required', confirm_flag: 'confirm_payment', preview_tool: 'pay_quote' });
const noQuote = await call('pay_and_call', { resource_url: 'https://paid.test/x', confirm_payment: true });
expect(noQuote.result.structuredContent).toMatchObject({ reason: 'preview_required', preview_arg: 'quote_id' });
const unknown = await call('pay_and_call', { resource_url: 'https://paid.test/x', confirm_payment: true, quote_id: 'q_aaaaaaaaaaaaaaaaaaaaaaaa' });
expect(unknown.result.structuredContent.reason).toBe('preview_unknown');
expect(payer.payExternalX402).not.toHaveBeenCalled();
});
it('pay_and_call refuses a quote_id issued for a different resource', async () => {
const quote = await call('pay_quote', { resource_url: 'https://paid.test/cheap' });
const quoteId = quote.result._meta['three.ws/preview'].quote_id;
const r = await call('pay_and_call', { resource_url: 'https://paid.test/other', quote_id: quoteId, confirm_payment: true });
expect(r.result.structuredContent).toMatchObject({ reason: 'preview_mismatch' });
expect(payer.payExternalX402).not.toHaveBeenCalled();
});
it('pay_and_call degrades to a pay link when spend is disabled', async () => {
payerState.spendEnabled = false;
const r = await quoteThenPay({ resource_url: 'https://paid.test/x' });
expect(payer.payExternalX402).not.toHaveBeenCalled();
expect(r.result.structuredContent).toMatchObject({ paid: false, reason: 'spend_disabled' });
expect(r.result.structuredContent.pay_link).toContain('https://three.ws/pay?resource=');
});
it('pay_and_call degrades to auth handoff for anon callers', async () => {
const r = await quoteThenPay({ resource_url: 'https://paid.test/x' }, ANON);
expect(payer.payExternalX402).not.toHaveBeenCalled();
expect(r.result.structuredContent.reason).toBe('auth_required');
});
it('pay_and_call pays and returns the result when enabled', async () => {
payerState.payResult = { ok: true, payer: 'SoLaddr', result: { temp: 72 }, receipt: { tx: 'sig' } };
const r = await quoteThenPay({ resource_url: 'https://paid.test/weather', max_usd: 0.05 });
// The policy-only arguments (quote_id, confirm_payment) never reach the payer.
expect(payer.payExternalX402).toHaveBeenCalledTimes(1);
expect(payer.payExternalX402).toHaveBeenCalledWith({
userId: 'user-1',
url: 'https://paid.test/weather',
method: 'GET',
body: undefined,
maxUsd: 0.05,
});
expect(r.result.structuredContent).toMatchObject({ paid: true, payer: 'SoLaddr', result: { temp: 72 } });
});
it('spends a quote_id once: one approval pays one call', async () => {
payerState.payResult = { ok: true, payer: 'SoLaddr', result: { temp: 72 }, receipt: { tx: 'sig' } };
const quote = await call('pay_quote', { resource_url: 'https://paid.test/weather' });
const args = {
resource_url: 'https://paid.test/weather',
quote_id: quote.result._meta['three.ws/preview'].quote_id,
confirm_payment: true,
};
const first = await call('pay_and_call', args);
expect(first.result.structuredContent.paid).toBe(true);
const replay = await call('pay_and_call', args);
expect(replay.result.structuredContent.reason).toBe('preview_unknown');
expect(payer.payExternalX402).toHaveBeenCalledTimes(1);
});
it('pay_and_call surfaces payer errors with a friendly message + pay link', async () => {
payerState.payError = Object.assign(new Error('boom'), { code: 'no_solana_wallet' });
const r = await quoteThenPay({ resource_url: 'https://paid.test/x' });
expect(r.result.isError).toBe(true);
expect(r.result.content[0].text).toContain('no Solana wallet');
expect(r.result.structuredContent.reason).toBe('no_solana_wallet');
});
it('pay_quote tells a read-only token it cannot spend and issues it no quote_id', async () => {
const r = await call('pay_quote', { resource_url: 'https://paid.test/x' }, READONLY);
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent.blockers.map((b) => b.code)).toContain('insufficient_scope');
expect(r.result._meta?.['three.ws/preview']).toBeUndefined();
});
it('refuses to spend for a read-only token, before any payment call', async () => {
// Same account, so a quote issued to its full-scope token passes the
// policy gate; the handler's own wallet:write check must still refuse.
const r = await quoteThenPay({ resource_url: 'https://paid.test/x' }, READONLY, { quoteAuth: USER });
expect(payer.payExternalX402).not.toHaveBeenCalled();
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toMatchObject({
reason: 'insufficient_scope',
required: 'wallet:write',
});
});
it('still hands a read-only token the manual pay link when spend is off', async () => {
payerState.spendEnabled = false;
const r = await quoteThenPay({ resource_url: 'https://paid.test/x' }, READONLY);
expect(r.result.structuredContent).toMatchObject({ paid: false, reason: 'spend_disabled' });
expect(r.result.structuredContent.pay_link).toContain('https://three.ws/pay?resource=');
});
it('rejects an out-of-range max_price_usdc as invalid params, not an internal error', async () => {
const r = await call('find_services', { query: 'weather', max_price_usdc: 1e21 });
expect(r.error.code).toBe(-32602);
expect(r.error.message).toContain('max_price_usdc');
expect(bazState.search).not.toHaveBeenCalled();
});
it('enforces the pay rate limit before spending', async () => {
const quote = await call('pay_quote', { resource_url: 'https://paid.test/x' });
rl.pay = { success: false, reset: Date.now() + 30000 };
const r = await call('pay_and_call', {
resource_url: 'https://paid.test/x',
quote_id: quote.result._meta['three.ws/preview'].quote_id,
confirm_payment: true,
});
expect(r.error.code).toBe(-32000);
expect(payer.payExternalX402).not.toHaveBeenCalled();
});
});