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.

14.8 KB
Raw Blame
// forge-frames.js — pure logic for the Live Avatar Forge.
//
// Shared by THREE callers so the staged narration and the final-frame sidecar
// never drift between them:
//   • src/agent-screen.js   — the in-browser forge driver (the viewer watches)
//   • workers/agent-forge/   — the headless broadcast worker
//   • tests/forge-frame.test.js
//
// Zero DOM, zero env, zero network: every export is a pure function of its
// input. The real generation (POST/poll /api/forge on the free NVIDIA NIM
// TRELLIS lane) and the real GLB load/animation live in the callers; this file
// only turns a generation state into a holder-readable line and packs/unpacks
// the GLB url that rides along with the final frame.

// The free TRELLIS lane conditions on ~77 characters; a longer prompt is
// silently truncated by the model, so we trim with intent and tell the user.
export const TRELLIS_PROMPT_LIMIT = 77;

const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));

// Normalize a raw prompt for the free lane. Returns the cleaned prompt, whether
// it was trimmed to the conditioning window, and the original length so the UI
// can show "trimmed to fit". Trimming happens on a word boundary when possible
// so we never cut a word in half mid-token.
export function clampPrompt(raw) {
	const text = String(raw == null ? '' : raw).replace(/\s+/g, ' ').trim();
	if (text.length <= TRELLIS_PROMPT_LIMIT) {
		return { prompt: text, trimmed: false, originalLength: text.length };
	}
	let cut = text.slice(0, TRELLIS_PROMPT_LIMIT);
	const lastSpace = cut.lastIndexOf(' ');
	// Only snap to the word boundary if it doesn't throw away too much (>60% kept).
	if (lastSpace > TRELLIS_PROMPT_LIMIT * 0.6) cut = cut.slice(0, lastSpace);
	return { prompt: cut.trim(), trimmed: true, originalLength: text.length };
}

// Is a prompt acceptable to submit? The free lane needs ≥3 characters of actual
// subject. Returns { ok } or { ok:false, reason } with a holder-readable reason.
export function validatePrompt(raw) {
	const text = String(raw == null ? '' : raw).trim();
	if (text.length < 3) {
		return { ok: false, reason: 'Describe a concrete object — at least a few characters.' };
	}
	return { ok: true };
}

// Backend id → the lane name a person recognizes, so a narration can name the
// engine that actually ran instead of guessing one. Mirrors ENGINE_LABELS in
// src/forge.js; it lives here because this module is the one every non-/forge
// surface shares (agent-screen, ar-studio, workers/agent-forge). An unknown or
// absent id returns null, and callers fall back to a lane-agnostic line.
const LANE_LABELS = {
	nvidia: 'free NVIDIA NIM',
	huggingface: 'free Hunyuan3D',
	trellis: 'Fast',
	trellis2: 'TRELLIS.2',
	trellis_selfhost: 'TRELLIS',
	modly: 'Modly TripoSG',
	modly_hunyuan: 'Modly Hunyuan',
	meshy: 'Meshy',
	tripo: 'Tripo',
	rodin: 'Rodin',
	stability: 'Stability',
	replicate_byok: 'Replicate',
	hunyuan3d: 'Hunyuan3D',
	triposg: 'TripoSG',
};

export function laneLabel(backendId) {
	const id = String(backendId == null ? '' : backendId).trim();
	return LANE_LABELS[id] || null;
}

