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 Forge on OKX.AI, the rebuilt marketplace listing
* (/api/okx/3d/forge-*, tools in api/_okx3d/forge.js, catalog rows in
* api/_lib/okx-catalog.js).
*
* What this pins:
* - the LISTED line-up is the forge and nothing else, and the submission
* payload built from it is exactly those rows;
* - every paid row answers an unpaid tools/call with a 402 that LEADS with
* eip155:196 at that row's own price (the integration the 2026-07-04 review
* rejected us for missing);
* - the free tools (getting_started, forge_status) are served with no payment
* on every endpoint, so a buyer polls where it paid;
* - a buying agent gets the same payload the ChatGPT custom GPT gets: the GLB,
* the concept image, a viewer link and an AR link;
* - the age-13+ content gate refuses before any generation is started, so a
* refused prompt can never settle.
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { Readable } from 'node:stream';
process.env.PUBLIC_APP_ORIGIN = 'https://three.ws';
process.env.X402_PAY_TO_BASE ||= '0x0000000000000000000000000000000000000001';
process.env.X402_ASSET_ADDRESS_BASE ||= '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
// The OKX X Layer rail. With these set, xlayerSettleable() is true and every
// paid forge 402 must lead with eip155:196.
process.env.X402_PAY_TO_XLAYER ||= '0x75d00a2713565171f33216e5aa2a375e076ecf69';
process.env.X402_XLAYER_RELAYER_KEY ||=
'0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
process.env.JWT_SECRET ||= 'okx-forge-test-secret';
vi.mock('../../api/_lib/auth.js', () => ({
extractBearer: () => null,
authenticateBearer: vi.fn(async () => null),
hasScope: () => true,
}));
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
mcpIp: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcpUser: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
},
clientIp: vi.fn(() => '203.0.113.9'),
}));
// The paid rows refuse before settlement when the delivery bucket is
// unwritable, so every case here needs a verdict for that probe. Keep the real
// module and override only the probe: a test must never reach for real R2.
vi.mock('../../api/_lib/r2.js', async (importOriginal) => ({
...(await importOriginal()),
objectStorageUsable: vi.fn(async () => ({ ok: true, reason: null, message: null })),
}));
// look_at_model renders through the shared headless browser. Stub only the
// render; the geometry fetch and its plain reading stay real, fed by the fetch
// router's /api/3d/inspect branch below.
vi.mock('../../api/_lib/3d-vision.js', async (importOriginal) => ({
...(await importOriginal()),
renderTurntable: vi.fn(async ({ views }) => ({
frames: (views || ['front']).map((view) => ({ view, theta: 0, phi: 0, png: Buffer.from([0x89, 0x50, 0x4e, 0x47]) })),
failed: [],
size: 256,
})),
}));
vi.mock('../../api/_lib/usage.js', () => ({
recordEvent: vi.fn(),
logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
}));
// The forge lane is a pure HTTP client over /api/gpt-forge. Mock global fetch
// with a router so nothing here touches a GPU or the network.
const lane = { submit: null, poll: null };
const submitted = [];
function jsonResponse(status, body) {
return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
}
globalThis.fetch = vi.fn(async (input, init) => {
const url = typeof input === 'string' ? input : input.url;
if (url.includes('/api/gpt-forge')) {
if (init?.method === 'POST') {
submitted.push(JSON.parse(init.body));
return lane.submit ? lane.submit() : jsonResponse(200, { job_id: 'f1.job.abc', eta_seconds: 45 });
}
return lane.poll ? lane.poll(url) : jsonResponse(200, { status: 'running' });
}
if (url.includes('/api/3d/inspect')) return jsonResponse(200, { stats: { triangles: 12400, materials: 2, textures: 1 } });
throw new Error(`unexpected fetch: ${url}`);
});
const {
OKX_CATALOG,
catalogEntry,
listedCatalog,
validateCatalog,
FORGE_TOOL,
FORGE_STATUS_TOOL,
} = await import('../../api/_lib/okx-catalog.js');
const { forgeSurface, FORGE_SERVICE_IDS } = await import('../../api/_okx3d/forge.js');
const { default: handler } = await import('../../api/okx/3d/[service].js');
function makeRes() {
return {
statusCode: 200,
headers: {},
body: null,
setHeader(name, value) {
this.headers[String(name).toLowerCase()] = value;
},
end(body) {
this.body = body ?? null;
},
};
}
function makeReq({ method = 'POST', service, headers = {}, body = null } = {}) {
const payload = body == null ? '' : JSON.stringify(body);
const req = Readable.from(payload ? [Buffer.from(payload, 'utf8')] : []);
req.method = method;
req.url = `/api/okx/3d/${service}`;
req.query = { service };
req.headers = { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9', ...headers };
return req;
}
function rpc(name, args, id = 1) {
return { jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } };
}
async function post(service, body) {
const res = makeRes();
await handler(makeReq({ service, body }), res);
return res;
}
const anonAuth = { userId: null, rateKey: null, scope: '', source: 'free' };
// dispatch() answers a full JSON-RPC envelope; the tool result is `.result`.
async function callTool(service, name, args) {
const envelope = await forgeSurface(service).dispatch(rpc(name, args), anonAuth, { headers: {} });
expect(envelope.error, JSON.stringify(envelope.error)).toBeUndefined();
return envelope.result;
}
beforeEach(() => {
lane.submit = null;
lane.poll = null;
submitted.length = 0;
});
// Every listed A2MCP row, the exact set a reviewer's MCP client connects to.
// The two free REST rows (catalog, health) are plain GET and are covered
// separately.
const LISTED_IDS = listedCatalog()
.filter((e) => e.kind === 'a2mcp')
.map((e) => e.id);
const PAID_FORGE = [
['forge-draft', '10000', '0.01'],
['forge-standard', '50000', '0.05'],
['forge-hd', '250000', '0.25'],
['forge-image', '250000', '0.25'],
];
describe('the listed line-up is the forge', () => {
it('validates, and every listed row is a forge row or a free discovery row', () => {
expect(validateCatalog()).toBe(true);
const listed = listedCatalog().map((e) => e.id);
expect(listed).toEqual([...FORGE_SERVICE_IDS, 'catalog', 'health']);
});
it('keeps every back-burner row deployed but out of the listing', () => {
const unlisted = OKX_CATALOG.filter((e) => !e.listed).map((e) => e.id);
expect(unlisted).toContain('identity-studio');
expect(unlisted).toContain('text-to-3d');
// Back burner is a listing decision, not a deletion: the rows still exist.
for (const id of unlisted) expect(catalogEntry(id).endpoint).toMatch(/^https:\/\/three\.ws\//);
});
it('prices each paid row from its own catalog entry, and prices the free row at nothing', () => {
for (const [id, atomics, usd] of PAID_FORGE) {
expect(catalogEntry(id).priceUsd).toBe(usd);
expect(forgeSurface(id).x402Amount(FORGE_TOOL)).toBe(atomics);
expect(forgeSurface(id).x402Amount(FORGE_STATUS_TOOL)).toBe(null);
expect(forgeSurface(id).x402Amount('getting_started')).toBe(null);
}
expect(forgeSurface('forge-status').x402Amount(FORGE_TOOL)).toBe(null);
});
// A buyer that pays for a model receives a URL it cannot open. look_at_model
// renders it into MCP image blocks, free, on every endpoint: the buyer sees
// what it bought. No other seller on this marketplace can do that.
it('gives every endpoint the free look_at_model tool, priced at nothing', () => {
for (const id of FORGE_SERVICE_IDS) {
const surface = forgeSurface(id);
expect(surface.TOOL_CATALOG.map((t) => t.name)).toContain('look_at_model');
expect(surface.isPublicTool('look_at_model')).toBe(true);
expect(surface.x402Amount('look_at_model')).toBe(null);
}
});
// The tool's description promises the geometry and a plain reading of it, so
// the response has to carry both, not frames alone.
it('look_at_model returns the geometry and its reading alongside the frames', async () => {
const look = forgeSurface('forge-draft').TOOLS.look_at_model;
const out = await look.handler({ glb_url: 'https://cdn.test/model.glb', views: ['front', 'side'] });
expect(out.content.filter((c) => c.type === 'image')).toHaveLength(2);
expect(out.content[0].text).toContain('12,400 triangles');
expect(out.structuredContent.stats).toEqual({ triangles: 12400, materials: 2, textures: 1 });
expect(out.structuredContent.notes[0]).toContain('12,400 triangles');
});
it('exposes one client shape: the same tool names on every endpoint', () => {
for (const [id] of PAID_FORGE) {
const names = forgeSurface(id).TOOL_CATALOG.map((t) => t.name);
expect(names).toContain(FORGE_TOOL);
expect(names).toContain(FORGE_STATUS_TOOL);
expect(names).toContain('getting_started');
}
// The free row sells nothing, so it must not advertise a paid tool.
expect(forgeSurface('forge-status').TOOL_CATALOG.map((t) => t.name)).not.toContain(FORGE_TOOL);
});
});
describe('402 challenge: the OKX Agent Payments Protocol integration', () => {
for (const [id, atomics] of PAID_FORGE) {
it(`${id}: an unpaid ${FORGE_TOOL} call 402s at its own price, leading with eip155:196`, async () => {
const args = id === 'forge-image' ? { image_urls: ['https://three.ws/og/three-ws.png'] } : { prompt: 'a low-poly fox' };
const res = await post(id, rpc(FORGE_TOOL, args));
expect(res.statusCode).toBe(402);
const challenge = JSON.parse(res.body);
// OKX buyer CLIs auto-select accepts[0]; if it is not X Layer they cannot pay.
expect(challenge.accepts[0].network).toBe('eip155:196');
expect(challenge.accepts[0].scheme).toBe('exact');
expect(challenge.accepts[0].amount).toBe(atomics);
expect(challenge.accepts[0].asset.toLowerCase()).toBe('0x779ded0c9e1022225f8e0630b35a9b54be713736');
// Non-OKX agents can still pay on the legacy rails.
expect(challenge.accepts.slice(1).some((a) => a.network !== 'eip155:196')).toBe(true);
// Nothing was generated for an unpaid call.
expect(submitted).toHaveLength(0);
});
}
it('the 402 envelope teaches a buyer to call THIS server, not another one', async () => {
const res = await post('forge-draft', rpc(FORGE_TOOL, { prompt: 'a low-poly fox' }));
const challenge = JSON.parse(res.body);
const wire = JSON.stringify(challenge);
expect(wire).toContain(FORGE_TOOL);
expect(wire).toContain(FORGE_STATUS_TOOL);
expect(challenge.extensions?.bazaar?.info?.input?.body?.params?.name).toBe(FORGE_TOOL);
});
// paymentRequirements() already emits the X Layer rail when it is configured,
// and the endpoint prepends it again so it LEADS. Prepending alone shipped the
// same rail twice in accepts[], which is the first thing a marketplace
// reviewer reads. accepts[] must now name each rail once.
it('advertises each rail exactly once', async () => {
const res = await post('forge-draft', rpc(FORGE_TOOL, { prompt: 'a low-poly fox' }));
const { accepts } = JSON.parse(res.body);
const keys = accepts.map((a) => `${a.scheme}|${a.network}|${a.asset}|${a.amount}|${a.payTo}`);
expect(new Set(keys).size).toBe(keys.length);
expect(accepts[0].network).toBe('eip155:196');
});
// The A2MCP guide's own compliance self-check is `curl -i -X POST <endpoint>`:
// no request body, no content-type, and its stated pass condition for a paid
// row is "HTTP 402 + PAYMENT-REQUIRED". readJson() rejected exactly that
// probe with 415 before any payment logic ran, so OKX's listing validator
// read four live paid rows as having no x402 quotation at all and never
// reached the payment stage (review 2026-09-04).
for (const [id, atomics] of PAID_FORGE) {
it(`${id}: the documented self-check POST (no body, no content-type) answers 402, not 415`, async () => {
const req = makeReq({ service: id });
delete req.headers['content-type'];
const res = makeRes();
await handler(req, res);
expect(res.statusCode).toBe(402);
expect(res.headers['payment-required']).toBeTruthy();
const challenge = JSON.parse(res.body);
expect(challenge.x402Version).toBe(2);
expect(challenge.accepts[0].network).toBe('eip155:196');
expect(challenge.accepts[0].amount).toBe(atomics);
expect(submitted).toHaveLength(0);
});
}
// Any POST that names no priced tool (an empty body, a plain business
// payload, a typo'd tool name) priced as null, and paymentRequirements()
// then fell back to the platform-wide default. The challenge went out
// quoting eip155:196 TWICE at two different amounts, the catalog price and
// $0.001, an ambiguous quotation the OKX validator reads as non-compliant.
for (const body of [{}, { prompt: 'a low-poly fox' }, rpc('not_a_tool', {})]) {
it(`an unpriced POST (${JSON.stringify(body).slice(0, 32)}) quotes one price per rail, the list price`, async () => {
const res = await post('forge-hd', body);
expect(res.statusCode).toBe(402);
const { accepts } = JSON.parse(res.body);
expect(accepts[0].network).toBe('eip155:196');
// One quotation per rail, and every rail quotes THIS row's price.
// ($THREE prices the same call in its own token, so it is judged on
// naming its rail once rather than on the USD-atomic amount.)
const rails = accepts.map((a) => `${a.scheme}|${a.network}|${a.asset}`);
expect(new Set(rails).size).toBe(rails.length);
for (const a of accepts.filter((x) => !/pump$/.test(x.asset))) {
expect(a.amount ?? a.maxAmountRequired).toBe('250000');
}
expect(submitted).toHaveLength(0);
});
}
// Unparseable bytes must not become a silent empty batch. On a paid row the
// paywall answers first; on the free row the caller gets the JSON-RPC parse
// error it earned, and nothing is dispatched.
it('answers unparseable bytes with the paywall on a paid row and a parse error on the free row', async () => {
const paid = makeRes();
const paidReq = Readable.from([Buffer.from('not json at all', 'utf8')]);
Object.assign(paidReq, {
method: 'POST',
url: '/api/okx/3d/forge-draft',
query: { service: 'forge-draft' },
headers: { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9' },
});
await handler(paidReq, paid);
expect(paid.statusCode).toBe(402);
const free = makeRes();
const freeReq = Readable.from([Buffer.from('not json at all', 'utf8')]);
Object.assign(freeReq, {
method: 'POST',
url: '/api/okx/3d/forge-status',
query: { service: 'forge-status' },
headers: { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9' },
});
await handler(freeReq, free);
expect(free.statusCode).toBe(200);
expect(JSON.parse(free.body).error.code).toBe(-32700);
expect(submitted).toHaveLength(0);
});
// A payment header we cannot decode is still a caller trying to pay, and the
// only thing it can do next is read the quotation again. OKX's own seller
// SDK answers an undecodable PAYMENT-SIGNATURE with a fresh 402; ours
// answered a bare 400 whose body carried no accepts[] at all, the one
// response on the paid path with nothing to parse.
for (const header of ['not-base64-at-all!!', Buffer.from('notjson', 'utf8').toString('base64')]) {
it(`an undecodable PAYMENT-SIGNATURE (${header.slice(0, 12)}) re-issues the quotation, never a bare 400`, async () => {
const res = makeRes();
await handler(
makeReq({
service: 'forge-draft',
body: rpc(FORGE_TOOL, { prompt: 'a low-poly fox' }),
headers: { 'payment-signature': header },
}),
res,
);
expect(res.statusCode).toBe(402);
expect(res.headers['payment-required']).toBeTruthy();
const challenge = JSON.parse(res.body);
expect(challenge.x402Version).toBe(2);
expect(challenge.accepts[0].network).toBe('eip155:196');
expect(challenge.accepts[0].amount).toBe('10000');
expect(challenge.error).toMatch(/PAYMENT|JSON|decode/i);
expect(submitted).toHaveLength(0);
});
}
// GET is the discovery challenge a reviewer opens first. paymentRequirements()
// was quoting the shared default there while the prepended rail quoted the
// real price, so the same rail appeared twice at two different amounts and a
// buyer could not tell what the endpoint charges.
it('the GET discovery challenge quotes the endpoint price once per rail', async () => {
const res = makeRes();
await handler(makeReq({ method: 'GET', service: 'forge-hd' }), res);
expect(res.statusCode).toBe(402);
const { accepts } = JSON.parse(res.body);
expect(accepts[0].network).toBe('eip155:196');
for (const a of accepts) expect(a.amount ?? a.maxAmountRequired).toBe('250000');
const rails = accepts.map((a) => `${a.scheme}|${a.network}|${a.asset}`);
expect(new Set(rails).size).toBe(rails.length);
});
// The OKX buyer flow: "if it is not 402, return the body directly". A
// spec-compliant MCP client sends Accept: application/json, text/event-stream
// and mcp-protocol-version, which the shared servers answer with an OAuth 401.
// That is a 401 no OKX buyer can pay and no reviewer reads as integrated.
it('a real MCP client gets 402 with the OKX header, never an OAuth 401', async () => {
for (const headers of [
{ accept: 'application/json, text/event-stream' },
{ 'mcp-protocol-version': '2025-06-18' },
]) {
const res = makeRes();
await handler(makeReq({ service: 'forge-standard', headers, body: rpc(FORGE_TOOL, { prompt: 'a fox' }) }), res);
expect(res.statusCode).toBe(402);
expect(res.headers['www-authenticate']).toBeUndefined();
expect(res.headers['payment-required']).toBeTruthy();
expect(JSON.parse(res.body).accepts[0].network).toBe('eip155:196');
}
const sse = makeRes();
await handler(makeReq({ method: 'GET', service: 'forge-standard', headers: { accept: 'text/event-stream' } }), sse);
expect(sse.statusCode).toBe(402);
});
// The 2026-09-02 review rejected the listing as "missing a complete
// description, parameter details, and usage examples". It was not the copy:
// discovery itself was paywalled. Free discovery was scoped to non-protocol
// clients (an OAuth-capable client must meet the 401 on initialize on the
// platform's other MCP surfaces), but this surface forces 402 and has no
// OAuth, so a spec-compliant MCP client, the only kind a reviewer probes an
// A2MCP listing with, was answered 402 on initialize and tools/list and
// could never read a single tool description or parameter schema. curl
// sends neither header and was served 200, which is why every earlier
// verification pass missed it.
it('a real MCP client can discover every endpoint without paying', async () => {
const mcpHeaders = [
{ accept: 'application/json, text/event-stream' },
{ 'mcp-protocol-version': '2025-06-18' },
{ 'mcp-session-id': 'sess-1' },
];
for (const id of LISTED_IDS) {
for (const headers of mcpHeaders) {
for (const method of ['initialize', 'tools/list', 'ping']) {
const res = makeRes();
await handler(makeReq({ service: id, headers, body: { jsonrpc: '2.0', id: 1, method } }), res);
expect(res.statusCode, `${id} ${method} ${JSON.stringify(headers)}`).toBe(200);
expect(res.headers['payment-required']).toBeUndefined();
}
}
}
});
// Discovery being free is only useful if what it returns is what the review
// asked for: every tool named, described, and carrying a typed schema for
// each argument.
it('tools/list hands a reviewer the parameter details for every tool', async () => {
for (const id of LISTED_IDS) {
const res = makeRes();
await handler(
makeReq({
service: id,
headers: { 'mcp-protocol-version': '2025-06-18' },
body: { jsonrpc: '2.0', id: 1, method: 'tools/list' },
}),
res,
);
const tools = JSON.parse(res.body).result.tools;
expect(tools.length, id).toBeGreaterThan(0);
for (const tool of tools) {
expect(tool.name, id).toBeTruthy();
expect(String(tool.description || '').length, `${id}/${tool.name}`).toBeGreaterThan(20);
const props = tool.inputSchema?.properties || {};
for (const [arg, schema] of Object.entries(props)) {
expect(schema.type, `${id}/${tool.name}/${arg}`).toBeTruthy();
}
}
}
});
// Paid work is not discovery, and must stay behind the 402 for the same
// clients that now discover freely.
it('still charges a protocol client for the paid tool', async () => {
for (const [id] of PAID_FORGE) {
const res = makeRes();
await handler(
makeReq({
service: id,
headers: { accept: 'application/json, text/event-stream', 'mcp-protocol-version': '2025-06-18' },
body: rpc(FORGE_TOOL, { prompt: 'a low-poly orange fox' }),
}),
res,
);
expect(res.statusCode, id).toBe(402);
expect(JSON.parse(res.body).accepts[0].network).toBe('eip155:196');
}
});
it('free tools need no payment on a paid endpoint', async () => {
const res = await post('forge-draft', rpc('getting_started', {}));
expect(res.statusCode).toBe(200);
expect(JSON.parse(res.body).result.isError).toBeFalsy();
});
it('the free status endpoint never 402s', async () => {
lane.poll = () => jsonResponse(200, { status: 'running' });
const res = await post('forge-status', rpc(FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' }));
expect(res.statusCode).toBe(200);
// ...including on GET, which a reviewer probes first: a free row answering
// its discovery GET with a priced 402 reads as a paid service.
const get = makeRes();
await handler(makeReq({ method: 'GET', service: 'forge-status' }), get);
expect(get.statusCode).toBe(405);
expect(get.headers.allow).toBe('POST, DELETE');
});
// The reviewer sweep runs ONE body across every listed endpoint, so the free
// row is asked for the paid tool it does not serve. That priced as null and
// matched no explicit free name, so it fell through to a 402 whose X Layer
// accept quoted an amount of the literal string "null": a free service
// demanding an unpayable payment, on the row a reviewer reaches last.
it('the free status endpoint answers the paid tool it does not serve with an error, not a 402', async () => {
const res = await post('forge-status', rpc(FORGE_TOOL, { prompt: 'a low-poly orange fox' }));
expect(res.statusCode).not.toBe(402);
expect(res.headers['payment-required']).toBeUndefined();
const out = JSON.parse(res.body);
expect(out.error?.message || out.result?.content?.[0]?.text || '').toMatch(/unknown|not found|unsupported/i);
});
it('no accept ever advertises an amount of "null"', async () => {
for (const id of [...PAID_FORGE.map(([rowId]) => rowId), 'forge-status']) {
const res = await post(id, rpc(FORGE_TOOL, { prompt: 'a low-poly orange fox' }));
if (res.statusCode !== 402) continue;
for (const accept of JSON.parse(res.body).accepts) {
expect(accept.amount).toMatch(/^[0-9]+$/);
}
}
});
});
describe('what a buying agent actually receives', () => {
it('a queued job comes back with a pollable handle and the free tool that reads it', async () => {
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a low-poly orange fox' });
expect(out.isError).toBeFalsy();
expect(out.structuredContent.status).toBe('pending');
expect(out.structuredContent.job).toBe('f1.job.abc');
expect(out.structuredContent.poll_tool).toBe(FORGE_STATUS_TOOL);
expect(out.structuredContent.poll_endpoint).toBe('https://three.ws/api/okx/3d/forge-status');
expect(out.structuredContent.etaSeconds).toBe(45);
});
it('a finished job carries the GLB, the browser viewer, the AR link and the model page', async () => {
lane.poll = () =>
jsonResponse(200, {
status: 'done',
creation_id: '0b6d2a9e-6f0f-4b1e-9a2c-3d4e5f607182',
glb_url: 'https://cdn.test/fox.glb',
preview_image_url: 'https://cdn.test/fox.png',
tier: 'draft',
});
const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc', title: 'a fox' });
const body = out.structuredContent;
expect(body.status).toBe('done');
expect(body.glbUrl).toBe('https://cdn.test/fox.glb');
expect(body.viewerUrl).toContain('/viewer?src=');
expect(body.arUrl).toContain('/api/ar?src=');
expect(body.pageUrl).toBe('https://three.ws/m/0b6d2a9e-6f0f-4b1e-9a2c-3d4e5f607182');
expect(body.previewImageUrl).toBe('https://cdn.test/fox.png');
expect(body.format).toBe('glb');
// The text content is what most agents relay verbatim: every link is in it.
const text = out.content[0].text;
for (const link of [body.glbUrl, body.viewerUrl, body.arUrl, body.pageUrl]) expect(text).toContain(link);
});
it('titles the viewer and AR pages from the job itself when the buyer passes no title', async () => {
lane.poll = () =>
jsonResponse(200, { status: 'done', glb_url: 'https://cdn.test/fox.glb', prompt: 'a low-poly fox' });
const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' });
expect(out.structuredContent.arUrl).toContain('title=a%20low-poly%20fox');
});
it('a pending job tells the buyer exactly what to call next', async () => {
const out = await callTool('forge-standard', FORGE_TOOL, { prompt: 'a low-poly fox' });
expect(out.structuredContent.poll_arguments).toEqual({ job_id: 'f1.job.abc', title: 'a low-poly fox' });
expect(out.content[0].text).toContain(FORGE_STATUS_TOOL);
expect(out.content[0].text).toContain('f1.job.abc');
});
it('a failed job is an error the buyer can act on, not a silent pending', async () => {
lane.poll = () =>
jsonResponse(200, {
status: 'failed',
error: 'upstream lane died',
retry_backends: ['trellis_selfhost', 'hunyuan3d'],
});
const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' });
expect(out.isError).toBe(true);
expect(out.structuredContent.status).toBe('error');
expect(out.structuredContent.error).toContain('upstream lane died');
// The alternate engines the generator named reach the buyer, so "an error
// the buyer can act on" means something the buyer can actually act on.
expect(out.structuredContent.retryBackends).toEqual(['trellis_selfhost', 'hunyuan3d']);
});
// These rows settle when the lane accepts a job, so a generation failure
// after that point HAS been charged. The shared shaper's free-lane wording
// ("it costs nothing to try again") is true on /api/3d/studio and false
// here, and it was being served to paying buyers until 2026-09-02.
it('a failed job never tells a paying buyer the retry is free', async () => {
lane.poll = () => jsonResponse(200, { status: 'failed', error: 'upstream lane died' });
const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' });
expect(out.structuredContent.error).not.toContain('costs nothing');
expect(out.structuredContent.error).toContain('new paid call');
expect(out.content[0].text).toContain('new paid call');
});
it('an unknown job id is reported as unknown_job rather than a generic failure', async () => {
lane.poll = () => jsonResponse(404, { message: 'no such job' });
const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.nope.xyz' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('unknown_job');
});
});
describe('each row drives its own lane', () => {
it('sends the row tier to the generator, and pins the image lane to reference images', async () => {
await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
expect(submitted.at(-1).tier).toBe('draft');
await callTool('forge-standard', FORGE_TOOL, { prompt: 'a fox' });
expect(submitted.at(-1).tier).toBe('standard');
await callTool('forge-hd', FORGE_TOOL, { prompt: 'a fox' });
expect(submitted.at(-1).tier).toBe('high');
await callTool('forge-image', FORGE_TOOL, { image_urls: ['https://cdn.test/a.png'] });
expect(submitted.at(-1).image_urls).toEqual(['https://cdn.test/a.png']);
expect(submitted.at(-1).tier).toBeUndefined();
});
// The generator hold-gates its high tier. A buyer of the HD row has already
// paid, so the job runs operator-funded, exactly like the custom GPT runs it.
it('runs the HD row operator-funded on the generator', async () => {
process.env.CRON_SECRET = 'seed-for-test';
let seen;
globalThis.fetch.mockImplementationOnce(async (input, init) => {
seen = init.headers;
submitted.push(JSON.parse(init.body));
return jsonResponse(200, { job_id: 'f1.job.hd', tier: 'high', eta_seconds: 240 });
});
const out = await callTool('forge-hd', FORGE_TOOL, { prompt: 'a fox' });
expect(seen['x-forge-seed']).toBe('seed-for-test');
expect(out.structuredContent.status).toBe('pending');
expect(out.structuredContent.tier).toBe('high');
});
// Without this the lane client degraded a refused high job to standard on
// its own, and the buyer paid the HD price for a standard mesh. The refusal
// answers before settlement, so nothing is charged.
it('refuses the HD row BEFORE settlement when the high lane will not take the job', async () => {
lane.submit = () => jsonResponse(402, { error: 'three_hold_required' });
const out = await callTool('forge-hd', FORGE_TOOL, { prompt: 'a fox' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('tier_unavailable');
expect(out.structuredContent.charged).toBe(false);
// Exactly one submit, no silent second attempt at a lower tier.
expect(submitted).toHaveLength(1);
expect(submitted[0].tier).toBe('high');
});
it('refuses the HD row if the lane answers with a lower tier than it was asked for', async () => {
lane.submit = () => jsonResponse(200, { job_id: 'f1.job.x', tier: 'standard' });
const out = await callTool('forge-hd', FORGE_TOOL, { prompt: 'a fox' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('tier_unavailable');
});
// Generation being up is not enough: this row settles when the lane ACCEPTS
// the job, but the buyer only ever receives a mesh that reached the delivery
// bucket. A rejected R2 credential broke that copy for every job from
// 2026-09-07, while the lane kept accepting and charging work that could
// never finish.
it('refuses BEFORE settlement when the delivery bucket is unwritable, and never submits', async () => {
const { objectStorageUsable } = await import('../../api/_lib/r2.js');
vi.mocked(objectStorageUsable).mockResolvedValueOnce({
ok: false,
reason: 'rejected',
message: 'The request signature we calculated does not match the signature you provided.',
});
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('delivery_unavailable');
expect(out.structuredContent.charged).toBe(false);
expect(out.structuredContent.retry_after).toBe(120);
// Nothing reached the generator, so nothing can settle.
expect(submitted).toHaveLength(0);
});
// The probe fails OPEN on a transient fault, so a flaky list never takes the
// paid rows down: only a deterministic rejection refuses.
it('still sells when the storage probe reports a transient fault', async () => {
const { objectStorageUsable } = await import('../../api/_lib/r2.js');
vi.mocked(objectStorageUsable).mockResolvedValueOnce({ ok: true, reason: null, message: null });
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
expect(out.isError).toBeFalsy();
expect(submitted).toHaveLength(1);
});
it('rejects an unsafe prompt BEFORE any generation runs, so it can never settle', async () => {
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a nude child' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('prompt_rejected');
expect(submitted).toHaveLength(0);
});
// The gauntlet's pay-on-acceptance case (scripts/okx-e2e-gauntlet.mjs case 6)
// signs a real payment for exactly this input, so the refusal has to survive
// two hops: the tool's JSON schema must ACCEPT it (minLength 3 counts the
// spaces) so the buyer still gets a payable 402, and the handler must then
// refuse it before the lane is ever asked for work.
it('refuses a whitespace-only prompt at acceptance, before any generation runs', async () => {
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: ' ' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('invalid_input');
expect(submitted).toHaveLength(0);
});
it('turns a saturated generator into an actionable busy error, never a 500', async () => {
lane.submit = () => jsonResponse(429, { message: 'busy', retry_after: 12 });
const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
expect(out.isError).toBe(true);
expect(out.structuredContent.error).toBe('busy');
expect(out.structuredContent.retry_after).toBe(12);
});
});