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
// Studio wiring for run receipts (api/_lib/run-receipt.js): one receipt per
// generating tool call, stating what each stage was expected to do, what it
// actually did, and the verdict, then sealed, stored and linked from the result.
//
// A receipt never changes what a tool returns, only adds to it: a
// `structuredContent.receipt` block and one closing line of text. Every step
// here fails open. If sealing, storing or the rig read-back fails, the model
// still goes out exactly as before, just with a receipt that says so (or, with
// no database, an inline receipt and no link).
//
// Data minimization: the receipt id is a fresh random public handle, the same
// footing as the job handle a pending result already carries. The job handle
// itself is never stored, only its hash (jobRef), which is how check_job finds
// the pending receipt it should complete.
import {
startReceipt,
addStage,
finishReceipt,
jobRef,
inputStage,
subjectGateStage,
briefStage,
meshStage,
geometryStage,
visualQaStage,
rigStage,
deliveryStage,
} from '../_lib/run-receipt.js';
import {
sealReceipt,
saveReceipt,
loadReceiptForJob,
inspectRiggedGlb,
engineLabel,
receiptUrl,
} from '../_lib/run-receipt-store.js';
export { inputStage, subjectGateStage, briefStage, rigStage, deliveryStage, inspectRiggedGlb };
/** A request turned away at the input boundary for a reason other than safety. */
export function inputRejected({ expected, message }) {
return { id: 'input', label: 'Input', expected, observed: 'The input was rejected before any work ran.', verdict: 'missed', cause: message };
}
/**
* Open a receipt for one tool call. `plan` is what the caller asked for in
* pipeline terms (the tier, whether a rig follows), kept on the receipt so a
* job collected later by check_job is judged against the same contract.
*/
export function openRun(tool, { prompt, hasImage = false, tier = null, rig = false } = {}) {
const receipt = startReceipt({ tool, prompt, hasImage });
receipt.plan = { tier, rig: Boolean(rig) };
return runFor(receipt);
}
function runFor(receipt) {
return {
receipt,
add(stage) {
try {
addStage(receipt, stage);
} catch (err) {
console.warn('[run-receipt] stage dropped:', err?.message || err);
}
},
/** Mesh, geometry score and vision verdict, all read off one terminal job frame. */
mesh(frame, { error, timedOut, ms } = {}) {
this.add(meshStage({ frame, expectedTier: receipt.plan.tier, error, timedOut, ms, labelFor: engineLabel }));
if (frame?.glb_url && !error && !timedOut) {
this.add(geometryStage({ quality: frame.quality, retried: frame.quality_retried === true }));
this.add(visualQaStage({ gate: frame.quality_gate }));
}
},
};
}
function compactIssues(issues) {
return issues.map((i) => ({
stage: i.stage,
label: i.label,
verdict: i.verdict,
expected: i.expected,
observed: i.observed,
...(i.cause ? { cause: i.cause } : {}),
}));
}
/** Add the receipt to a tool result without disturbing anything already in it. */
export function attachReceipt(result, receipt, url) {
if (!result || !receipt) return result;
const block = {
id: receipt.id,
outcome: receipt.outcome,
summary: receipt.summary,
issues: compactIssues(receipt.issues || []),
...(url ? { url } : {}),
};
const line = url
? `Run receipt (what each stage was expected to do and what it did): ${url}`
: `Run receipt: ${receipt.summary}`;
const content = Array.isArray(result.content) ? [...result.content] : [];
const at = content.findIndex((c) => c?.type === 'text');
if (at >= 0) content[at] = { ...content[at], text: `${content[at].text}\n${line}` };
else content.push({ type: 'text', text: line });
return { ...result, content, structuredContent: { ...(result.structuredContent || {}), receipt: block } };
}
/**
* Finish, seal, store and attach. `jobId` marks a pending run so check_job can
* complete it; `redactPrompt` drops the prompt from a refusal's record.
*/
export async function closeRun(run, result, { base, outcome, jobId, redactPrompt = false } = {}) {
try {
if (redactPrompt) run.receipt.input.prompt = null;
const sc = result?.structuredContent || {};
const glbUrl = result?.isError ? null : sc.glbUrl || sc.glb_url || null;
const finished = finishReceipt(run.receipt, { outcome, glbUrl, viewerUrl: glbUrl ? sc.viewer_url || sc.viewerUrl : undefined });
const envelope = await sealReceipt(finished);
const stored = await saveReceipt(envelope, { jobRef: jobRef(jobId) });
return attachReceipt(result, envelope.receipt, stored ? receiptUrl(base, finished.id) : null);
} catch (err) {
console.warn('[run-receipt] not attached:', err?.message || err);
return result;
}
}
// The fields finishReceipt adds; stripped before a pending receipt is re-opened.
const FINISH_FIELDS = ['finished_at', 'duration_ms', 'outcome', 'summary', 'issues', 'output'];
/**
* check_job collected a job some tool call left pending. Find that call's
* receipt, record what the job actually produced against the same contract,
* and re-seal it. `data` is the terminal poll payload; `failure` is the copy for
* a failed job. Resolves to the result with the receipt attached, or the result
* untouched when the job has no pending receipt.
*/
export async function completeRun(result, { base, jobId, data, failure }) {
try {
const ref = jobRef(jobId);
const envelope = await loadReceiptForJob(ref);
if (!envelope) return result;
if (envelope.receipt.outcome !== 'pending') return attachReceipt(result, envelope.receipt, receiptUrl(base, envelope.receipt.id));
const receipt = { ...envelope.receipt, stages: [...(envelope.receipt.stages || [])] };
for (const f of FINISH_FIELDS) delete receipt[f];
receipt.plan = receipt.plan || { tier: null, rig: false };
const run = runFor(receipt);
const pendingStage = receipt.stages.find((s) => s.verdict === 'pending');
const elapsedMs = Number.isFinite(Number(data?.elapsed_seconds)) ? Number(data.elapsed_seconds) * 1000 : undefined;
let outcome;
if (failure) {
const id = pendingStage?.id || 'mesh';
run.add(id === 'rig' ? rigStage({ error: failure, ms: elapsedMs }) : meshStage({ error: failure, expectedTier: receipt.plan.tier, ms: elapsedMs }));
} else if (pendingStage?.id === 'rig') {
const inspected = await inspectRiggedGlb(data.glb_url);
run.add(rigStage({ report: inspected.report, inspectError: inspected.error, ms: elapsedMs }));
run.add(deliveryStage({ frame: data }));
} else {
run.mesh(data, { ms: elapsedMs });
if (receipt.plan.rig) {
run.add({
id: 'rig',
label: 'Rig',
expected: 'A skinned humanoid skeleton the animation library can drive: torso, arms and legs mapped.',
observed: 'The mesh outlived the inline wait, so rigging moved to a follow-up rig_mesh call (the viewer starts it automatically).',
verdict: 'skipped',
cause: 'Not rigged inside this run.',
});
outcome = 'partial';
}
run.add(deliveryStage({ frame: data }));
}
const sc = result?.structuredContent || {};
const glbUrl = failure ? null : sc.glbUrl || sc.glb_url || data?.glb_url || null;
const finished = finishReceipt(receipt, { outcome, glbUrl, viewerUrl: glbUrl ? sc.viewer_url || sc.viewerUrl : undefined });
const sealed = await sealReceipt(finished);
const stored = await saveReceipt(sealed, { jobRef: ref });
return attachReceipt(result, sealed.receipt, stored ? receiptUrl(base, finished.id) : null);
} catch (err) {
console.warn('[run-receipt] completion not attached:', err?.message || err);
return result;
}
}