// Map a real /api/forge job/poll state to a single holder-readable narration
// line. The states come straight from the pipeline — no fabricated steps:
//   submitting           → before the job is accepted
//   queued               → accepted, waiting for a free GPU slot
//   running / reconstruct → the mesh is being built (TRELLIS reconstruct)
//   done                 → GLB ready
//   failed               → generation failed
// `mode` ('image' before the mesh stage) and `eta_seconds` refine the line when
// the pipeline reports them. Unknown states fall back to a neutral "working".
//
// Two optional numbers make a wait measurable instead of merely named, and both
// come off the poll payload (/api/forge returns `elapsed_seconds` and
// `eta_remaining_seconds` on every non-terminal poll): `elapsed_seconds` is how
// long the job has really been alive, `eta_remaining_seconds` is the lane's
// typical total minus that. Neither is ever synthesized here from a local clock,
// so a page reopened mid-generation reports the job's age, not the tab's.
export function forgeStageNarration(state = {}) {
	const status = String(state.status || state.stage || '').toLowerCase();
	const num = (v) => (Number(v) > 0 ? Math.round(Number(v)) : null);
	const eta = num(state.eta_seconds);
	const elapsed = Number(state.elapsed_seconds) >= 0 ? Math.round(Number(state.elapsed_seconds)) : null;
	// Prefer the live remaining estimate: repeating the lane's static total on
	// every frame is what made a poll loop read as "stuck at ~60s" for a minute.
	const remaining = num(state.eta_remaining_seconds) ?? eta;
	const etaSuffix = remaining ? ` (~${remaining}s left)` : '';
	// The lane that actually ran, when the caller knows it. Older callers pass no
	// `backend`, so every line degrades to a lane-agnostic phrasing rather than
	// naming the wrong engine.
	const lane = laneLabel(state.backend);
	const laneSuffix = lane ? ` on the ${lane} lane` : ' on the free lane';
	// A scale-to-zero GPU worker booting is a real, nameable wait, not a stall.
	// `cold_seconds` is the lane's spin-up budget from the API, never a timer we
	// invent; without it we still name the state but promise no number.
	const cold = Boolean(state.cold_start);
	const coldSeconds = num(state.cold_seconds);
	const coldWho = lane ? ` ${lane}` : '';
	// Elapsed is only worth showing once it means something; under 5s it just
	// flickers. A boot past its budget says so instead of counting into negatives.
	const elapsedSuffix = elapsed != null && elapsed >= 5 ? ` (${elapsed}s in)` : '';

	switch (status) {
		case 'submitting':
		case 'submit':
			return `Forging${laneSuffix}…`;
		case 'queued':
		case 'queue':
			if (cold) {
				if (!coldSeconds) return `Waking up the${coldWho} GPU worker, then sculpting starts`;
				const bootLeft = elapsed != null ? coldSeconds - elapsed : null;
				if (bootLeft != null && bootLeft <= 0) {
					return `Still waking the${coldWho} GPU worker${elapsedSuffix}. The job is accepted and starts the moment it answers`;
				}
				return bootLeft != null
					? `Waking up the${coldWho} GPU worker${elapsedSuffix}, about ${bootLeft}s of boot left, then sculpting starts`
					: `Waking up the${coldWho} GPU worker (about ${coldSeconds}s), then sculpting starts`;
			}
			return `Queued${laneSuffix}${elapsedSuffix}${etaSuffix}`;
		case 'image':
		case 'texturing':
			return 'Drafting the look…';
		case 'running':
		case 'reconstruct':
		case 'mesh':
			return `Building geometry & texturing${elapsedSuffix}${etaSuffix}`;
		case 'done':
		case 'ready':
			return 'Model ready — loading into the cam';
		case 'failed':
		case 'error':
			return 'Forge failed — try a more concrete prompt';
		default:
			return `Forging${etaSuffix}`;
	}
}

