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.

11.1 KB
Raw Blame
// Workbench network client. Every call here is a real platform endpoint:
//   /api/forge-upload       presigned image upload
//   /api/forge              image or prompt to 3D, plus ?catalog, ?health, ?action=rig
//   /api/forge-rembg        background removal
//   /api/forge-remesh       server-side retopology
//   /api/material-studio    durable GLB checkpoint + AI material restyle
//
// Failures surface as WorkbenchError with a `kind` the UI branches on, and a
// message written for the person looking at the screen.

const POLL_INTERVAL_MS = 2500;
const MAX_POLL_MS = 12 * 60 * 1000;

export class WorkbenchError extends Error {
	constructor(message, { kind = 'failed', retryAfter = null, retryBackends = null, status = null } = {}) {
		super(message);
		this.kind = kind;
		this.retryAfter = retryAfter;
		this.retryBackends = retryBackends;
		this.status = status;
	}
}

// The same anonymous browser handle /forge uses, so creations made here land in
// the same per-browser gallery.
export const CLIENT_ID = (() => {
	const KEY = 'forge:cid';
	try {
		let id = localStorage.getItem(KEY);
		if (!id) {
			id = crypto.randomUUID();
			localStorage.setItem(KEY, id);
		}
		return id;
	} catch {
		return crypto.randomUUID();
	}
})();

const baseHeaders = (extra) => ({ 'x-forge-client': CLIENT_ID, ...extra });

const sleep = (ms, signal) =>
	new Promise((resolve, reject) => {
		const t = setTimeout(resolve, ms);
		signal?.addEventListener(
			'abort',
			() => {
				clearTimeout(t);
				reject(new WorkbenchError('Cancelled.', { kind: 'cancelled' }));
			},
			{ once: true },
		);
	});

async function request(url, init = {}) {
	let res;
	try {
		res = await fetch(url, init);
	} catch (err) {
		if (err?.name === 'AbortError') throw new WorkbenchError('Cancelled.', { kind: 'cancelled' });
		throw new WorkbenchError('No connection to three.ws. Check your network and try again.', { kind: 'network' });
	}
	const data = await res.json().catch(() => ({}));
	return { res, data };
}

/** Map an error response from any forge endpoint onto a WorkbenchError. */
function toError(res, data, fallback) {
	const message = data?.message || fallback;
	const code = data?.error;
	if (res.status === 429 || code === 'rate_limited') {
		const header = Number(res.headers.get('ratelimit-reset'));
		const secs = Number(data?.retry_after) > 0 ? Math.ceil(Number(data.retry_after)) : header > 0 ? Math.ceil(header) : 30;
		return new WorkbenchError(data?.message || `Rate limit reached. It resets in about ${secs}s.`, {
			kind: 'rate_limited',
			retryAfter: secs,
			status: 429,
		});
	}
	if (code === 'provider_busy' || code === 'free_lane_unavailable') {
		return new WorkbenchError(message, {
			kind: 'busy',
			retryAfter: Number(data?.retry_after) > 0 ? Math.ceil(Number(data.retry_after)) : 15,
			retryBackends: Array.isArray(data?.retry_backends) ? data.retry_backends : null,
			status: res.status,
		});
	}
	if (res.status === 402 && code === 'three_hold_required') {
		return new WorkbenchError(
			data?.message || 'High quality is a $THREE holder perk. Switch to Draft or Standard, or unlock High on /forge.',
			{ kind: 'hold_required', status: 402 },
		);
	}
	if (res.status === 422 && code === 'image_not_usable') return new WorkbenchError(message, { kind: 'not_usable', status: 422 });
	if (res.status === 403 && code === 'region_restricted') return new WorkbenchError(message, { kind: 'region', status: 403 });
	if (code === 'needs_key' || code === 'invalid_key') return new WorkbenchError(message, { kind: 'needs_key', status: res.status });
	if (res.status === 503 || code === 'unconfigured') return new WorkbenchError(message, { kind: 'unconfigured', status: res.status });
	if (res.status === 400) return new WorkbenchError(message, { kind: 'invalid', status: 400 });
	return new WorkbenchError(message, { status: res.status });
}

