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 3D Studio (free) — client over the production generation pipeline.
//
// Every studio tool is a thin client over /api/forge — the public, auth-free
// twin of the paid 3D Studio MCP server (see api/forge.js). The platform's
// server-side keys (NVIDIA NIM, FLUX, TRELLIS/Hunyuan3D, UniRig, IBM Granite)
// cover the provider cost, so the ChatGPT user pays nothing and no wallet,
// payment, or API key is ever involved. This module is the SAME submit/poll
// logic the npm MCP tools use, factored once — not a fork and not a mock.
//
// All work runs against the deployment's own origin (STUDIO_API_BASE, else the
// configured PUBLIC_APP_ORIGIN; see api/_lib/self-origin.js), so the studio
// front door and the generation pipeline are always the same deployment.
import { selfOrigin } from '../_lib/self-origin.js';
import { watsonxConfig, watsonxChatComplete } from '../_lib/watsonx.js';
import { llmComplete } from '../_lib/llm.js';
const DEFAULT_TIMEOUT_MS = 180_000;
const DEFAULT_POLL_MS = 3_000;
function envNum(key, def) {
const v = Number(process.env[key]);
return Number.isFinite(v) && v > 0 ? v : def;
}
// Resolve the origin to call /api/forge on: STUDIO_API_BASE when set, otherwise
// the configured app origin (selfOrigin). Never a request header: the forge
// self-call can carry the internal seed credential, and a caller-chosen
// `x-forwarded-host` would send it, and the request, to any host they name.
export function originFromReq(req) {
const explicit = process.env.STUDIO_API_BASE && String(process.env.STUDIO_API_BASE).trim();
if (explicit) return explicit.replace(/\/$/, '');
return selfOrigin(req);
}
export function viewerUrl(base, glbUrl) {
return `${base}/viewer?src=${encodeURIComponent(glbUrl)}`;
}
// Device-aware AR launch link (api/ar.js): Android 302s straight into Scene
// Viewer, iOS gets a Quick Look launch page (GLB→USDZ converted in-page), and
// desktop falls back to the WebGL viewer. One URL places the model in the
// user's real room on any phone — the same lane the /ar and /forge pages use.
// `live: true` marks a rigged avatar (an agent's body): the launch page then
// leads with the IRL living handoff instead of static placement.
export function arLaunchUrl(base, glbUrl, title, { live = false } = {}) {
const t = typeof title === 'string' && title.trim() ? `&title=${encodeURIComponent(title.trim().slice(0, 80))}` : '';
const k = live ? '&kind=avatar' : '';
return `${base}/api/ar?src=${encodeURIComponent(glbUrl)}${t}${k}`;
}
// IRL living-agent link: /irl loads the avatar as an agent body in the user's
// real space: camera passthrough, animation, movement, conversation. This is
// the digital-to-physical bridge for the agent economy; static AR placement is
// the fallback for props, not the destination for avatars.
export function irlUrl(base, glbUrl) {
return `${base}/irl?avatar=${encodeURIComponent(glbUrl)}`;
}
function failure(code, message, extra = {}) {
const e = new Error(message);
e.code = code;
Object.assign(e, extra);
return e;
}
// The studio surfaces run server→server against the deployment's own /api/forge,
// so they may carry the internal seed token (the same one forge-seed-cron uses).
// Forge accepts it as proof the call is platform-originated, which clears the
// High-tier access gate — the ChatGPT user stays anonymous and keyless while the
// platform funds the premium tier. Absent secret → no header, and the tier
// fallback in startForge keeps the surface working.
function internalHeaders() {
const secret = process.env.CRON_SECRET;
return secret ? { 'x-forge-seed': secret } : {};
}
// Submit a generation job to /api/forge. Handles both the synchronous-done shape
// (the free lanes often complete inside the submit window) and the queued shape
// ({ job_id }). `backend`/`path`/`tier` pass through to forge's router; omitting
// `backend` lets the free-first router pick the best engine for the tier.
// `internal: true` attaches the platform seed token so gated tiers (high) run
// operator-funded. A high-tier submit degrades to the ungated standard tier
// rather than dead-ending when the gate refuses (402: secret missing or stale)
// OR when the high lane can't hand back a job inside the submit window. The
// self-hosted Hunyuan3D worker that serves high does return a poll handle, so
// the usual cause of the second case is its scale-to-zero cold start rather
// than a blocking lane; either way, standard is better than a dead end.
// `submitTimeoutMs` sets how long the caller is willing to hold the submit open
// before giving up (default 90s). The blocking free lanes (HF Spaces) can take
// well past 90s under a queue while still finishing fine server-side; a caller
// whose consumers poll anyway (the public /api/3d/generate) passes a wider
// window so a slow-but-working lane returns done instead of burning the GPU
// work into a client-side timeout. Interactive surfaces keep the 90s default.
// `clientKey` is a stable, opaque per-caller handle forwarded as the x-forge-client
// header so /api/forge attributes the durable creation (forge_creations row) to the
// real caller instead of collapsing it to the shared 'anon' bucket. It scopes the
// gallery/claim surface to one client without any account. Forge salts+hashes it, so
// the raw value never reaches the DB. Deliberately NOT the caller IP forwarded as
// x-forwarded-for: that would collide with forge's own per-IP free-lane limiter and
// halve the ceiling — identity attribution and rate limiting stay decoupled.
export async function startForge(base, { prompt, imageUrls, aspect, backend, path, tier, internal, submitTimeoutMs, clientKey }) {
const submitWindowMs = Number(submitTimeoutMs) > 0 ? Number(submitTimeoutMs) : 90_000;
const attempt = async (tierId, withInternal) => {
const payload = {
...(prompt ? { prompt } : {}),
...(Array.isArray(imageUrls) && imageUrls.length ? { image_urls: imageUrls } : {}),
...(aspect ? { aspect_ratio: aspect } : {}),
...(backend ? { backend } : {}),
...(path ? { path } : {}),
...(tierId ? { tier: tierId } : {}),
};
let res;
try {
res = await fetch(`${base}/api/forge`, {
method: 'POST',
headers: {
'content-type': 'application/json',
...(clientKey ? { 'x-forge-client': clientKey } : {}),
...(withInternal ? internalHeaders() : {}),
},
body: JSON.stringify(payload),
signal: AbortSignal.timeout(submitWindowMs),
});
} catch (err) {
if (err?.name === 'TimeoutError' || err?.name === 'AbortError')
throw failure('timeout', 'the 3D generator took too long to accept the job; try again');
throw failure('provider_error', `the 3D generator is unreachable: ${err?.message || err}`);
}
const data = await res.json().catch(() => ({}));
return { res, data };
};
let res;
let data;
try {
({ res, data } = await attempt(tier, !!internal));
} catch (err) {
if (err?.code !== 'timeout' || tier !== 'high') throw err;
({ res, data } = await attempt('standard', false));
}
if (res.status === 402 && tier === 'high') ({ res, data } = await attempt('standard', false));
if (res.status === 503) throw failure('not_configured', data?.message || '3D generation is not configured on this deployment');
if (res.status === 429) throw failure('busy', data?.message || 'the 3D generator is busy; try again shortly', { retryAfter: data?.retry_after });
const completedSync = data?.status === 'done' && data?.glb_url;
if (!res.ok || !(data?.job_id || completedSync)) throw failure('provider_error', data?.message || `the 3D generator returned ${res.status}`);
return data;
}
export async function startRig(base, glbUrl) {
let res;
try {
res = await fetch(`${base}/api/forge?action=rig`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ glb_url: glbUrl }),
signal: AbortSignal.timeout(30_000),
});
} catch (err) {
if (err?.name === 'TimeoutError' || err?.name === 'AbortError')
throw failure('timeout', 'the rigger took too long to accept the job; try again');
throw failure('provider_error', `the rigger is unreachable: ${err?.message || err}`);
}
const data = await res.json().catch(() => ({}));
if (res.status === 503 || res.status === 501) throw failure('not_configured', data?.message || 'auto-rigging is not enabled on this deployment');
if (res.status === 429) throw failure('busy', data?.message || 'the rigger is busy; try again shortly', { retryAfter: data?.retry_after });
if (!res.ok || !data?.job_id) throw failure('provider_error', data?.message || `the rigger returned ${res.status}`);
return data;
}
// Poll a /api/forge job to a terminal state. Returns the done payload, throws a
// coded failure on a failed job, or returns { _timedOut: true } at the deadline.
export async function pollJob(base, jobId, { timeoutMs, intervalMs } = {}) {
const tMs = timeoutMs || DEFAULT_TIMEOUT_MS;
const iMs = intervalMs || DEFAULT_POLL_MS;
const deadline = Date.now() + tMs;
let last = null;
while (Date.now() < deadline) {
let res;
try {
res = await fetch(`${base}/api/forge?job=${encodeURIComponent(jobId)}`, {
headers: { accept: 'application/json' },
signal: AbortSignal.timeout(Math.max(iMs * 3, 15_000)),
});
} catch (err) {
if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
await sleep(iMs);
continue;
}
throw failure('provider_error', `generation poll failed: ${err?.message || err}`);
}
const data = await res.json().catch(() => ({}));
if (!res.ok) throw failure('provider_error', data?.message || `generation poll returned ${res.status}`);
last = data;
if (data.status === 'done' && data.glb_url) return data;
if (data.status === 'failed') throw failure('generation_failed', data.error || 'generation failed');
await sleep(iMs);
}
return { ...(last || {}), _timedOut: true };
}
// Run a submit→poll cycle end to end, returning the terminal job payload.
// A timed-out payload keeps `job_id` so the caller can hand the (still
// running) job back to the client as a pollable handle instead of an error.
export async function generate(base, submitArgs, { timeoutEnv } = {}) {
const job = await startForge(base, submitArgs);
if (job.status === 'done' && job.glb_url) return job;
const out = await pollJob(base, job.job_id, {
timeoutMs: timeoutEnv ? envNum(timeoutEnv, DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS,
intervalMs: envNum('STUDIO_POLL_MS', DEFAULT_POLL_MS),
});
return out._timedOut ? { ...out, job_id: job.job_id } : out;
}
export async function rig(base, glbUrl, { timeoutEnv } = {}) {
const job = await startRig(base, glbUrl);
const out = await pollJob(base, job.job_id, {
timeoutMs: timeoutEnv ? envNum(timeoutEnv, DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS,
intervalMs: envNum('STUDIO_POLL_MS', DEFAULT_POLL_MS),
});
return out._timedOut ? { ...out, job_id: job.job_id } : out;
}
// IBM Granite prompt director. Rewrites a rough idea into a tight single-subject
// 3D spec. Runs IN PROCESS: watsonx Granite leads, and the shared free-first LLM
// chain (llmComplete, the same one forge-enhance rides) is the fallback. The
// previous implementation POSTed provider=watsonx to its own /api/chat, which
// the anonymous-provider gate 401s (chat.js pins anon callers to the free
// providers), so the director silently never ran on any surface. Fail-soft:
// returns null on any failure so the caller forwards the original prompt
// unchanged, never faked.
// A complete director spec (subject, construction, materials, lighting, framing,
// negatives) measures ~800 characters, which is right at what 200 tokens buys.
// With no headroom, any model even slightly more verbose than average had its
// answer cut mid-clause, and the fragment was then forwarded as the brief:
// observed on production 2026-08-07, "a red wooden rocking chair" directed to
// "A classic wooden rocking chair with gracefully curved" and "a small ceramic
// teapot with a bamboo handle" to "A small,", which reconstructed as a coffee
// tamper. Budget for a whole spec instead of a clipped one.
const DIRECTOR_MAX_TOKENS = 400;
const DIRECTOR_TIMEOUT_MS = 20_000;
// Longest brief we forward, and the longest prompt the forge itself accepts
// (api/gpt-forge.js rejects anything over 1000). The director prompts ask for
// under 800 (BRIEF_BUDGET_CHARS) so a spec has room to spare.
const DIRECTOR_MAX_CHARS = 1000;
// The director's system prompts ask for a complete spec, and a complete spec is
// a finished sentence. A generation that ran out of tokens cannot finish one,
// which makes the ending the one signal that separates a whole brief from a
// clipped one without guessing at grammar. Both production truncations fail it
// ("A small," and "A classic wooden rocking chair with gracefully curved"), as
// does any fragment ending on a separator or a dangling connective.
const ENDS_COMPLETE = /[.!?]["'\u201d\u2019)\]]*$/;
// The prompts also mandate the LAST words of the brief: the composition list
// closing on "no second subject" (mesh) or "no second character" (avatar). The
// chain copies that list verbatim and often stops without a period, and treating
// those as clipped threw away every brief on 2026-10-11 (run receipts showed the
// brief "recovered" on each studio run). A clip lands mid-word or mid-list, never
// exactly on the mandated last phrase, so that phrase is as whole an ending as a
// period. "no second" alone is still a clip.
const ENDS_ON_CLOSING_CONSTRAINT = /(?:\bno second (?:subject|character)s?|\bone (?:subject|character) only)$/i;
// Decide whether a director rewrite is safe to forward in place of the user's
// own words, and if not, name why: the run receipt states the reason, so a
// fallback is never filed under a guess. The director is a quality lever that
// must never cost a caller their intent, so anything named here falls back to
// the raw prompt rather than shipping a fragment. Erring toward rejection is
// cheap: the fallback is the caller's own wording, which is always a valid
// brief. Pure: same inputs to same verdict. gpt-forge-client.js re-exports this.
// Returns null when usable, else 'empty' | 'too_long' | 'unfinished' | 'link' |
// 'not_enriched'.
export function directorRewriteProblem(refined, rawPrompt) {
if (typeof refined !== 'string') return 'empty';
const text = refined.trim();
if (text.length < 3) return 'empty';
if (text.length > DIRECTOR_MAX_CHARS) return 'too_long';
if (!ENDS_COMPLETE.test(text) && !ENDS_ON_CLOSING_CONSTRAINT.test(text)) return 'unfinished';
// A brief describes an object; it never carries a link. A URL or a markdown
// link means the reply is a provider notice ("raise the key budget at
// https://...") or chatter, and reconstructing a mesh from it is how 22
// production generations came out of a billing message.
if (/https?:\/\/|\]\(|\bwww\./i.test(text)) return 'link';
// The director's contract is to ENRICH a rough idea into a denser spec. A
// result no longer than what the caller typed has added nothing, and is far
// more likely a clipped opening clause than a genuine tightening, so the
// user's own wording is the better brief.
const raw = String(rawPrompt ?? '').trim();
if (raw && text.length <= raw.length) return 'not_enriched';
return null;
}
export function isUsableDirectorRewrite(refined, rawPrompt) {
return directorRewriteProblem(refined, rawPrompt) === null;
}
// Shared tail of both clients' directPrompt: clean the model reply, judge it,
// and tell the caller why it was dropped. `onFallback` receives
// { reason, chars? } where reason is 'no_reply' or a directorRewriteProblem code.
export function finishDirectorReply(text, rawPrompt, onFallback) {
if (!text) {
onFallback?.({ reason: 'no_reply' });
return null;
}
// First line only, then strip wrapping quotes; the reverse order leaves a
// dangling quote when the model adds commentary lines after a quoted prompt.
const firstLine = text.trim().split('\n')[0].trim();
const refined = firstLine.replace(/^["'“”]+|["'“”]+$/g, '').trim();
const reason = directorRewriteProblem(refined, rawPrompt);
if (reason === null) return refined;
// Returning null here is the documented fail-soft path: the caller forwards
// the caller's original prompt unchanged, which is always a valid brief.
onFallback?.(reason === 'too_long' ? { reason, chars: refined.length } : { reason });
return null;
}
export async function directPrompt(instruction, rawPrompt, { onFallback } = {}) {
const user = `Idea: ${rawPrompt}`;
let text = null;
// watsonxChatComplete carries no abort signal of its own, so cap it here; a
// hung IAM or inference call must degrade to the free chain, not stall the
// whole generation submit.
const cfg = watsonxConfig();
if (cfg.configured) {
let timer;
try {
const result = await Promise.race([
watsonxChatComplete(cfg, {
messages: [
{ role: 'system', content: instruction },
{ role: 'user', content: user },
],
maxTokens: DIRECTOR_MAX_TOKENS,
}),
new Promise((_, reject) => {
timer = setTimeout(() => reject(new Error('watsonx director timed out')), DIRECTOR_TIMEOUT_MS);
}),
]);
text = result?.text || null;
} catch {
text = null;
} finally {
clearTimeout(timer);
}
}
if (!text) {
try {
const result = await llmComplete({
system: instruction,
user,
maxTokens: DIRECTOR_MAX_TOKENS,
timeoutMs: DIRECTOR_TIMEOUT_MS,
track: { tool: 'forge-director' },
});
text = result?.text || null;
} catch {
text = null;
}
}
return finishDirectorReply(text, rawPrompt, onFallback);
}
function sleep(ms) {
return new Promise((r) => setTimeout(r, ms));
}