// Cold-start state for one real /api/forge frame, or null when the API is not
// reporting a boot.
//
// A queued job on a scale-to-zero GPU worker is waiting on a container start,
// not on a queue of other people's work, and the two need different words: "in
// line for a GPU" says something is ahead of you, which is both wrong and
// unfixable-sounding, when in fact nothing is ahead and the wait has a known
// end. The API states the flag and the lane's spin-up budget (`cold_start`,
// `cold_start_seconds`) and reports the JOB's age (`elapsed_seconds`), so every
// number below is read off the payload. Nothing is timed locally, which is what
// keeps a page resumed mid-generation from restarting the countdown at zero.
//
// Shared because four surfaces render this state (the homepage chamber, the
// Studio step list, the in-world prop forge, and the MCP tool responses) and
// three of them had grown their own copy of the arithmetic.
//
// @returns {null | { budgetSeconds: number|null, elapsedSeconds: number|null,
//                    remainingSeconds: number|null, pastBudget: boolean }}
export function coldStartState(job = {}) {
	if (!job || !job.cold_start) return null;
	const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);
	// Guard null BEFORE the numeric compare: Number(null) is 0, which would report
	// a job of unknown age as "0s in".
	const elapsedSeconds =
		job.elapsed_seconds == null || !Number.isFinite(Number(job.elapsed_seconds)) || Number(job.elapsed_seconds) < 0
			? null
			: Math.round(Number(job.elapsed_seconds));
	const budgetSeconds = num(job.cold_start_seconds);
	const left = budgetSeconds != null && elapsedSeconds != null ? budgetSeconds - elapsedSeconds : null;
	return {
		budgetSeconds,
		elapsedSeconds,
		remainingSeconds: left != null && left > 0 ? left : null,
		// A boot that has run past its stated budget says so rather than counting
		// into negatives.
		pastBudget: left != null && left <= 0,
	};
}

// The short phrase every surface leads with, from coldStartState(). Returns null
// when the frame reports no boot, so a caller keeps its own queued/running copy.
// Callers append their own tail ("then sculpting starts", an ellipsis, nothing).
export function coldStartLabel(job = {}) {
	const c = coldStartState(job);
	if (!c) return null;
	const inNote = c.elapsedSeconds != null && c.elapsedSeconds >= 5 ? ` (${c.elapsedSeconds}s in)` : '';
	if (c.remainingSeconds != null) return `Waking up a GPU: about ${c.remainingSeconds}s of boot left${inNote}`;
	if (c.pastBudget) return `Still waking the GPU${inNote}`;
	return c.budgetSeconds != null ? `Waking up a GPU (about ${c.budgetSeconds}s)` : 'Waking up a GPU';
}

// A forge progress frame for screenPush — the live narration other viewers see.
// `type: 'analysis'` matches the activity-log "analysis" lane. The optional
// `meta` rides in the frame sidecar (used only on the final frame).
export function buildForgeFrame({ activity, type = 'analysis', meta = null }) {
	const frame = { activity: String(activity || ''), type };
	if (meta && typeof meta === 'object') frame.meta = meta;
	return frame;
}

// The final forge frame: narration + a sidecar carrying the durable GLB url and
// the three.ws viewer link so every connected viewer can load and animate the
// freshly-forged avatar. `kind:'forge'` tags it for parseForgeFrame().
export function finalForgeFrame({ prompt, glbUrl, viewerUrl, tier = null, backend = null, durable = null }) {
	const meta = {
		kind: 'forge',
		glbUrl: String(glbUrl || ''),
		viewerUrl: String(viewerUrl || ''),
		prompt: String(prompt || ''),
	};
	if (tier) meta.tier = String(tier);
	if (backend) meta.backend = String(backend);
	if (durable != null) meta.durable = Boolean(durable);
	const shortPrompt = meta.prompt.length > 60 ? `${meta.prompt.slice(0, 57)}…` : meta.prompt;
	return buildForgeFrame({
		activity: `Forged "${shortPrompt}" — rigging & animating`,
		type: 'analysis',
		meta,
	});
}

