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
// Shared, dependency-free generation cores for the three.ws 3D pipeline.
//
// These are the REAL handlers behind the five generation tools — text→3D, 3D
// avatar, text/image→mesh, auto-rig, and one-call text→rigged-avatar. They are
// thin clients over the three.ws production pipeline (/api/forge) and, for
// text_to_avatar, Replicate: no GPU/LLM work happens here, all of it runs on
// the operator-funded backend that holds the provider keys.
//
// One implementation behind the npx-distributed stdio MCP server: every tool in
// mcp-server/src/tools/*.js wraps a core in `paid()`/`free()`, and x402 USDC
// gates the paid ones. The hosted FREE 3D Studio endpoint (/api/mcp-studio) is a
// separate lane over the same /api/forge pipeline, with its own client
// (api/_mcp-studio/forge-client.js), no payment surface, and per-IP rate limits.
//
// Keeping the generation logic here (not forked across the stdio tools) means
// the five generators and refine_model can never drift. This module imports
// nothing payment- or schema-related: only the global `fetch` and the
// dependency-free humanoid classifier, so it loads without the @x402 stack or
// zod-to-json-schema.
import { classifyHumanoidPrompt } from './_humanoid.js';
import { composeRefinement, seedLineage, appendVersion, buildLineageChain, branchFrom } from './_lineage.js';
import { resolveLogoPrompt, BRAND_MARK_DIRECTIVE } from './_logo-lexicon.js';
// Standard tool error envelope — identical shape to payments.js `toolError`, so
// a core's error is indistinguishable whether it is surfaced through the paid
// wrapper or the free one. Duplicated (not imported) because payments.js pulls
// the @x402 stack, which a core must stay loadable without.
export function coreError(code, message, extra) {
return { ok: false, error: code, message, ...(extra || {}) };
}
function env(k, def) {
const v = process.env[k];
return v && String(v).trim() ? String(v).trim() : def;
}
// Resolve the three.ws origin from the first set of the provided env keys,
// trailing slash stripped. Each tool keeps its historical override key.
function apiBaseFrom(keys, def = 'https://three.ws') {
for (const k of keys) {
const v = env(k);
if (v) return v.replace(/\/$/, '');
}
return def.replace(/\/$/, '');
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const VALID_TIER = new Set(['draft', 'standard', 'high']);
const VALID_ASPECT = new Set(['1:1', '4:3', '3:4', '16:9', '9:16']);
// Probe that a generated asset URL is actually fetchable before returning it as
// a success: a degraded lane can hand back an already-expired temp URL, and a
// 404 link reads as breakage downstream. A 1-byte ranged GET is used because
// gradio file routes frequently reject HEAD. Best-effort — any error counts as
// unreachable.
async function isUrlReachable(url) {
if (!url) return false;
try {
const r = await fetch(url, {
method: 'GET',
headers: { range: 'bytes=0-0' },
signal: AbortSignal.timeout(15_000),
});
return r.ok || r.status === 206;
} catch {
return false;
}
}
// ---------------------------------------------------------------------------
// /api/forge client — submit + poll, shared by forge_free / mesh_forge /
// forge_avatar. The three callers differ only in: which backend/path they pin,
// whether a synchronous `status:"done"` submit is acceptable, and the submit
// timeout. Everything else is identical, so it lives here once.
// ---------------------------------------------------------------------------
async function submitForge({ base, payload, submitTimeoutMs, allowSyncDone }) {
let res;
try {
res = await fetch(`${base}/api/forge`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(payload),
signal: AbortSignal.timeout(submitTimeoutMs),
});
} catch (err) {
if (err?.name === 'TimeoutError' || err?.name === 'AbortError') {
const e = new Error('the 3D lane took too long to accept the job; try again');
e.code = 'timeout';
throw e;
}
const e = new Error(`forge unreachable: ${err?.message || err}`);
e.code = 'provider_error';
throw e;
}
const data = await res.json().catch(() => ({}));
if (res.status === 503) {
const e = new Error(data?.message || 'text→3D is not configured on the three.ws deployment');
e.code = 'not_configured';
throw e;
}
if (res.status === 429) {
const e = new Error(data?.message || 'the 3D generator is busy; try again shortly');
e.code = 'rate_limited';
e.retryAfter = data?.retry_after;
throw e;
}
const completedSync = allowSyncDone && data?.status === 'done' && data?.glb_url;
if (!res.ok || !(data?.job_id || completedSync)) {
const e = new Error(data?.message || `forge returned ${res.status}`);
e.code = 'provider_error';
throw e;
}
return data;
}
async function pollForge(jobId, { base, timeoutMs, intervalMs, failCode = 'generation_failed' }) {
const deadline = Date.now() + timeoutMs;
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(intervalMs * 3, 15_000)),
});
} catch (err) {
if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
await sleep(intervalMs);
continue;
}
const e = new Error(`forge poll failed: ${err?.message || err}`);
e.code = 'provider_error';
throw e;
}
const data = await res.json().catch(() => ({}));
if (!res.ok) {
const e = new Error(data?.message || `forge poll returned ${res.status}`);
e.code = 'provider_error';
throw e;
}
last = data;
if (data.status === 'done' && data.glb_url) return data;
if (data.status === 'failed') {
const e = new Error(data.error || 'generation failed');
e.code = failCode;
throw e;
}
await sleep(intervalMs);
}
return { ...(last || {}), _timedOut: true };
}
async function startRig({ base, glbUrl }) {
const 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),
});
const data = await res.json().catch(() => ({}));
if (res.status === 503 || res.status === 501) {
const e = new Error(data?.message || 'auto-rigging is not enabled on the three.ws deployment');
e.code = 'not_configured';
throw e;
}
if (res.status === 429) {
const e = new Error(data?.message || 'the rigger is busy; try again shortly');
e.code = 'rate_limited';
e.retryAfter = data?.retry_after;
throw e;
}
if (!res.ok || !data?.job_id) {
const e = new Error(data?.message || `rig start returned ${res.status}`);
e.code = 'provider_error';
throw e;
}
return data;
}
// Prompt director over the deployed /api/chat SSE endpoint. Returns the refined
// prompt string, or null on ANY failure so the caller falls back to the
// original prompt (fail-soft, never fabricated).
//
// No provider is pinned: this client is anonymous, and /api/chat rejects every
// non-free provider for anonymous callers with 401 (pinning watsonx here used
// to kill the director on every call). Unpinned, the deployment routes the
// request through its anonymous free-provider chain. MESH_FORGE_DIRECTOR_MODEL
// stays available as an explicit override for callers who know their
// deployment's model catalog.
async function directPrompt({ base, rawPrompt, instruction, model }) {
let res;
try {
res = await fetch(`${base}/api/chat`, {
method: 'POST',
headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
body: JSON.stringify({
...(model ? { model } : {}),
message: `${instruction}\n\nIdea: ${rawPrompt}`,
}),
signal: AbortSignal.timeout(30_000),
});
} catch {
return null;
}
if (!res.ok || !res.body) return null;
let acc = '';
try {
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop() ?? '';
for (const line of lines) {
if (!line.startsWith('data: ')) continue;
let evt;
try {
evt = JSON.parse(line.slice(6));
} catch {
continue;
}
if (evt.type === 'chunk' && typeof evt.text === 'string') acc += evt.text;
else if (evt.type === 'error') return null;
else if (evt.type === 'done' && typeof evt.text === 'string' && !acc) acc = evt.text;
}
}
} catch {
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 = acc.trim().split('\n')[0].trim();
const refined = firstLine.replace(/^["'“”]+|["'“”]+$/g, '').trim();
return refined.length >= 3 && refined.length <= 1000 ? refined : null;
}
// Merge a multi-view array with a single image_url, de-duped + order-preserving.
function normalizeViews({ image_url, image_urls }) {
const raw = Array.isArray(image_urls)
? image_urls
: typeof image_url === 'string'
? [image_url]
: [];
const seen = new Set();
const views = [];
for (const v of raw) {
if (typeof v !== 'string') continue;
const t = v.trim();
if (!t || seen.has(t)) continue;
seen.add(t);
views.push(t);
}
return views;
}
// Photoreal cue block shared by both directors below — mirrors the wording in
// api/_lib/forge-director-prompts.js's PHOTOREAL_CUES so this published,
// independently-deployed mcp-server package produces the same realism bar as
// the platform's own /api/forge director. Duplicated rather than imported: this
// package ships standalone (npm), so it cannot reach into the api/ tree.
const PHOTOREAL_CUES =
'shot like a real photograph, not a render or illustration: natural soft studio lighting with gentle wrapping ' +
'shadows, true-to-life color response, and visible micro-detail — fabric weave, skin pores and fine creases, ' +
'brushed-metal grain, natural wear — because nothing in the real world is perfectly clean or perfectly smooth';
// Lightweight subject classifier so this lane can pick a subject-aware cue
// without importing across the api/ package boundary. Whole-word matching so
// "manatee" never reads as "man".
const PERSON_RE = /\b(person|human|man|woman|guy|girl|boy|lady|character|hero|warrior|knight|wizard|ninja|astronaut|robot|android|mascot)\b/i;
const ANIMAL_RE = /\b(animal|creature|dragon|dog|cat|horse|bird|dinosaur|beast|wolf|fox|lion|tiger|bear|monster)\b/i;
const VEHICLE_RE = /\b(car|truck|van|bus|motorcycle|bike|plane|jet|boat|ship|train|tank|spaceship|rocket|vehicle)\b/i;
const FOOD_RE = /\b(food|fruit|vegetable|burger|pizza|cake|bread|sushi|sandwich|donut|cookie|meal|dish|coffee)\b/i;
function classifySubjectLite(text) {
const t = String(text || '');
if (PERSON_RE.test(t)) return 'person';
if (ANIMAL_RE.test(t)) return 'animal';
if (VEHICLE_RE.test(t)) return 'vehicle';
if (FOOD_RE.test(t)) return 'object';
return 'object';
}
const MESH_SUBJECT_CUES = {
person: 'real skin with visible pores and subtle asymmetry, individual hair strands, ordinary human proportions',
animal: 'real fur/feathers/scales with natural directional flow, correct species anatomy, a moist natural nose or beak',
vehicle: 'correct wheel count and panel symmetry, real painted or brushed-metal body panels, rubber tread',
object: "the object's real material, finish, and surface micro-detail (grain, brush marks, wear, weave)",
};
function meshDirectorInstruction(prompt) {
const cue = MESH_SUBJECT_CUES[classifySubjectLite(prompt)] || MESH_SUBJECT_CUES.object;
return (
"You are a 3D asset art director. Rewrite the user's idea into ONE concise prompt for a " +
'text-to-3D generator. Describe a SINGLE isolated subject on a plain background, naming form, ' +
'materials, color, and surface detail. Default to photoreal — an actual photograph of the physical thing, ' +
'not a render or game asset — unless the user clearly asked for a different style (cartoon, low-poly, toy, ' +
'anime, etc.). When photoreal, weave in: ' + PHOTOREAL_CUES + '; specifically call out ' + cue + '. No ' +
'scenes, no multiple objects, no rendered text, no background environment. ' +
BRAND_MARK_DIRECTIVE +
'Output ONLY the rewritten prompt as a single line — no preamble, no quotes.'
);
}
function avatarDirectorInstruction(prompt) {
const subject = classifySubjectLite(prompt) === 'animal' ? 'animal' : 'person';
const subjectCue =
subject === 'animal'
? 'real fur/feathers/scales with natural directional flow, correct species anatomy, lifelike eyes with a catchlight'
: 'real skin with visible pores and subtle asymmetry, hair as many fine individual strands, natural catchlights in the eyes';
return (
"You are a 3D character art director. Rewrite the user's idea into ONE concise prompt for a text-to-3D " +
'generator that will be auto-rigged. Describe a SINGLE full-body humanoid character standing in a relaxed ' +
'neutral pose with arms slightly away from the body, hands open and fingers separated and clearly visible ' +
'(never a closed fist, never a hand hidden behind the body or in a pocket), on a plain background. Default ' +
'to photoreal — a real person (or, for a creature/beast character, a real animal) photographed, not a game ' +
"character or a toy — unless the user's words clearly call for something else (anime, cartoon, chibi, " +
'voxel, toy, low-poly, etc.). When photoreal, weave in: ' + PHOTOREAL_CUES + '; specifically: ' + subjectCue +
'. Name the body type, outfit, materials, colors, and key features. No scene, no props held across the ' +
'body, no multiple characters, no text or logos. Output ONLY the rewritten prompt as a single line — no ' +
'preamble, no quotes.'
);
}
// ---------------------------------------------------------------------------
// forge_free — text → textured 3D GLB on the FREE NVIDIA NIM (TRELLIS) lane.
// ---------------------------------------------------------------------------
export async function runForgeFree({ prompt, tier }) {
const trimmed = typeof prompt === 'string' ? prompt.trim() : '';
if (trimmed.length < 3) {
return coreError('invalid_input', 'Provide a text prompt of at least 3 characters.');
}
const tierId = VALID_TIER.has(tier) ? tier : 'draft';
// Known brand-mark prompts ("<brand name> logo") resolve to a deterministic
// geometric spec of the real mark; this lane has no LLM director, so without
// it the raw brand name reconstructs as a garbled generic badge. The user's
// original prompt stays on the response metadata unchanged.
const knownMark = resolveLogoPrompt(trimmed);
const subject = knownMark ? knownMark.prompt : trimmed;
const base = apiBaseFrom(['FORGE_FREE_API_BASE']);
// A pre-rendered reference view beats any text draw for a known mark: the
// text lane rolls a random colorway per run, the reference reconstructs the
// exact mark. Served by the same deployment the job is submitted to.
const markImageUrls = knownMark?.imagePath ? [`${base}${knownMark.imagePath}`] : undefined;
const startedAt = Date.now();
// The free lane's happy path is the durable NVIDIA NIM (R2-persisted) result.
// When NIM is cold it degrades to a HuggingFace Space whose gradio /tmp URL
// expires within seconds — a non-durable result that can be DEAD on arrival.
// Prefer a durable result via a bounded retry, verify any non-durable URL is
// actually reachable before returning it, and never hand back a confirmed-dead
// link as success. This is what keeps the free smoke-test reliable for a
// reviewer even during a NIM outage. Raise FORGE_FREE_ATTEMPTS to trade
// latency for a better shot at landing the durable lane.
const maxAttempts = Math.max(1, Math.min(4, Number(env('FORGE_FREE_ATTEMPTS', '2')) || 2));
// The free lane is shared and rate-limited, so a reviewer (or any first caller
// during a busy window) can hit a transient `rate_limited` instead of a model.
// That single response should NOT bounce them: it carries a `retryAfter`, so a
// short, bounded backoff lands a real result on the next slot. Budgeted
// separately from the durable-attempt loop so a pure backoff never burns an
// attempt. Genuine failures stay terminal (see the catch below).
const _rateRetriesRaw = Number(env('FORGE_FREE_RATE_RETRIES', '4'));
// `|| 4` would swallow an explicit, valid 0 (0 is falsy) — making the rate
// backoff impossible to disable. Honor 0; only fall back to the default when
// the env value is non-numeric.
const maxRateRetries = Math.max(0, Math.min(6, Number.isFinite(_rateRetriesRaw) ? _rateRetriesRaw : 4));
let liveFallback = null; // first reachable-but-non-durable result, used only if no durable one appears
let rateRetries = 0;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
let gen;
try {
gen = await forgeFreeOnce({ base, prompt: subject, tierId, imageUrls: markImageUrls });
} catch (err) {
// Transient contention on the shared free lane (the generator is busy):
// honor the server's retryAfter (capped 1–8s), back off, and retry
// WITHOUT consuming a durable attempt. This is what keeps the free
// smoke-test reliable for a reviewer during a busy window. Only
// rate_limited is retried here — every OTHER error (generation_failed,
// not_configured, invalid_input, timeout) stays terminal and is surfaced
// immediately, preserving the tool's original error contract.
if (err.code === 'rate_limited' && rateRetries < maxRateRetries) {
rateRetries++;
const waitMs = Math.min(8000, Math.max(1000, (Number(err.retryAfter) || 2) * 1000));
await sleep(waitMs);
attempt--; // a pure backoff must not count against the durable-attempt budget
continue;
}
// The ONLY exception to surfacing immediately: if an earlier attempt
// already produced a reachable result, keep it rather than losing a
// usable model to a later attempt's transient error.
if (liveFallback) break;
return coreError(err.code || 'provider_error', err.message, {
...(err.extra || {}),
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
...(attempt > 1 ? { attempts: attempt } : {}),
...(rateRetries ? { rateRetries } : {}),
durationMs: Date.now() - startedAt,
});
}
// Durable — the reliable, R2-persisted result. Return immediately.
if (gen.data.durable && gen.data.glb_url) {
return shapeForgeFree({
data: gen.data,
prompt: trimmed,
tierId,
jobId: gen.jobId,
base,
startedAt,
attempts: attempt,
});
}
// Non-durable success — only trust it if the ephemeral URL is actually
// fetchable right now. Keep the first reachable one, but keep trying for a
// durable result while attempts remain.
if (gen.data.glb_url && !liveFallback && (await isUrlReachable(gen.data.glb_url))) {
liveFallback = { data: gen.data, jobId: gen.jobId };
}
}
// No durable result across all attempts — fall back to a verified-reachable
// non-durable one (flagged with a `warning` in shapeForgeFree).
if (liveFallback) {
return shapeForgeFree({
data: liveFallback.data,
prompt: trimmed,
tierId,
jobId: liveFallback.jobId,
base,
startedAt,
attempts: maxAttempts,
});
}
// Every attempt produced a non-durable URL that was unreachable — return a
// clear, actionable error instead of a dead "success".
return coreError(
'lane_degraded',
'The free 3D lane produced a result but its URL was unreachable — the durable NVIDIA NIM path is ' +
'momentarily cold and the fallback provider URL expired before it could be used. Please try again shortly.',
{ attempts: maxAttempts, durationMs: Date.now() - startedAt },
);
}
// One forge_free generation attempt: submit to the free draft-tier lane, then
// (when queued) poll to a terminal state. Returns { data, jobId } or throws a
// coded error (with optional `.extra`/`.retryAfter`) the retry loop acts on.
async function forgeFreeOnce({ base, prompt, tierId, imageUrls }) {
const job = await submitForge({
base,
// No backend pin: the forge router's own free-lane resolver picks the
// zero-cost engine (self-host TRELLIS → Hunyuan3D → HuggingFace → NVIDIA
// NIM last resort, see forge-tiers.js FREE_DEFAULT_FOR_TIERS) so this free
// lane gets the photoreal image-intermediate pipeline by default instead
// of forcing NVIDIA's native text-only preview, which skips it entirely.
// path:"image" still applies for a bare text prompt. With a reference
// view (known brand marks) the submit goes image→3D unpinned the same way:
// the forge router owns image-mode engine selection, and the prompt rides
// along as the caption.
payload:
Array.isArray(imageUrls) && imageUrls.length
? { image_urls: imageUrls, prompt: prompt || undefined, tier: tierId }
: { prompt, tier: tierId, path: 'image' },
submitTimeoutMs: 90_000,
allowSyncDone: true,
});
if (job.status === 'done' && job.glb_url) {
return { data: job, jobId: null };
}
const timeoutMs = Number(env('FORGE_FREE_TIMEOUT_MS', '180000'));
const intervalMs = Number(env('FORGE_FREE_POLL_MS', '3000'));
const final = await pollForge(job.job_id, { base, timeoutMs, intervalMs });
if (final._timedOut) {
const e = new Error(`generation did not finish within ${timeoutMs}ms`);
e.code = 'timeout';
e.extra = {
jobId: job.job_id,
creationId: job.creation_id ?? null,
status: final.status || 'running',
resumeUrl: `${base}/api/forge?job=${job.job_id}`,
};
throw e;
}
return { data: final, jobId: job.job_id };
}
function shapeForgeFree({ data, prompt, tierId, jobId, base, startedAt, attempts }) {
const glbUrl = data.glb_url;
const durable = Boolean(data.durable);
const result = {
ok: true,
free: true,
cost: '$0.00',
mode: 'text_to_3d',
glbUrl,
preview: `${base}/viewer?src=${encodeURIComponent(glbUrl)}`,
prompt,
tier: tierId,
backend: data.backend ?? null,
durable,
jobId,
creationId: data.creation_id ?? null,
attempts,
durationMs: Date.now() - startedAt,
fetchedAt: new Date().toISOString(),
};
// A non-durable URL is an ephemeral provider temp file (the free lane degraded
// off the durable NVIDIA NIM path). We only return it after verifying it is
// reachable, but it can still expire soon — flag it so a stale link later is
// never read as breakage, and so the caller views/downloads it promptly.
if (!durable) {
result.verifiedReachable = true;
result.warning =
'Served from an ephemeral provider URL (the free lane degraded off the durable NVIDIA NIM path). ' +
'It is reachable now but may expire soon — open or download it promptly, or call again for a durable result.';
}
return result;
}
// ---------------------------------------------------------------------------
// mesh_forge — text / image / multi-view → textured 3D GLB (Granite-directed).
// ---------------------------------------------------------------------------
export async function runMeshForge({ prompt, image_url, image_urls, aspect_ratio, direct }) {
const trimmedPrompt = typeof prompt === 'string' ? prompt.trim() : '';
const views = normalizeViews({ image_url, image_urls });
if (views.length > 4) {
return coreError('invalid_input', 'Provide between 1 and 4 reference images.');
}
const imageMode = views.length > 0;
if (!imageMode && trimmedPrompt.length < 3) {
return coreError(
'invalid_input',
'Provide a prompt (3+ chars) for text→3D, or 1–4 image_urls for image/multi-view→3D.',
);
}
const aspect = VALID_ASPECT.has(aspect_ratio) ? aspect_ratio : '1:1';
const base = apiBaseFrom(['MESH_FORGE_API_BASE']);
const started = Date.now();
// A known brand-mark prompt resolves deterministically and skips the LLM
// director: the lexicon spec is already a tight, correct description of the
// real mark, and a rewrite could only degrade it.
const knownMark = !imageMode && trimmedPrompt ? resolveLogoPrompt(trimmedPrompt) : null;
const runDirector =
!imageMode && !knownMark && trimmedPrompt && direct !== false && env('MESH_FORGE_DIRECTOR', '1') !== '0';
let directedPrompt = null;
if (runDirector) {
directedPrompt = await directPrompt({
base,
rawPrompt: trimmedPrompt,
instruction: meshDirectorInstruction(trimmedPrompt),
model: env('MESH_FORGE_DIRECTOR_MODEL'),
});
}
const effectivePrompt = knownMark?.prompt || directedPrompt || trimmedPrompt;
// Known marks with a pre-rendered reference view go image→3D: the reference
// reconstructs the exact mark, while a text draw rolls a random colorway.
const markViews = knownMark?.imagePath ? [`${base}${knownMark.imagePath}`] : null;
let job;
try {
job = await submitForge({
base,
payload:
imageMode || markViews
? { image_urls: imageMode ? views : markViews, prompt: effectivePrompt || undefined, aspect_ratio: aspect }
: { prompt: effectivePrompt, aspect_ratio: aspect },
submitTimeoutMs: 30_000,
allowSyncDone: false,
});
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
});
}
const timeoutMs = Number(env('MESH_FORGE_TIMEOUT_MS', '180000'));
const intervalMs = Number(env('MESH_FORGE_POLL_MS', '3000'));
let final;
try {
final = await pollForge(job.job_id, { base, timeoutMs, intervalMs });
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
durationMs: Date.now() - started,
});
}
const durationMs = Date.now() - started;
if (final._timedOut) {
return coreError('timeout', `reconstruction did not finish within ${timeoutMs}ms`, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
status: final.status || 'running',
resumeUrl: `${base}/api/forge?job=${job.job_id}`,
durationMs,
});
}
const glbUrl = final.glb_url;
return {
ok: true,
mode: imageMode ? 'image_to_3d' : 'text_to_3d',
glbUrl,
preview: `${base}/viewer?src=${encodeURIComponent(glbUrl)}`,
prompt: trimmedPrompt || null,
imageUrl: imageMode ? views[0] : null,
imageUrls: imageMode ? views : null,
viewsRequested: imageMode ? views.length : 0,
viewsUsed: (typeof final.views_used === 'number' ? final.views_used : job.views_used) ?? null,
multiview: (final.multiview ?? job.multiview) ?? null,
backend: (final.backend ?? job.backend) ?? null,
directedPrompt: directedPrompt || null,
directed: Boolean(directedPrompt),
jobId: job.job_id,
creationId: final.creation_id ?? job.creation_id ?? null,
referenceImageUrl: job.preview_image_url ?? null,
durable: Boolean(final.durable),
durationMs,
fetchedAt: new Date().toISOString(),
};
}
// ---------------------------------------------------------------------------
// rig_mesh — static GLB → rigged, animation-ready GLB (auto-rig pipeline).
// ---------------------------------------------------------------------------
export async function runRigMesh({ glb_url }) {
const base = apiBaseFrom(['MESH_FORGE_API_BASE']);
const started = Date.now();
let job;
try {
job = await startRig({ base, glbUrl: glb_url });
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
});
}
const timeoutMs = Number(env('RIG_MESH_TIMEOUT_MS', '180000'));
const intervalMs = Number(env('RIG_MESH_POLL_MS', '3000'));
let final;
try {
final = await pollForge(job.job_id, { base, timeoutMs, intervalMs, failCode: 'rig_failed' });
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
durationMs: Date.now() - started,
});
}
const durationMs = Date.now() - started;
if (final._timedOut) {
return coreError('timeout', `rigging did not finish within ${timeoutMs}ms`, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
status: final.status || 'running',
resumeUrl: `${base}/api/forge?job=${job.job_id}`,
durationMs,
});
}
const riggedGlbUrl = final.glb_url;
return {
ok: true,
riggedGlbUrl,
sourceGlbUrl: glb_url,
poseStudioUrl: `${base}/pose?src=${encodeURIComponent(riggedGlbUrl)}`,
jobId: job.job_id,
creationId: final.creation_id ?? job.creation_id ?? null,
durable: Boolean(final.durable),
durationMs,
fetchedAt: new Date().toISOString(),
};
}
// ---------------------------------------------------------------------------
// forge_avatar — one-call text/image → rigged, animation-ready avatar.
// ---------------------------------------------------------------------------
export async function runForgeAvatar({
prompt,
image_url,
image_urls,
aspect_ratio,
direct,
allow_non_humanoid,
}) {
const trimmedPrompt = typeof prompt === 'string' ? prompt.trim() : '';
const views = normalizeViews({ image_url, image_urls });
if (views.length > 4) {
return coreError('invalid_input', 'Provide between 1 and 4 reference images.');
}
const imageMode = views.length > 0;
if (!imageMode && trimmedPrompt.length < 3) {
return coreError(
'invalid_input',
'Provide a prompt (3+ chars) for text→avatar, or 1–4 image_urls for image/multi-view→avatar.',
);
}
// Humanoid gate runs BEFORE any work — rigging assumes a humanoid skeleton.
let humanoidInfo;
if (trimmedPrompt.length >= 3) {
const verdict = classifyHumanoidPrompt(trimmedPrompt);
humanoidInfo = {
humanoid: verdict.humanoid,
confidence: verdict.confidence,
reason: verdict.reason,
};
if (!verdict.humanoid && allow_non_humanoid !== true) {
return coreError(
'not_a_character',
`"${trimmedPrompt}" does not look like a humanoid character (${verdict.reason}). ` +
'Auto-rigging needs a humanoid subject. Use forge_free or mesh_forge to generate a ' +
'non-character mesh, or set allow_non_humanoid:true to rig it anyway.',
{ humanoid: humanoidInfo },
);
}
} else {
humanoidInfo = {
humanoid: true,
confidence: 'low',
reason: 'image-only request; trusting caller intent (no prompt to classify)',
};
}
const aspect = VALID_ASPECT.has(aspect_ratio) ? aspect_ratio : '3:4';
const base = apiBaseFrom(['MESH_FORGE_API_BASE']);
const intervalMs = Number(env('FORGE_AVATAR_POLL_MS', '3000'));
const started = Date.now();
const runDirector =
!imageMode && trimmedPrompt && direct !== false && env('FORGE_AVATAR_DIRECTOR', '1') !== '0';
let directedPrompt = null;
if (runDirector) {
directedPrompt = await directPrompt({
base,
rawPrompt: trimmedPrompt,
instruction: avatarDirectorInstruction(trimmedPrompt),
});
}
const effectivePrompt = directedPrompt || trimmedPrompt;
// Stage 1 — generate the textured mesh. Avatars are IRL-likeness-critical, so
// they always request the 'high' tier: that is the only tier the router maps
// to the self-host Hunyuan3D lane (people/organic-subject strength, portrait
// realism cues in the reference-image stage) ahead of the faster/lower-fidelity
// free defaults (NVIDIA NIM at draft/standard). Without this the avatar chain
// silently ran on the standard tier's default lane and never saw Hunyuan3D.
const genStarted = Date.now();
let genJob;
try {
genJob = await submitForge({
base,
payload: imageMode
? { image_urls: views, prompt: effectivePrompt || undefined, aspect_ratio: aspect, tier: 'high' }
: { prompt: effectivePrompt, aspect_ratio: aspect, tier: 'high' },
submitTimeoutMs: 30_000,
allowSyncDone: true,
});
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
});
}
const genTimeout = Number(env('FORGE_AVATAR_GEN_TIMEOUT_MS', '180000'));
let gen;
if (genJob.status === 'done' && genJob.glb_url) {
gen = genJob;
} else {
try {
gen = await pollForge(genJob.job_id, {
base,
timeoutMs: genTimeout,
intervalMs,
failCode: 'generation_failed',
});
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
stage: 'generation',
jobId: genJob.job_id,
creationId: genJob.creation_id ?? null,
durationMs: Date.now() - started,
});
}
if (gen._timedOut) {
return coreError('timeout', `generation did not finish within ${genTimeout}ms`, {
stage: 'generation',
jobId: genJob.job_id,
creationId: genJob.creation_id ?? null,
resumeUrl: `${base}/api/forge?job=${genJob.job_id}`,
durationMs: Date.now() - started,
});
}
}
const meshGlbUrl = gen.glb_url;
const generationMs = Date.now() - genStarted;
// Rig-stage degrade: the mesh is real, finished work — a rig failure must
// never discard it. Mirror the embody chain's behavior (forge-client.js
// runEmbodyChain): deliver the unrigged mesh as a SUCCESS with rigged:false
// and the rig error attached, so the caller keeps the asset and can retry
// rigging alone (rig_mesh) once the rig lane recovers.
const meshOnlyResult = (rigError) => ({
ok: true,
mode: imageMode ? 'image_to_avatar' : 'text_to_avatar',
riggedGlbUrl: null,
meshGlbUrl,
viewerUrl: `${base}/viewer?src=${encodeURIComponent(meshGlbUrl)}`,
animationReady: false,
rigged: false,
rigError,
prompt: trimmedPrompt || null,
imageUrls: imageMode ? views : null,
viewsUsed: (gen.views_used ?? genJob.views_used) ?? (imageMode ? views.length : 0),
backend: (gen.backend ?? genJob.backend) ?? null,
directedPrompt: directedPrompt || null,
directed: Boolean(directedPrompt),
humanoid: humanoidInfo,
meshCreationId: gen.creation_id ?? genJob.creation_id ?? null,
generationMs,
durationMs: Date.now() - started,
fetchedAt: new Date().toISOString(),
});
// Stage 2 — auto-rig. Failures degrade to the unrigged mesh, never a dead end.
const rigStarted = Date.now();
let rigJob;
try {
rigJob = await startRig({ base, glbUrl: meshGlbUrl });
} catch (err) {
return meshOnlyResult({
code: err.code || 'provider_error',
message: `rigging could not start: ${err.message}`,
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
});
}
const rigTimeout = Number(env('FORGE_AVATAR_RIG_TIMEOUT_MS', '180000'));
let rig;
try {
rig = await pollForge(rigJob.job_id, {
base,
timeoutMs: rigTimeout,
intervalMs,
failCode: 'rig_failed',
});
} catch (err) {
return meshOnlyResult({
code: err.code || 'provider_error',
message: `rigging failed: ${err.message}`,
rigJobId: rigJob.job_id,
});
}
if (rig._timedOut) {
return meshOnlyResult({
code: 'timeout',
message: `rigging did not finish within ${rigTimeout}ms — it may still complete; poll resumeUrl`,
rigJobId: rigJob.job_id,
resumeUrl: `${base}/api/forge?job=${rigJob.job_id}`,
});
}
const riggedGlbUrl = rig.glb_url;
return {
ok: true,
mode: imageMode ? 'image_to_avatar' : 'text_to_avatar',
riggedGlbUrl,
meshGlbUrl,
rigged: true,
poseStudioUrl: `${base}/pose?src=${encodeURIComponent(riggedGlbUrl)}`,
viewerUrl: `${base}/viewer?src=${encodeURIComponent(riggedGlbUrl)}`,
animationReady: true,
prompt: trimmedPrompt || null,
imageUrls: imageMode ? views : null,
viewsUsed: (gen.views_used ?? genJob.views_used) ?? (imageMode ? views.length : 0),
backend: (gen.backend ?? genJob.backend) ?? null,
directedPrompt: directedPrompt || null,
directed: Boolean(directedPrompt),
humanoid: humanoidInfo,
meshCreationId: gen.creation_id ?? genJob.creation_id ?? null,
riggedCreationId: rig.creation_id ?? rigJob.creation_id ?? null,
rigJobId: rigJob.job_id,
durable: Boolean(rig.durable),
generationMs,
rigMs: Date.now() - rigStarted,
durationMs: Date.now() - started,
fetchedAt: new Date().toISOString(),
};
}
// ---------------------------------------------------------------------------
// text_to_avatar — text/image → 3D GLB avatar via Replicate (Hunyuan-3D).
// ---------------------------------------------------------------------------
const REPLICATE_BASE = 'https://api.replicate.com/v1';
function replicateAuthHeaders() {
const token = env('REPLICATE_API_TOKEN');
if (!token) {
const err = new Error('REPLICATE_API_TOKEN is not configured on the server');
err.code = 'not_configured';
throw err;
}
return { authorization: `Bearer ${token}`, 'content-type': 'application/json' };
}
function extractGlbUrl(output) {
if (!output) return null;
if (typeof output === 'string') return output;
if (Array.isArray(output)) {
for (const v of output) {
if (typeof v === 'string' && /\.glb(\?|$)/i.test(v)) return v;
}
for (const v of output) {
if (typeof v === 'string' && /^https?:\/\//.test(v)) return v;
}
}
if (typeof output === 'object') {
for (const key of ['glb', 'mesh', 'mesh_url', 'output_url', 'url', 'model']) {
if (typeof output[key] === 'string') return output[key];
}
}
return null;
}
// Generous: a cold Replicate model can take a while to accept the job, and
// failing early here wastes the user's prompt for nothing.
const SUBMIT_TIMEOUT_MS = 30_000;
async function submitPrediction({ version, input }) {
// The poll loop below is bounded per request, but the submit that starts it
// was not: a stalled connection here held the whole tool invocation open with
// no prediction to poll for. Submitting is not idempotent (a retry buys a
// second GPU run), so this is a deadline only, never a retry.
const res = await fetch(`${REPLICATE_BASE}/predictions`, {
method: 'POST',
headers: replicateAuthHeaders(),
body: JSON.stringify({ version, input }),
signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
});
const data = await res.json().catch(() => ({}));
if (!res.ok) {
const err = new Error(data?.detail || data?.title || `replicate returned ${res.status}`);
err.code = 'provider_error';
err.providerStatus = res.status;
throw err;
}
return data;
}
async function pollPrediction(predictionId, { timeoutMs, intervalMs }) {
const deadline = Date.now() + timeoutMs;
let last = null;
const perFetchTimeoutMs = Math.max(intervalMs * 3, 10_000);
while (Date.now() < deadline) {
let r;
try {
r = await fetch(`${REPLICATE_BASE}/predictions/${encodeURIComponent(predictionId)}`, {
headers: replicateAuthHeaders(),
signal: AbortSignal.timeout(perFetchTimeoutMs),
});
} catch (err) {
if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
await sleep(intervalMs);
continue;
}
const e = new Error(`replicate poll fetch failed: ${err?.message || err}`);
e.code = 'provider_error';
throw e;
}
const data = await r.json().catch(() => ({}));
if (!r.ok) {
const err = new Error(data?.detail || `replicate poll returned ${r.status}`);
err.code = 'provider_error';
throw err;
}
last = data;
const s = data.status;
if (s === 'succeeded' || s === 'failed' || s === 'canceled') return data;
await sleep(intervalMs);
}
return { ...last, _timedOut: true };
}
async function rehostIfRequested(glbUrl, { prompt, images }) {
if (env('MCP_TEXT_TO_AVATAR_REHOST', '0') !== '1') return null;
const endpoint = env('MCP_REHOST_ENDPOINT', 'https://three.ws/api/avatars/ingest-url');
const ingestKey = env('MCP_REHOST_KEY');
if (!ingestKey) return null;
try {
const r = await fetch(endpoint, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${ingestKey}` },
body: JSON.stringify({
source_url: glbUrl,
name: (prompt || 'text-to-avatar').slice(0, 80),
source: 'mcp',
source_meta: { provider: 'replicate', prompt, images },
}),
});
if (!r.ok) return { error: `rehost failed: ${r.status}` };
return await r.json();
} catch (err) {
return { error: err?.message || 'rehost call failed' };
}
}
// The platform's own free-first forge chain (mesh + auto-rig via /api/forge) —
// the standing backup when the pinned Replicate lane is unconfigured or fails
// mid-flight. Maps the chain result onto text_to_avatar's output shape with the
// lane switch reported honestly (`lane`, `fallback_from`, `fallbackReason`);
// when the rig stage succeeds the caller even gets a RIGGED avatar — strictly
// more than the Replicate lane's raw mesh, never less.
async function textToAvatarViaForgeChain({ prompt, images, reason }) {
const chain = await runForgeAvatar({
prompt,
image_urls: images && images.length ? images : undefined,
// text_to_avatar has no humanoid restriction (Hunyuan reconstructs any
// subject), so the chain's humanoid gate must not narrow it.
allow_non_humanoid: true,
});
if (!chain.ok) {
// Both lanes down. Lead with the Replicate failure (it names what an
// operator must fix); attach the chain's own error for completeness.
return coreError('all_lanes_failed', `${reason}; forge-chain fallback also failed: ${chain.message || chain.error}`, {
fallbackError: chain.error || null,
});
}
const glbUrl = chain.riggedGlbUrl || chain.meshGlbUrl;
return {
ok: true,
glbUrl,
rigged: Boolean(chain.riggedGlbUrl),
lane: 'three-ws-forge-chain',
fallback_from: 'replicate',
fallbackReason: reason,
prompt: prompt || null,
images: images && images.length ? images : null,
model: chain.backend ? `three-ws/${chain.backend}` : 'three-ws/forge',
durationMs: chain.durationMs ?? null,
preview: chain.viewerUrl || `https://three.ws/viewer?src=${encodeURIComponent(glbUrl)}`,
fetchedAt: new Date().toISOString(),
};
}
export async function runTextToAvatar({ prompt, images, seed, texture }) {
if (!prompt && (!images || images.length === 0)) {
return coreError('invalid_input', 'Provide either prompt or images[].');
}
const version = env('REPLICATE_TEXT_TO_AVATAR_MODEL');
if (!version || !env('REPLICATE_API_TOKEN')) {
// The pinned Replicate lane isn't configured — serve the request on the
// platform's own forge chain instead of dead-ending a paid tool.
return textToAvatarViaForgeChain({
prompt,
images,
reason: !version ? 'REPLICATE_TEXT_TO_AVATAR_MODEL is not set' : 'REPLICATE_API_TOKEN is not set',
});
}
// Granite avatar director (text mode only, fail-soft): without this the
// Replicate lane reconstructed straight from the raw words with none of the
// photoreal briefing the platform's own forge_avatar chain already gets.
let effectivePrompt = prompt;
if (prompt && (!images || images.length === 0) && env('TEXT_TO_AVATAR_DIRECTOR', '1') !== '0') {
const directed = await directPrompt({
base: apiBaseFrom(['MESH_FORGE_API_BASE']),
rawPrompt: prompt,
instruction: avatarDirectorInstruction(prompt),
});
if (directed) effectivePrompt = directed;
}
const input = {
prompt: effectivePrompt || undefined,
image: images && images.length ? images[0] : undefined,
images: images && images.length ? images : undefined,
seed: typeof seed === 'number' ? seed : undefined,
texture: typeof texture === 'boolean' ? texture : true,
};
Object.keys(input).forEach((k) => input[k] === undefined && delete input[k]);
const started = Date.now();
let submitted;
try {
submitted = await submitPrediction({ version, input });
} catch (err) {
// Replicate rejected the submit (auth, quota, outage) — hop to the forge
// chain rather than dead-ending a paid tool on a vendor problem.
return textToAvatarViaForgeChain({ prompt, images, reason: `replicate submit failed: ${err.message}` });
}
const timeoutMs = Number(env('MCP_TEXT_TO_AVATAR_TIMEOUT_MS', '110000'));
const intervalMs = Number(env('MCP_TEXT_TO_AVATAR_POLL_MS', '2000'));
let finalState;
try {
finalState = await pollPrediction(submitted.id, { timeoutMs, intervalMs });
} catch (err) {
return textToAvatarViaForgeChain({
prompt,
images,
reason: `replicate poll failed (prediction ${submitted.id}): ${err.message}`,
});
}
const durationMs = Date.now() - started;
if (finalState._timedOut) {
// The prediction may still complete — resumeUrl lets the caller pick it
// up, so a timeout is NOT "nothing" and does not trigger a second full
// generation on the fallback chain.
return coreError('timeout', `prediction did not finish within ${timeoutMs}ms`, {
predictionId: submitted.id,
status: finalState.status,
resumeUrl: `${REPLICATE_BASE}/predictions/${submitted.id}`,
durationMs,
});
}
if (finalState.status === 'failed' || finalState.status === 'canceled') {
return textToAvatarViaForgeChain({
prompt,
images,
reason: `replicate prediction ${finalState.status}: ${finalState.error || 'no detail'}`,
});
}
const glbUrl = extractGlbUrl(finalState.output);
if (!glbUrl) {
return textToAvatarViaForgeChain({
prompt,
images,
reason: `replicate prediction ${submitted.id} succeeded but returned no GLB`,
});
}
const rehost = await rehostIfRequested(glbUrl, { prompt, images });
return {
ok: true,
predictionId: submitted.id,
glbUrl,
rehosted: rehost,
prompt: prompt || null,
images: images || null,
seed: typeof seed === 'number' ? seed : null,
model: version,
durationMs,
preview: `https://three.ws/viewer?src=${encodeURIComponent(glbUrl)}`,
fetchedAt: new Date().toISOString(),
};
}
// ---------------------------------------------------------------------------
// refine_model — conversational refinement: carry a model forward with a
// natural-language change instruction. The prior prompt is folded into the new
// generation prompt so form, material, and subject carry forward. A reference
// image (2D preview/screenshot of the parent) anchors the generation when
// provided; otherwise text-only re-generation is used — still real, still
// anchored through the composed prompt.
//
// Lineage: pass parent_lineage to extend an existing version history, or omit
// to start a fresh lineage rooted at glb_url. The returned lineage array
// supports revert (pointer move, no mutation) and branch (parentIndex override).
// ---------------------------------------------------------------------------
export async function runRefineModel({
glb_url,
instruction,
parent_prompt,
parent_lineage,
parent_index,
reference_image_url,
}) {
if (!glb_url || typeof glb_url !== 'string' || !glb_url.trim()) {
return coreError('invalid_input', 'Provide glb_url of the model to refine.');
}
const instructionTrimmed = typeof instruction === 'string' ? instruction.trim() : '';
if (!instructionTrimmed) {
return coreError('invalid_input', 'Provide an instruction describing the change to make.');
}
const parentPromptStr = typeof parent_prompt === 'string' ? parent_prompt.trim() : '';
const composedPrompt = composeRefinement(parentPromptStr, instructionTrimmed);
// Resolve starting lineage: extend an existing one, or seed from the parent.
// A caller-supplied parent_lineage is UNTRUSTED — validate its structural
// integrity (contiguous indices, single root, no cycles) with buildLineageChain
// before extending. A malformed array falls back to a fresh lineage rooted at
// glb_url rather than corrupting history.
const baseLineage =
Array.isArray(parent_lineage) && parent_lineage.length > 0 && buildLineageChain(parent_lineage).ok
? parent_lineage
: seedLineage({ glbUrl: glb_url.trim(), prompt: parentPromptStr || null });
// Branch point: branchFrom validates the index against the lineage; an
// out-of-range index falls back to extending the leaf.
let effectiveParentIndex;
if (Number.isInteger(parent_index)) {
try {
effectiveParentIndex = branchFrom(baseLineage, parent_index);
} catch {
effectiveParentIndex = undefined;
}
}
const base = apiBaseFrom(['MESH_FORGE_API_BASE']);
const started = Date.now();
const refImageUrl =
typeof reference_image_url === 'string' && reference_image_url.trim()
? reference_image_url.trim()
: null;
let job;
try {
job = await submitForge({
base,
payload: refImageUrl
? { image_urls: [refImageUrl], prompt: composedPrompt }
: { prompt: composedPrompt },
submitTimeoutMs: 30_000,
allowSyncDone: false,
});
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
});
}
const timeoutMs = Number(env('REFINE_MODEL_TIMEOUT_MS', '180000'));
const intervalMs = Number(env('REFINE_MODEL_POLL_MS', '3000'));
let final;
try {
final = await pollForge(job.job_id, { base, timeoutMs, intervalMs });
} catch (err) {
return coreError(err.code || 'provider_error', err.message, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
durationMs: Date.now() - started,
});
}
const durationMs = Date.now() - started;
if (final._timedOut) {
return coreError('timeout', `refinement did not finish within ${timeoutMs}ms`, {
jobId: job.job_id,
creationId: job.creation_id ?? null,
status: final.status || 'running',
resumeUrl: `${base}/api/forge?job=${job.job_id}`,
durationMs,
});
}
const newGlbUrl = final.glb_url;
const viewerUrl = `${base}/viewer?src=${encodeURIComponent(newGlbUrl)}`;
const lineage = appendVersion(baseLineage, {
glbUrl: newGlbUrl,
viewerUrl,
prompt: composedPrompt,
instruction: instructionTrimmed,
refKind: refImageUrl ? 'image' : 'text',
...(effectiveParentIndex !== undefined ? { parentIndex: effectiveParentIndex } : {}),
});
const activeIndex = lineage.length - 1;
return {
ok: true,
mode: 'refine',
glbUrl: newGlbUrl,
viewerUrl,
composedPrompt,
instruction: instructionTrimmed,
parentGlbUrl: glb_url.trim(),
anchored: Boolean(refImageUrl),
referenceImageUrl: refImageUrl,
backend: (final.backend ?? job.backend) ?? null,
jobId: job.job_id,
creationId: final.creation_id ?? job.creation_id ?? null,
durable: Boolean(final.durable),
lineage,
activeIndex,
durationMs,
fetchedAt: new Date().toISOString(),
};
}