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
/**
* Free-first reconstruct ordering for api/forge.js.
*
* Platform stance: a generation must prefer the FREE reconstruct lane over the
* paid Replicate default — so a forge call never spends on, nor dead-ends
* against, the paid account while a free lane can serve it. Concretely:
*
* • When the native free NVIDIA NIM text→3D lane fails, the request reconstructs
* the FLUX-synthesized view on the FREE HuggingFace Spaces lane BEFORE ever
* touching the paid Replicate reconstruct (FORGE_PREFER_FREE, default on).
* • When every free lane is unavailable and the only one left is the platform's
* own paid account out of credit, the buyer NEVER sees the vendor's raw
* "purchase credit / replicate.com/billing" message — that internal billing
* state is sanitized into an honest "temporarily unavailable".
*
* The provider boundaries are stubbed; these assert the endpoint's routing and
* its error hygiene, with provenance reporting the lane that actually ran.
*/
import { describe, it, expect, vi, beforeAll } from 'vitest';
beforeAll(() => {
Object.assign(process.env, {
APP_ORIGIN: 'https://three.ws',
REPLICATE_API_TOKEN: 'test-token',
NVIDIA_API_KEY: 'test-nvidia-key',
JWT_SECRET: 'test-jwt-secret-at-least-32-characters-long',
});
// No Hunyuan3D worker wired here — keep the reconstruct fallback to HF/Replicate
// only, so the free-first ordering is the single variable under test.
delete process.env.GCP_HUNYUAN3D_URL;
delete process.env.GCP_RECONSTRUCTION_KEY;
delete process.env.FORGE_PREFER_FREE; // default ON
});
// Free NVIDIA NIM text→3D lane is DOWN this whole suite (mirrors the prod failure
// that started this work: auth ok, invoke errors). Every text prompt therefore
// reaches the reconstruct step, which is what free-first governs.
const nvidiaTextTo3d = vi.fn(async () => {
throw Object.assign(new Error('TRELLIS completed but returned no GLB artifact'), {
code: 'provider_error',
status: 502,
});
});
vi.mock('../../api/_providers/nvidia.js', () => ({
createNvidiaProvider: () => ({ textTo3d: nvidiaTextTo3d }),
}));
// FLUX text-to-image (the free reference view) succeeds — the variable under test
// is which RECONSTRUCT lane runs, not image synthesis.
vi.mock('../../api/_mcp3d/text-to-image.js', () => ({
textToImage: vi.fn(async () => ({ imageUrl: 'https://cdn.example/ref.png', model: 'flux' })),
}));
// Paid Replicate reconstruct. A single module-level spy lets a test assert it was
// NEVER called (free chosen first). By default it is out of credit, exactly like
// the broke prod account — so if a test DOES reach it, the leak path is exercised.
const replicateSubmit = vi.fn(async () => {
throw Object.assign(
new Error(
'You have insufficient credit to run this model. Go to https://replicate.com/account/billing#billing to purchase credit.',
),
{ code: 'provider_error', status: 502, providerStatus: 402 },
);
});
vi.mock('../../api/_providers/replicate.js', () => ({
createRegenProvider: () => ({ submit: replicateSubmit }),
}));
// Free HuggingFace Spaces lane. createRegenProvider throws when HF_TOKEN is unset
// (mirrors the real provider's gating), so the lane is only available where a
// token is configured. submit() blocks and packs the GLB; status() echoes it.
const hfSubmit = vi.fn(async () => ({ extJobId: 'hf-packed-job' }));
const hfStatus = vi.fn(async () => ({ status: 'done', resultGlbUrl: 'https://cdn.example/hf.glb' }));
vi.mock('../../api/_providers/huggingface.js', () => ({
createRegenProvider: () => {
if (!process.env.HF_TOKEN) {
throw Object.assign(new Error('HF_TOKEN env var is required'), {
code: 'provider_unconfigured',
status: 501,
});
}
return { submit: hfSubmit, status: hfStatus };
},
}));
vi.mock('../../api/_lib/forge-store.js', () => ({
hashClient: (v) => `client:${v || 'anon'}`,
hashIp: (v) => `ip:${v}`,
createCreation: vi.fn(async () => 'creation-1'),
materializeCreation: vi.fn(async ({ glbUrl }) => ({ id: 'creation-1', glbUrl })),
markFailed: vi.fn(async () => {}),
findByJob: vi.fn(async () => null),
runWithCreationContext: (_facts, fn) => fn(),
}));
vi.mock('../../api/_lib/forge-image-validate.js', () => ({
validateForgeImage: vi.fn(async () => ({ ok: true })),
}));
vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
const actual = await importActual();
return {
...actual,
limits: {
...actual.limits,
mcp3dGenerate: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcp3dGenerateFree: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcp3dGenerateFreeTiered: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
},
clientIp: () => '203.0.113.11',
};
});
const { default: handler } = await import('../../api/forge.js');
function makeReq(body) {
return {
method: 'POST',
url: '/api/forge',
headers: { 'content-type': 'application/json', 'x-forge-client': 'tester', 'x-vercel-ip-country': 'US' },
on(event, cb) {
if (event === 'data') cb(Buffer.from(JSON.stringify(body)));
if (event === 'end') cb();
},
};
}
function makeRes() {
return {
statusCode: 200,
headers: {},
body: null,
setHeader(name, value) {
this.headers[String(name).toLowerCase()] = value;
},
getHeader(name) {
return this.headers[String(name).toLowerCase()];
},
end(body) {
this.body = body ? JSON.parse(body) : null;
},
};
}
describe('forge free-first reconstruct ordering', () => {
it('reconstructs a text prompt on the FREE HuggingFace lane before ever touching paid Replicate', async () => {
process.env.HF_TOKEN = 'test-hf-token';
nvidiaTextTo3d.mockClear();
replicateSubmit.mockClear();
hfSubmit.mockClear();
try {
const req = makeReq({ prompt: 'a red ceramic mug', tier: 'standard', path: 'image' });
const res = makeRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res.body.status).toBe('done');
expect(res.body.backend).toBe('huggingface');
expect(res.body.mode).toBe('text_to_3d');
expect(res.body.glb_url).toBe('https://cdn.example/hf.glb');
// The default resolver now leads with the image-intermediate reference
// pipeline: with HF configured (and no self-host worker), it resolves
// straight to the FREE HuggingFace lane — NVIDIA's native text→mesh
// preview (which skips the photoreal reference image) is never even
// attempted, and the paid Replicate reconstruct is NEVER invoked either.
expect(nvidiaTextTo3d).not.toHaveBeenCalled();
expect(hfSubmit).toHaveBeenCalled();
expect(replicateSubmit).not.toHaveBeenCalled();
} finally {
delete process.env.HF_TOKEN;
}
});
it('prefers the free HF lane for an image upload too (no paid Replicate call)', async () => {
process.env.HF_TOKEN = 'test-hf-token';
replicateSubmit.mockClear();
hfSubmit.mockClear();
try {
const req = makeReq({
image_urls: ['https://cdn.example/photo.png'],
tier: 'standard',
path: 'image',
skip_validation: true,
});
const res = makeRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res.body.status).toBe('done');
expect(res.body.backend).toBe('huggingface');
expect(res.body.mode).toBe('image_to_3d');
expect(hfSubmit).toHaveBeenCalled();
expect(replicateSubmit).not.toHaveBeenCalled();
} finally {
delete process.env.HF_TOKEN;
}
});
it('sanitizes the paid-lane "insufficient credit" billing leak into an honest unavailable state', async () => {
// No free reconstruct lane (HF_TOKEN unset) and the paid Replicate account is
// out of credit — the buyer must never see the vendor billing message.
delete process.env.HF_TOKEN;
replicateSubmit.mockClear();
const req = makeReq({ prompt: 'a red ceramic mug', tier: 'standard', path: 'image' });
const res = makeRes();
await handler(req, res);
expect(replicateSubmit).toHaveBeenCalled(); // free lane unavailable → fell to paid
expect(res.statusCode).toBe(503);
expect(res.body.error).toBe('generation_unavailable');
expect(res.body.message).not.toMatch(/credit|replicate|billing|insufficient/i);
expect(res.headers['retry-after']).toBe('30');
});
it('routes an EXPLICIT huggingface pick to the free lane and never the paid one', async () => {
// The user deliberately chose the free engine for a photo upload.
process.env.HF_TOKEN = 'test-hf-token';
replicateSubmit.mockClear();
hfSubmit.mockClear();
try {
const req = makeReq({
image_urls: ['https://cdn.example/photo.png'],
backend: 'huggingface',
tier: 'standard',
path: 'image',
skip_validation: true,
});
const res = makeRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res.body.backend).toBe('huggingface');
expect(res.body.mode).toBe('image_to_3d');
expect(hfSubmit).toHaveBeenCalled();
expect(replicateSubmit).not.toHaveBeenCalled();
} finally {
delete process.env.HF_TOKEN;
}
});
it('surfaces a designed busy error (never a paid fallback) when an explicit free pick has no lane', async () => {
// HF_TOKEN unset → the free Spaces provider is unavailable. An explicit free
// pick must NOT silently spend on the paid Replicate account; it returns a
// designed, retryable error instead.
delete process.env.HF_TOKEN;
replicateSubmit.mockClear();
const req = makeReq({
image_urls: ['https://cdn.example/photo.png'],
backend: 'huggingface',
tier: 'standard',
path: 'image',
skip_validation: true,
});
const res = makeRes();
await handler(req, res);
// A temporary capacity state, not a gateway fault: 503 + Retry-After.
expect(res.statusCode).toBe(503);
expect(res.headers['retry-after']).toBe('30');
expect(res.body.error).toBe('provider_busy');
expect(res.body.backend).toBe('huggingface');
expect(res.body.retry_after).toBe(30);
// Names the configured engines a fresh retry could use, never HF itself.
expect(res.body.retryable).toBe(true);
expect(res.body.retry_backends).toContain('trellis');
expect(res.body.retry_backends).not.toContain('huggingface');
expect(replicateSubmit).not.toHaveBeenCalled();
});
it('restores the paid-default ORDER when FORGE_PREFER_FREE=false (Replicate tried first)', async () => {
// The flag flips ORDER, not availability. With free-first OFF the paid
// Replicate default is attempted FIRST; HF still serves as the post-failure
// fallback (so the request doesn't dead-end), but only after Replicate is hit.
// The tier-default resolver now resolves straight to 'huggingface' when it's
// configured (the photoreal-reference-by-default fix), so this legacy
// paid-vs-free ordering — internal to the 'trellis' backend's own reconstruct
// fallback — is exercised via an EXPLICIT backend pick rather than the
// implicit default.
process.env.HF_TOKEN = 'test-hf-token';
process.env.FORGE_PREFER_FREE = 'false';
replicateSubmit.mockClear();
hfSubmit.mockClear();
try {
const req = makeReq({ prompt: 'a red ceramic mug', tier: 'standard', path: 'image', backend: 'trellis' });
const res = makeRes();
await handler(req, res);
// Replicate WAS tried first (legacy ordering) — contrast with the free-first
// test where it is never called. HF then served it as the existing fallback.
expect(replicateSubmit).toHaveBeenCalled();
expect(res.body.backend).toBe('huggingface');
} finally {
delete process.env.HF_TOKEN;
delete process.env.FORGE_PREFER_FREE;
}
});
});
// Production 2026-10-08: every HuggingFace Space sat GPU-quota-dead while a user
// who had picked that engine retried it four times in six minutes, each one a
// 3-15s wait ending in a 502. One chain-wide failure now pauses the lane
// fleet-wide, so the next request answers at once (the health report side is
// pinned in tests/api/forge-health.test.js).
describe('forge HuggingFace lane pause after a chain-wide failure', () => {
const photoPick = () =>
makeReq({
image_urls: ['https://cdn.example/photo.png'],
backend: 'huggingface',
tier: 'standard',
path: 'image',
skip_validation: true,
});
it('pauses the lane so the next explicit pick skips the dead Spaces', async () => {
const { clearProviderCooldown } = await import('../../api/_lib/provider-health.js');
const { laneCooldownKey, hfLaneCooling } = await import('../../api/_lib/forge-lane-health.js');
process.env.HF_TOKEN = 'test-hf-token';
hfSubmit.mockClear();
hfSubmit.mockRejectedValueOnce(new Error('all 3 huggingface Space(s) failed: GPU quota exhausted'));
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
try {
const first = makeRes();
await handler(photoPick(), first);
expect(first.statusCode).toBe(503);
expect(first.body.error).toBe('provider_busy');
expect(hfSubmit).toHaveBeenCalledTimes(1);
expect(await hfLaneCooling()).toBe(true);
const second = makeRes();
await handler(photoPick(), second);
expect(second.statusCode).toBe(503);
expect(second.body.error).toBe('provider_busy');
// Paused: the Spaces were not called again.
expect(hfSubmit).toHaveBeenCalledTimes(1);
} finally {
warn.mockRestore();
await clearProviderCooldown(laneCooldownKey('huggingface'));
delete process.env.HF_TOKEN;
}
});
});