/** Upload an image file and return its public https URL. */
export async function uploadImage(file, { signal } = {}) {
	if (!/^image\/(png|jpe?g|webp)$/i.test(file.type)) {
		throw new WorkbenchError('Use a PNG, JPG or WebP image.', { kind: 'invalid' });
	}
	if (file.size > 8 * 1024 * 1024) throw new WorkbenchError('Images must be 8 MB or smaller.', { kind: 'invalid' });
	const { res, data } = await request('/api/forge-upload', {
		method: 'POST',
		signal,
		headers: baseHeaders({ 'content-type': 'application/json' }),
		body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
	});
	if (res.status === 503) {
		throw new WorkbenchError(
			data.error === 'storage_unavailable' ? 'Uploads are down right now. Try again shortly.' : 'Uploads are unavailable on this deployment.',
			{ kind: 'unconfigured' },
		);
	}
	if (!res.ok || !data.upload_url || !data.public_url) throw toError(res, data, 'The upload could not start.');
	let put;
	try {
		put = await fetch(data.upload_url, { method: 'PUT', signal, headers: { 'content-type': file.type }, body: file });
	} catch {
		throw new WorkbenchError('Storage refused the upload. Try again shortly.', { kind: 'network' });
	}
	if (!put.ok) throw new WorkbenchError(`Storage rejected the file (${put.status}).`);
	return data.public_url;
}

/** Persist a GLB blob and return a durable https URL other tools can read. */
export async function uploadGlb(blob, { signal } = {}) {
	const { res, data } = await request('/api/material-studio?action=upload', {
		method: 'POST',
		signal,
		headers: { 'content-type': 'model/gltf-binary' },
		body: blob,
	});
	if (!res.ok || !data.url) throw toError(res, data, 'The model could not be saved for the next step.');
	return data.url;
}

export async function fetchCatalog() {
	const { res, data } = await request('/api/forge?catalog=1', { headers: baseHeaders() });
	if (!res.ok || !Array.isArray(data.backends)) throw toError(res, data, 'The engine catalog is unavailable.');
	return data;
}

export async function fetchHealth() {
	const { res, data } = await request('/api/forge?health=1', { headers: baseHeaders() });
	if (!res.ok || !data.backends) throw toError(res, data, 'Lane health is unavailable.');
	return data;
}

/**
 * Submit an image (or prompt) to 3D job and poll it to completion.
 * @returns {Promise<{glb_url:string, backend?:string, tier?:string}>}
 */
export async function generateMesh(body, { signal, onStatus } = {}) {
	const { res, data } = await request('/api/forge', {
		method: 'POST',
		signal,
		headers: baseHeaders({ 'content-type': 'application/json', 'x-witness': 'handled' }),
		body: JSON.stringify(body),
	});
	if (!res.ok || data.error) throw toError(res, data, `The generator returned ${res.status}.`);
	if (data.status === 'done' && data.glb_url) return data;
	if (!data.job_id) throw new WorkbenchError('The generator did not return a job.');
	onStatus?.({ status: data.status || 'queued', eta: data.eta_seconds, coldStart: data.cold_start });
	return pollForge(data.job_id, { signal, onStatus });
}

async function pollForge(jobId, { signal, onStatus }) {
	let deadline = performance.now() + MAX_POLL_MS;
	while (performance.now() < deadline) {
		await sleep(POLL_INTERVAL_MS, signal);
		const { res, data } = await request(`/api/forge?job=${encodeURIComponent(jobId)}`, { signal, headers: baseHeaders() });
		if (data.error === 'unconfigured') throw toError(res, data, 'This engine is not configured.');
		if (data.status === 'done' && data.glb_url) return data;
		if (data.status === 'failed') {
			throw new WorkbenchError(data.error || 'Generation failed.', {
				kind: data.retryable && data.retry_backends?.length ? 'lane_failed' : 'failed',
				retryBackends: data.retry_backends || null,
			});
		}
		// Waiting for a GPU is progress, not a stall: keep the budget for run time.
		if (data.status === 'queued') deadline = performance.now() + MAX_POLL_MS;
		if (data.status) onStatus?.({ status: data.status, eta: data.eta_seconds, coldStart: data.cold_start });
	}
	throw new WorkbenchError('Generation timed out after 12 minutes. Try a lower quality or another engine.', { kind: 'timeout' });
}