// Pull the forge sidecar out of an incoming SSE frame, or null if the frame
// isn't a forge-completion frame. Validates the GLB url is an http(s) link so a
// viewer never tries to load a junk value. Used by the viewer (agent-screen.js)
// to know when to swap the Avatar Cam to the new model, and by the live wall
// (agents-live.js) to show "forged: <prompt>".
export function parseForgeFrame(frame) {
	const meta = frame && typeof frame === 'object' ? frame.meta : null;
	if (!meta || meta.kind !== 'forge') return null;
	const glbUrl = typeof meta.glbUrl === 'string' ? meta.glbUrl.trim() : '';
	if (!/^https?:\/\//i.test(glbUrl)) return null;
	const viewerUrl = typeof meta.viewerUrl === 'string' && /^https?:\/\//i.test(meta.viewerUrl.trim())
		? meta.viewerUrl.trim()
		: '';
	return {
		glbUrl,
		viewerUrl,
		prompt: typeof meta.prompt === 'string' ? meta.prompt : '',
		tier: typeof meta.tier === 'string' ? meta.tier : null,
		backend: typeof meta.backend === 'string' ? meta.backend : null,
		durable: typeof meta.durable === 'boolean' ? meta.durable : null,
	};
}

// Build the three.ws viewer link for a GLB url, given a site origin. Mirrors the
// `${base}/viewer?src=…` link the forge tools return.
export function viewerLinkFor(glbUrl, origin = 'https://three.ws') {
	const base = String(origin || 'https://three.ws').replace(/\/$/, '');
	return `${base}/viewer?src=${encodeURIComponent(String(glbUrl || ''))}`;
}

// A bounded, sanitized sidecar for the push API to persist. Caps every string so
// a frame record can't be inflated past the store's size budget, and drops any
// field that isn't part of the forge contract. Returns null for non-forge meta.
export function sanitizeFrameMeta(meta, { maxLen = 2048 } = {}) {
	if (!meta || typeof meta !== 'object') return null;
	if (meta.kind === 'a2a_hire') return sanitizeHireMeta(meta);
	if (meta.kind !== 'forge') return null;
	const str = (v, n) => (typeof v === 'string' ? v.slice(0, n) : '');
	const out = {
		kind: 'forge',
		glbUrl: str(meta.glbUrl, maxLen),
		viewerUrl: str(meta.viewerUrl, maxLen),
		prompt: str(meta.prompt, 320),
	};
	if (typeof meta.tier === 'string') out.tier = meta.tier.slice(0, 32);
	if (typeof meta.backend === 'string') out.backend = meta.backend.slice(0, 64);
	if (typeof meta.durable === 'boolean') out.durable = meta.durable;
	// A forge sidecar is only meaningful with an http(s) GLB url.
	if (!/^https?:\/\//i.test(out.glbUrl)) return null;
	return out;
}

// Bounded sanitizer for the live agent-to-agent hire visualizer sidecar. Mirrors
// the shape api/_lib/a2a-hire-phases.js#hirePhaseFrame emits: a phase tag plus the
// quote/cap/signature payload the receipt + coin-transfer UI render. Strings are
// capped; explorer urls are http(s)-gated so a push can't smuggle a junk link to
// the viewer; numbers are coerced finite-or-null.
function sanitizeHireMeta(meta) {
	const str = (v, n) => (typeof v === 'string' ? v.slice(0, n) : null);
	const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
	const httpUrl = (v) => {
		const s = str(v, 512);
		return s && /^https?:\/\//i.test(s) ? s : null;
	};
	const cap = meta.cap && typeof meta.cap === 'object'
		? {
			perCallCap: num(meta.cap.perCallCap),
			dailyUsd: num(meta.cap.dailyUsd),
			dailyRemaining: num(meta.cap.dailyRemaining),
			overCap: typeof meta.cap.overCap === 'boolean' ? meta.cap.overCap : undefined,
		}
		: null;
	return {
		kind: 'a2a_hire',
		phase: str(meta.phase, 32),
		phaseIndex: num(meta.phaseIndex),
		ok: typeof meta.ok === 'boolean' ? meta.ok : true,
		hireId: str(meta.hireId, 64),
		slug: str(meta.slug, 120),
		skill: str(meta.skill, 120),
		providerName: str(meta.providerName, 120),
		providerId: str(meta.providerId, 64),
		hirerId: str(meta.hirerId, 64),
		hirerName: str(meta.hirerName, 120),
		usd: num(meta.usd),
		maxUsd: num(meta.maxUsd),
		cap,
		network: str(meta.network, 16) || 'mainnet',
		txSig: str(meta.txSig, 128),
		paymentExplorer: httpUrl(meta.paymentExplorer),
		invocationSig: str(meta.invocationSig, 128),
		invocationExplorer: httpUrl(meta.invocationExplorer),
		resultSummary: str(meta.resultSummary, 280),
		error: str(meta.error, 280),
	};
}

export { clamp as _clamp };