/** Submit-then-poll for the GCP tool lanes that share the { job_id } → ?job= contract. */
async function runToolJob(path, body, { signal, onStatus, label }) {
	const { res, data } = await request(path, {
		method: 'POST',
		signal,
		headers: baseHeaders({ 'content-type': 'application/json' }),
		body: JSON.stringify(body),
	});
	if (!res.ok || !data.job_id) throw toError(res, data, `${label} could not start.`);
	onStatus?.({ status: 'queued', eta: data.eta_seconds });
	const deadline = performance.now() + MAX_POLL_MS;
	while (performance.now() < deadline) {
		await sleep(POLL_INTERVAL_MS, signal);
		const poll = await request(`${path}?job=${encodeURIComponent(data.job_id)}`, { signal, headers: baseHeaders() });
		const s = poll.data;
		if (poll.res.status === 429) continue;
		if (s.status === 'done' && s.result_url) return s;
		if (s.status === 'failed') throw new WorkbenchError(s.error ? `${label} failed: ${s.error}` : `${label} failed.`);
		if (s.status) onStatus?.({ status: s.status });
	}
	throw new WorkbenchError(`${label} timed out.`, { kind: 'timeout' });
}

export function removeBackground(imageUrl, model, opts) {
	return runToolJob('/api/forge-rembg', { image_url: imageUrl, model }, { ...opts, label: 'Background removal' });
}

export function remesh(meshUrl, { mode, targetFaces }, opts) {
	return runToolJob(
		'/api/forge-remesh',
		{ mesh_url: meshUrl, remesh_mode: mode, target_faces: targetFaces, output_format: 'glb' },
		{ ...opts, label: 'Remesh' },
	);
}

export async function rig(glbUrl, { signal, onStatus } = {}) {
	const { res, data } = await request('/api/forge?action=rig', {
		method: 'POST',
		signal,
		headers: baseHeaders({ 'content-type': 'application/json' }),
		body: JSON.stringify({ glb_url: glbUrl }),
	});
	if (data.error === 'rig_unconfigured') {
		throw new WorkbenchError('Auto-rigging is not configured on this deployment.', { kind: 'unconfigured' });
	}
	if (!res.ok || !data.job_id) throw toError(res, data, 'Rigging could not start.');
	onStatus?.({ status: 'queued' });
	return pollForge(data.job_id, { signal, onStatus });
}

export async function restyle(glbUrl, instruction, { signal } = {}) {
	const { res, data } = await request('/api/material-studio?action=restyle', {
		method: 'POST',
		signal,
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({ glb_url: glbUrl, instruction }),
	});
	if (!res.ok || !data.glbUrl) throw toError(res, data, 'The material restyle failed.');
	return data;
}

/**
 * Submit up to 8 /api/forge bodies as one group (api/forge-batch.js).
 * @returns {Promise<{batch_id:string, status:string, items:object[]}>}
 */
export async function submitBatch(items, { signal } = {}) {
	const { res, data } = await request('/api/forge-batch', {
		method: 'POST',
		signal,
		headers: baseHeaders({ 'content-type': 'application/json' }),
		body: JSON.stringify({ items }),
	});
	if (!res.ok || !data.batch_id) throw toError(res, data, `The batch could not start (${res.status}).`);
	return data;
}

/** One status check on a batch group started with submitBatch(). */
export async function pollBatchGroup(batchId, { signal } = {}) {
	const { res, data } = await request(`/api/forge-batch?batch=${encodeURIComponent(batchId)}`, { signal, headers: baseHeaders() });
	if (!res.ok) throw toError(res, data, `The batch could not be checked (${res.status}).`);
	return data;
}