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
feat(mcp-studio): wire signed run receipts into the five forge job-starting tools
nirholasd80e9d01c527
diff --git a/api/_mcp-studio/gpt-forge-client.js b/api/_mcp-studio/gpt-forge-client.jsindex 8326da519..d1e722ebe 100644--- a/api/_mcp-studio/gpt-forge-client.js+++ b/api/_mcp-studio/gpt-forge-client.js@@ -19,6 +19,11 @@ import { selfOrigin } from '../_lib/self-origin.js';import { watsonxConfig, watsonxChatComplete } from '../_lib/watsonx.js';import { llmComplete } from '../_lib/llm.js';import { TICKET_HEADER, newTicket, ticketHandle } from '../_lib/forge-submit-ticket.js';+// The rewrite guard and fallback-reason tail are shared with forge-client.js so+// the two clients cannot drift apart again (this copy once had its own,+// reason-less duplicate of isUsableDirectorRewrite).+import { isUsableDirectorRewrite, finishDirectorReply } from './forge-client.js';+export { isUsableDirectorRewrite };const DEFAULT_TIMEOUT_MS = 180_000;const DEFAULT_POLL_MS = 3_000;@@ -367,45 +372,7 @@ const DIRECTOR_MAX_TOKENS = 400;const DIRECTOR_TIMEOUT_MS = 15_000;const DIRECTOR_WATSONX_SHARE_MS = 6_000;-// Longest brief we forward. The director's own specs land near 800 characters;-// beyond this the model has stopped writing a prompt and started writing prose.-const DIRECTOR_MAX_CHARS = 1000;--// The director's system prompts ask for a complete spec, and a complete spec is-// a finished sentence: every well-formed one observed in production closes on a-// period after its negatives clause ("...no second subject."). A generation that-// ran out of tokens cannot, which makes terminal punctuation the one signal that-// separates a whole brief from a clipped one without guessing at grammar. Both-// production truncations fail it, as does any fragment ending on a separator or-// a dangling connective, with no per-word list to keep current.-const ENDS_COMPLETE = /[.!?]["'\u201d\u2019)\]]*$/;--// Decide whether a director rewrite is safe to forward in place of the user's-// own words. The director is a quality lever that must never cost a caller their-// intent, so anything that fails this check 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.-export function isUsableDirectorRewrite(refined, rawPrompt) {- if (typeof refined !== 'string') return false;- const text = refined.trim();- if (text.length < 3 || text.length > DIRECTOR_MAX_CHARS) return false;- if (!ENDS_COMPLETE.test(text)) return false;- // 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 false;- // 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 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 false;- return true;-}--export async function directPrompt(instruction, rawPrompt) {+export async function directPrompt(instruction, rawPrompt, { onFallback } = {}) {const user = `Idea: ${rawPrompt}`;let text = null;@@ -452,18 +419,11 @@ export async function directPrompt(instruction, rawPrompt) {});text = result?.text || null;} catch {- return null;+ text = null;}}- if (!text) 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();- // Returning null here is the documented fail-soft path: the caller forwards- // the caller's original prompt unchanged, which is always a valid brief.- return isUsableDirectorRewrite(refined, rawPrompt) ? refined : null;+ return finishDirectorReply(text, rawPrompt, onFallback);}function sleep(ms) {diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.jsindex 20dd82d7f..7328c5833 100644--- a/api/_mcp-studio/tools.js+++ b/api/_mcp-studio/tools.js@@ -56,6 +56,22 @@ import { IDEMPOTENCY_KEY_PROP, jobFields, withIdempotency } from './jobs.js';import { newTicket } from '../_lib/forge-submit-ticket.js';import { renderTurntable, describeGeometry, fetchGeometryStats } from '../_lib/3d-vision.js';import { buildSpatialArtifact } from '../_lib/spatial-mcp.js';+// Signed, per-stage run receipts: what each stage was expected to do, what it+// actually did, and the verdict (api/_lib/run-receipt.js, docs/run-receipts.md).+// openRun/closeRun bracket a job-starting handler; completeRun finishes a+// receipt a check_job/get_job collection completes.+import {+ openRun,+ closeRun,+ completeRun,+ inputStage,+ inputRejected,+ subjectGateStage,+ briefStage,+ rigStage,+ deliveryStage,+ inspectRiggedGlb,+} from './receipts.js';// The same pure cold-start core the browser surfaces render from// (src/shared/forge-frames.js). Zero DOM, zero env, zero network, so it is safe// server-side, and sharing it is what keeps the MCP wording from drifting away@@ -425,12 +441,68 @@ function jobOpts(ctx, shape, { ticket = ctx.ticket } = {}) {};}+// The shared tail of every single-stage generator: submit the mesh, record on+// the run receipt what came back, and close the receipt on whichever of the+// four endings occurred (submit error, pending job, inline-wait timeout,+// delivered model). `jobOptsArgs` is this call's jobOpts(ctx, shape) (the+// idempotency-key ticket/onJob/onProgress wiring), kept separate so the pending+// branch can reuse the same shape it was submitted with.+async function finishMesh(run, { base, ctx, submit, jobOptsArgs, timeoutEnv = 'STUDIO_FORGE_TIMEOUT_MS', what, prompt, kind, rigged = false }) {+ const t0 = Date.now();+ let job;+ try {+ job = await generate(base, submit, { timeoutEnv, deadline: ctx.deadline, ...jobOptsArgs });+ } catch (err) {+ run.mesh(null, { error: failureMessage(err), ms: Date.now() - t0 });+ return closeRun(run, toolError(failureMessage(err)), { base });+ }+ const ms = Date.now() - t0;+ if (job._timedOut && job.job_id) {+ run.mesh(job, { timedOut: true, ms });+ return closeRun(run, pendingResult({ base, jobId: job.job_id, what, prompt, ...pendingTiming(job), jobTool: ctx.jobTool }), { base, jobId: job.job_id });+ }+ if (job._timedOut || !job.glb_url) {+ run.mesh(null, { error: 'The inline wait ended before the job returned a handle to collect it with.', ms });+ return closeRun(run, toolError('Generation is taking longer than expected. Please try again.'), { base });+ }+ run.mesh(job, { ms });+ run.add(deliveryStage({ frame: job }));+ return closeRun(run, ok({ glbUrl: job.glb_url, base, kind, prompt, rigged, referenceImageUrl: job.preview_image_url }), { base });+}++// The shared tail of rigging: submit the rig job, read the delivered file back+// and verify the skeleton with Rig Doctor's analysis (not the rigger's own+// say-so), and close the receipt. `partial` builds the envelope for a rig+// failure when there is a mesh worth handing back anyway (forge_avatar).+async function finishRig(run, { base, ctx, meshUrl, jobOptsArgs, what = 'rigged model', prompt, done, partial }) {+ const t0 = Date.now();+ let job;+ try {+ job = await rig(base, meshUrl, { timeoutEnv: 'STUDIO_RIG_TIMEOUT_MS', deadline: ctx.deadline, ...jobOptsArgs });+ } catch (err) {+ run.add(rigStage({ error: failureMessage(err), ms: Date.now() - t0 }));+ if (partial) return closeRun(run, partial(err), { base, outcome: 'partial' });+ return closeRun(run, toolError(failureMessage(err)), { base });+ }+ if (job._timedOut && job.job_id) {+ run.add(rigStage({ timedOut: true, ms: Date.now() - t0 }));+ return closeRun(run, pendingResult({ base, jobId: job.job_id, what, prompt, ...pendingTiming(job), stage: 'rig', jobTool: ctx.jobTool }), { base, jobId: job.job_id });+ }+ if (job._timedOut || !job.glb_url) {+ run.add(rigStage({ error: 'The inline wait ended before the rig job returned a handle to collect it with.', ms: Date.now() - t0 }));+ return closeRun(run, toolError('Rigging is taking longer than expected. Please try again.'), { base });+ }+ const rigMs = Date.now() - t0;+ const inspected = await inspectRiggedGlb(job.glb_url);+ run.add(rigStage({ report: inspected.report, inspectError: inspected.error, ms: rigMs }));+ run.add(deliveryStage({ frame: job }));+ return closeRun(run, done(job), { base });+}+async function handleForgeFree(args, _auth, req, ctx = {}) {const base = originFromReq(req);const prompt = String(args.prompt || '').trim();if (prompt.length < 3) return toolError('Provide a text prompt of at least 3 characters.');- const safety = checkPromptSafety(prompt);- if (!safety.allowed) return toolError(safety.message);// Standard by default, and every doc describing this tool says exactly that.// The high tier is a real, working option, not a stub: it runs on our own// async Hunyuan3D worker (GCP_HUNYUAN3D_URL) behind a genuine poll handle,@@ -444,6 +516,10 @@ async function handleForgeFree(args, _auth, req, ctx = {}) {// standard on a 402 or submit timeout, and a job that outlives// STUDIO_FORGE_TIMEOUT_MS comes back as a pollable handle, never an error.const tier = VALID_TIER.has(args.tier) ? args.tier : 'standard';+ const run = openRun('forge_free', { prompt, tier });+ const safety = checkPromptSafety(prompt);+ run.add(inputStage({ allowed: safety.allowed, message: safety.message, hasPrompt: true }));+ if (!safety.allowed) return closeRun(run, toolError(safety.message), { base, outcome: 'refused', redactPrompt: true });// Known brand marks resolve deterministically; everything else runs the// subject-classified Granite director (fail-soft: original prompt on any// failure) so this free lane gets the same photoreal-reference treatment as@@ -454,25 +530,25 @@ async function handleForgeFree(args, _auth, req, ctx = {}) {if (knownMark) {effective = knownMark.prompt;if (knownMark.imagePath) markImageUrls = [`${base}${knownMark.imagePath}`];+ run.add(briefStage({ kind: 'mesh', knownMark: true }));} else {- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);+ const t0 = Date.now();+ let fallback = null;+ const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt, { onFallback: (f) => (fallback = f) });if (directed) effective = directed;+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));}- let job;- try {- job = await generate(- base,- markImageUrls- ? { prompt: effective, imageUrls: markImageUrls, tier, internal: true, director: false }- : { prompt: effective, path: 'image', tier, internal: true, director: false },- { timeoutEnv: 'STUDIO_FORGE_TIMEOUT_MS', deadline: ctx.deadline, ...jobOpts(ctx, { kind: 'model', what: 'model', prompt }) },- );- } catch (err) {- return toolError(failureMessage(err));- }- if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'model', prompt, ...pendingTiming(job), jobTool: ctx.jobTool });- if (job._timedOut || !job.glb_url) return toolError('Generation is taking longer than expected. Please try again.');- return ok({ glbUrl: job.glb_url, base, kind: 'model', prompt, referenceImageUrl: job.preview_image_url });+ return finishMesh(run, {+ base,+ ctx,+ submit: markImageUrls+ ? { prompt: effective, imageUrls: markImageUrls, tier, internal: true, director: false }+ : { prompt: effective, path: 'image', tier, internal: true, director: false },+ jobOptsArgs: jobOpts(ctx, { kind: 'model', what: 'model', prompt }),+ what: 'model',+ prompt,+ kind: 'model',+ });}async function handleTextToAvatar(args, _auth, req, ctx = {}) {@@ -480,14 +556,16 @@ async function handleTextToAvatar(args, _auth, req, ctx = {}) {const prompt = String(args.prompt || '').trim();const imageUrl = args.image_url ? String(args.image_url).trim() : '';if (!prompt && !imageUrl) return toolError('Provide a text prompt or a reference image_url.');- if (prompt) {- const safety = checkPromptSafety(prompt);- if (!safety.allowed) return toolError(safety.message);- }+ const run = openRun('text_to_avatar', { prompt, hasImage: Boolean(imageUrl), tier: AVATAR_TIER });+ const safety = prompt ? checkPromptSafety(prompt) : { allowed: true };+ run.add(inputStage({ allowed: safety.allowed, message: safety.message, hasPrompt: Boolean(prompt), hasImage: Boolean(imageUrl) }));+ if (!safety.allowed) return closeRun(run, toolError(safety.message), { base, outcome: 'refused', redactPrompt: true });try {await guardImage(imageUrl);} catch (err) {- return toolError(err.userMessage ? err.message : 'That image URL could not be used.');+ const message = err.userMessage ? err.message : 'That image URL could not be used.';+ run.add(inputRejected({ expected: 'A public image URL the generator can fetch.', message }));+ return closeRun(run, toolError(message), { base, outcome: 'refused' });}// Granite avatar director (text mode only, fail-soft): without this the raw// words reconstructed straight into TRELLIS/Hunyuan3D with no photoreal@@ -495,22 +573,23 @@ async function handleTextToAvatar(args, _auth, req, ctx = {}) {let effective = prompt;if (prompt && !imageUrl) {const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';- const directed = await directPrompt(avatarDirectorFor(subject), prompt);+ const t0 = Date.now();+ let fallback = null;+ const directed = await directPrompt(avatarDirectorFor(subject), prompt, { onFallback: (f) => (fallback = f) });effective = directed || avatarFallbackBrief(prompt, subject);+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));+ } else {+ run.add(briefStage({ kind: 'avatar', hasImage: true }));}- let job;- try {- job = await generate(- base,- { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: AVATAR_TIER, internal: true, director: false },- { timeoutEnv: 'STUDIO_FORGE_TIMEOUT_MS', deadline: ctx.deadline, ...jobOpts(ctx, { kind: 'avatar', what: 'avatar', prompt: prompt || undefined }) },- );- } catch (err) {- return toolError(failureMessage(err));- }- if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'avatar', prompt: prompt || undefined, ...pendingTiming(job), jobTool: ctx.jobTool });- if (job._timedOut || !job.glb_url) return toolError('Generation is taking longer than expected. Please try again.');- return ok({ glbUrl: job.glb_url, base, kind: 'avatar', prompt: prompt || undefined, referenceImageUrl: job.preview_image_url });+ return finishMesh(run, {+ base,+ ctx,+ submit: { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: AVATAR_TIER, internal: true, director: false },+ jobOptsArgs: jobOpts(ctx, { kind: 'avatar', what: 'avatar', prompt: prompt || undefined }),+ what: 'avatar',+ prompt: prompt || undefined,+ kind: 'avatar',+ });}async function handleMeshForge(args, _auth, req, ctx = {}) {@@ -518,14 +597,16 @@ async function handleMeshForge(args, _auth, req, ctx = {}) {const prompt = String(args.prompt || '').trim();const imageUrl = args.image_url ? String(args.image_url).trim() : '';if (!prompt && !imageUrl) return toolError('Provide a text prompt or a reference image_url.');- if (prompt) {- const safety = checkPromptSafety(prompt);- if (!safety.allowed) return toolError(safety.message);- }+ const run = openRun('mesh_forge', { prompt, hasImage: Boolean(imageUrl), tier: 'standard' });+ const safety = prompt ? checkPromptSafety(prompt) : { allowed: true };+ run.add(inputStage({ allowed: safety.allowed, message: safety.message, hasPrompt: Boolean(prompt), hasImage: Boolean(imageUrl) }));+ if (!safety.allowed) return closeRun(run, toolError(safety.message), { base, outcome: 'refused', redactPrompt: true });try {await guardImage(imageUrl);} catch (err) {- return toolError(err.userMessage ? err.message : 'That image URL could not be used.');+ const message = err.userMessage ? err.message : 'That image URL could not be used.';+ run.add(inputRejected({ expected: 'A public image URL the generator can fetch.', message }));+ return closeRun(run, toolError(message), { base, outcome: 'refused' });}// Known brand marks resolve deterministically (no LLM knows a niche mark's// geometry; the lexicon spec is already tight, so a rewrite could only hurt)@@ -539,55 +620,56 @@ async function handleMeshForge(args, _auth, req, ctx = {}) {if (knownMark) {effective = knownMark.prompt;if (knownMark.imagePath) markImageUrls = [`${base}${knownMark.imagePath}`];+ run.add(briefStage({ kind: 'mesh', knownMark: true }));} else {- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);+ const t0 = Date.now();+ let fallback = null;+ const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt, { onFallback: (f) => (fallback = f) });if (directed) effective = directed;+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));}+ } else {+ run.add(briefStage({ kind: 'mesh', hasImage: true }));}- let job;- try {- job = await generate(- base,- {- prompt: effective || undefined,- imageUrls: imageUrl ? [imageUrl] : markImageUrls,- aspect: '1:1',- tier: 'standard',- internal: true,- director: false,- },- { timeoutEnv: 'STUDIO_FORGE_TIMEOUT_MS', deadline: ctx.deadline, ...jobOpts(ctx, { kind: 'mesh', what: 'mesh', prompt: prompt || undefined }) },- );- } catch (err) {- return toolError(failureMessage(err));- }- if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'mesh', prompt: prompt || undefined, ...pendingTiming(job), jobTool: ctx.jobTool });- if (job._timedOut || !job.glb_url) return toolError('Generation is taking longer than expected. Please try again.');- return ok({ glbUrl: job.glb_url, base, kind: 'mesh', prompt: prompt || undefined, referenceImageUrl: job.preview_image_url });+ return finishMesh(run, {+ base,+ ctx,+ submit: {+ prompt: effective || undefined,+ imageUrls: imageUrl ? [imageUrl] : markImageUrls,+ aspect: '1:1',+ tier: 'standard',+ internal: true,+ director: false,+ },+ jobOptsArgs: jobOpts(ctx, { kind: 'mesh', what: 'mesh', prompt: prompt || undefined }),+ what: 'mesh',+ prompt: prompt || undefined,+ kind: 'mesh',+ });}async function handleRigMesh(args, _auth, req, ctx = {}) {const base = originFromReq(req);const glbUrl = String(args.glb_url || '').trim();if (!/^https?:\/\//i.test(glbUrl)) return toolError('Provide an http(s) URL to a GLB mesh to rig.');+ const run = openRun('rig_mesh', { rig: true });try {await guardImage(glbUrl);} catch (err) {- return toolError(err.userMessage ? err.message : 'That GLB URL could not be used.');+ const message = err.userMessage ? err.message : 'That GLB URL could not be used.';+ run.add(inputRejected({ expected: 'A public GLB URL the rigger can fetch.', message }));+ return closeRun(run, toolError(message), { base, outcome: 'refused' });}- let job;- try {- job = await rig(base, glbUrl, {- timeoutEnv: 'STUDIO_RIG_TIMEOUT_MS',- deadline: ctx.deadline,- ...jobOpts(ctx, { kind: 'rigged model', what: 'rigged model', rigged: true, stage: 'rig' }),- });- } catch (err) {- return toolError(failureMessage(err));- }- if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'rigged model', ...pendingTiming(job), stage: 'rig', jobTool: ctx.jobTool });- if (job._timedOut || !job.glb_url) return toolError('Rigging is taking longer than expected. Please try again.');- return ok({ glbUrl: job.glb_url, base, kind: 'rigged model', rigged: true });+ run.add({ id: 'input', label: 'Input', expected: 'A public GLB URL the rigger can fetch.', observed: 'Received a public GLB URL.', verdict: 'met' });+ run.add(subjectGateStage({ givenMesh: true }));+ return finishRig(run, {+ base,+ ctx,+ meshUrl: glbUrl,+ jobOptsArgs: jobOpts(ctx, { kind: 'rigged model', what: 'rigged model', rigged: true, stage: 'rig' }),+ done: (job) => ok({ glbUrl: job.glb_url, base, kind: 'rigged model', rigged: true }),+ });}async function handleForgeAvatar(args, _auth, req, ctx = {}) {@@ -595,27 +677,41 @@ async function handleForgeAvatar(args, _auth, req, ctx = {}) {const prompt = String(args.prompt || '').trim();const imageUrl = args.image_url ? String(args.image_url).trim() : '';if (!prompt && !imageUrl) return toolError('Provide a text prompt or a reference image_url.');- if (prompt) {- const safety = checkPromptSafety(prompt);- if (!safety.allowed) return toolError(safety.message);- }- if (prompt && !imageUrl && args.allow_non_humanoid !== true && looksNonHumanoid(prompt)) {- return toolError(- 'That looks like an object rather than a character. Auto-rigging needs a humanoid figure. Use the 3D mesh generator for objects, or set allow_non_humanoid to override.',+ const run = openRun('forge_avatar', { prompt, hasImage: Boolean(imageUrl), tier: AVATAR_TIER, rig: true });+ const safety = prompt ? checkPromptSafety(prompt) : { allowed: true };+ run.add(inputStage({ allowed: safety.allowed, message: safety.message, hasPrompt: Boolean(prompt), hasImage: Boolean(imageUrl) }));+ if (!safety.allowed) return closeRun(run, toolError(safety.message), { base, outcome: 'refused', redactPrompt: true });+ const nonHumanoid = Boolean(prompt && !imageUrl && looksNonHumanoid(prompt));+ run.add(subjectGateStage({ hasImage: Boolean(imageUrl), nonHumanoid, override: args.allow_non_humanoid === true }));+ if (nonHumanoid && args.allow_non_humanoid !== true) {+ return closeRun(+ run,+ toolError(+ 'That looks like an object rather than a character. Auto-rigging needs a humanoid figure. Use the 3D mesh generator for objects, or set allow_non_humanoid to override.',+ ),+ { base, outcome: 'refused' },);}try {await guardImage(imageUrl);} catch (err) {- return toolError(err.userMessage ? err.message : 'That image URL could not be used.');+ const message = err.userMessage ? err.message : 'That image URL could not be used.';+ run.add(inputRejected({ expected: 'A public image URL the generator can fetch.', message }));+ return closeRun(run, toolError(message), { base, outcome: 'refused' });}- // Stage 1 — generate the mesh (Granite director in text mode, fail-soft).+ // Stage 1: generate the mesh (Granite director in text mode, fail-soft).let effective = prompt;if (prompt && !imageUrl) {const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';- const directed = await directPrompt(avatarDirectorFor(subject), prompt);+ const t0 = Date.now();+ let fallback = null;+ const directed = await directPrompt(avatarDirectorFor(subject), prompt, { onFallback: (f) => (fallback = f) });effective = directed || avatarFallbackBrief(prompt, subject);+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));+ } else {+ run.add(briefStage({ kind: 'avatar', hasImage: true }));}+ const t0 = Date.now();let gen;try {gen = await generate(@@ -628,26 +724,38 @@ async function handleForgeAvatar(args, _auth, req, ctx = {}) {},);} catch (err) {- return toolError(failureMessage(err));+ run.mesh(null, { error: failureMessage(err), ms: Date.now() - t0 });+ return closeRun(run, toolError(failureMessage(err)), { base });+ }+ if (gen._timedOut && gen.job_id) {+ run.mesh(gen, { timedOut: true, ms: Date.now() - t0 });+ return closeRun(+ run,+ pendingResult({ base, jobId: gen.job_id, what: 'avatar mesh (rig it with rig_mesh once done)', prompt: prompt || undefined, ...pendingTiming(gen), stage: 'mesh', next: 'rig', jobTool: ctx.jobTool }),+ { base, jobId: gen.job_id },+ );}- if (gen._timedOut && gen.job_id) return pendingResult({ base, jobId: gen.job_id, what: 'avatar mesh (rig it with rig_mesh once done)', prompt: prompt || undefined, ...pendingTiming(gen), stage: 'mesh', next: 'rig', jobTool: ctx.jobTool });- if (gen._timedOut || !gen.glb_url) return toolError('Generation is taking longer than expected. Please try again.');+ if (gen._timedOut || !gen.glb_url) {+ run.mesh(null, { error: 'The inline wait ended before the job returned a handle to collect it with.', ms: Date.now() - t0 });+ return closeRun(run, toolError('Generation is taking longer than expected. Please try again.'), { base });+ }+ run.mesh(gen, { ms: Date.now() - t0 });- // Stage 2 — auto-rig the generated mesh.- let rigged;- try {+ // Stage 2: auto-rig the generated mesh, verified from the delivered file.+ return finishRig(run, {+ base,+ ctx,+ meshUrl: gen.glb_url,+ what: 'avatar rig',+ prompt: prompt || undefined,// The rig is a second job, so an idempotent call gives it a ticket of its// own and moves the key's record onto it.- rigged = await rig(base, gen.glb_url, {- timeoutEnv: 'STUDIO_RIG_TIMEOUT_MS',- deadline: ctx.deadline,- ...jobOpts(- ctx,- { kind: 'avatar', what: 'avatar rig', prompt: prompt || undefined, rigged: true, stage: 'rig', next: null },- { ticket: ctx.onJob ? newTicket() : undefined },- ),- });- } catch (err) {+ jobOptsArgs: jobOpts(+ ctx,+ { kind: 'avatar', what: 'avatar rig', prompt: prompt || undefined, rigged: true, stage: 'rig', next: null },+ { ticket: ctx.onJob ? newTicket() : undefined },+ ),+ done: (rigged) => ok({ glbUrl: rigged.glb_url, base, kind: 'avatar', prompt: prompt || undefined, rigged: true, referenceImageUrl: gen.preview_image_url }),// Generation succeeded but rigging failed: hand back the (unrigged) mesh so// the work isn't lost, and say so plainly.// It rides the SAME ok() envelope as every other success, because this@@ -656,22 +764,22 @@ async function handleForgeAvatar(args, _auth, req, ctx = {}) {// sandbox, so this path error-stated instead of showing the mesh it just// saved), the AR launch link, and the Spatial MCP artifact. Only the// narration differs, so a partial result stays as usable as a whole one.- const partial = ok({ glbUrl: gen.glb_url, base, kind: 'mesh', prompt: prompt || undefined, referenceImageUrl: gen.preview_image_url });- return {- ...partial,- content: [- {- type: 'text',- text:- `Generated the mesh but auto-rigging failed (${failureMessage(err)}). The model itself is fine and ready to use.\n` +- partial.content[0].text,- },- ],- };- }- if (rigged._timedOut && rigged.job_id) return pendingResult({ base, jobId: rigged.job_id, what: 'avatar rig', prompt: prompt || undefined, ...pendingTiming(rigged), stage: 'rig', jobTool: ctx.jobTool });- if (rigged._timedOut || !rigged.glb_url) return toolError('Rigging is taking longer than expected. Please try again.');- return ok({ glbUrl: rigged.glb_url, base, kind: 'avatar', prompt: prompt || undefined, rigged: true, referenceImageUrl: gen.preview_image_url });+ partial: (err) => {+ run.add(deliveryStage({ frame: gen }));+ const result = ok({ glbUrl: gen.glb_url, base, kind: 'mesh', prompt: prompt || undefined, referenceImageUrl: gen.preview_image_url });+ return {+ ...result,+ content: [+ {+ type: 'text',+ text:+ `Generated the mesh but auto-rigging failed (${failureMessage(err)}). The model itself is fine and ready to use.\n` ++ result.content[0].text,+ },+ ],+ };+ },+ });}// Rebuild a client-supplied lineage (refine_model's parent_lineage, or the@@ -893,16 +1001,16 @@ export async function collectJob(base, jobId, shape = {}, { jobTool = 'check_jobrigged: Boolean(shape.rigged),referenceImageUrl: data.preview_image_url,});- return doneJob(envelope, jobId, data);+ // The tool call that started this job left its receipt pending (it handed+ // out a job handle instead of waiting); record what the job actually+ // produced and link it, now that a collection resolved it.+ return doneJob(await completeRun(envelope, { base, jobId, data }), jobId, data);}if (data.status === 'failed') {// data.error is already sanitized server-side (sanitizeJobError): safe copy.- return jobFailure({- jobId,- message: data.error ? `Generation failed: ${data.error}` : 'Generation failed for this prompt.',- remedy: START_AGAIN,- reason: 'generation_failed',- });+ const message = data.error ? `Generation failed: ${data.error}` : 'Generation failed for this prompt.';+ const result = jobFailure({ jobId, message, remedy: START_AGAIN, reason: 'generation_failed' });+ return completeRun(result, { base, jobId, data, failure: message });}return pendingResult({base,diff --git a/tests/run-receipt.test.js b/tests/run-receipt.test.jsindex 7b5dbc1f0..ca7ebe463 100644--- a/tests/run-receipt.test.js+++ b/tests/run-receipt.test.js@@ -30,6 +30,14 @@ import { summarizeStats, inspectRiggedGlb, engineLabel, sealReceipt, resetSigninimport { attachReceipt } from '../api/_mcp-studio/receipts.js';import { dispatch } from '../api/_mcp-studio/dispatch.js';+// rig_mesh takes a caller-supplied GLB URL, which tools.js checks with the real+// SSRF guard before anything else; that guard does live DNS resolution, which a+// test has no business depending on. Same shape as tests/3d-vision.test.js.+vi.mock('../api/_lib/ssrf-guard.js', () => ({+ assertSafePublicUrl: async (u) => new URL(u),+ SsrfBlockedError: class extends Error {},+}));+// A real binary glTF: header, JSON chunk, no BIN chunk. analyzeGlb only reads// the JSON, which is exactly what the rig read-back fetches.function buildGlb(json) {@@ -351,16 +359,7 @@ describe('studio wiring', () => {expect(result.content[0].text).toBe('Generated a 3D model.');});- // Skipped: the 2026-10-11 evolve/main reconciliation merge (d77b89178, the- // one order 404 later verified, not order 404's own merge) kept tools.js's- // job-tools.js/collectJob generation-tool architecture (evolve) over the- // finishMesh/finishRig refactor that wires openRun/closeRun into forge_avatar- // (main), since job-tools.js's exported 4-arg collectJob and a second,- // conflicting get_job tool registration made combining both unsafe to guess- // at mid-merge. The receipt core, store and rig-doctor inspection above are- // unaffected and fully wired; only this end-to-end dispatch() attachment is- // not. See prompts/finish/405-wire-run-receipts-into-forge-tools.md.- it.skip('records a full forge_avatar run: fallback brief, tier downgrade, and a rig verified from the file', async () => {+ it('records a full forge_avatar run: fallback brief, tier downgrade, and a rig verified from the file', async () => {const rigged = riggedGlb();globalThis.fetch = vi.fn(async (url, init) => {const u = String(url);@@ -410,9 +409,7 @@ describe('studio wiring', () => {expect(r.result.content[0].text).toMatch(/Run receipt: Delivered as expected/);});- // Skipped for the same reason as the test above: forge_avatar's dispatch- // path does not attach a receipt in this merge's chosen architecture.- it.skip('records a refusal with the prompt redacted', async () => {+ it('records a refusal with the prompt redacted', async () => {globalThis.fetch = vi.fn(async () => ({ ok: false, status: 503, json: async () => ({}) }));const r = await dispatch({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'forge_avatar', arguments: { prompt: 'a wooden chair' } } },@@ -425,4 +422,78 @@ describe('studio wiring', () => {// The forge was never called: the gate fires before any GPU time.expect(globalThis.fetch.mock.calls.some(([u]) => /\/api\/(gpt-)?forge/.test(String(u)))).toBe(false);});++ function mockDoneForge(fields) {+ globalThis.fetch = vi.fn(async (url) => {+ const u = String(url);+ if (/\/api\/(gpt-)?forge/.test(u)) {+ return { ok: true, status: 200, json: async () => ({ status: 'done', durable: true, ...fields }) };+ }+ // The director's LLM chain answers unusably: the fixed brief/raw prompt carries the run.+ return { ok: false, status: 503, json: async () => ({}), text: async () => '' };+ });+ }++ it('records a forge_free run', async () => {+ mockDoneForge({ glb_url: 'https://three.ws/cdn/mesh.glb', job_id: 'F1', tier: 'standard', backend: 'trellis_selfhost' });+ const r = await dispatch(+ { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'forge_free', arguments: { prompt: 'a rustic wooden lantern' } } },+ auth,+ mkReq(),+ );+ expect(r.result.isError).toBeFalsy();+ const receipt = r.result.structuredContent.receipt;+ expect(isReceiptId(receipt.id)).toBe(true);+ expect(receipt.outcome).toBe('delivered');+ expect(r.result.content[0].text).toMatch(/Run receipt: Delivered as expected/);+ });++ it('records a text_to_avatar run', async () => {+ mockDoneForge({ glb_url: 'https://three.ws/cdn/avatar.glb', job_id: 'A1', tier: 'high', backend: 'hunyuan3d' });+ const r = await dispatch(+ { jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'text_to_avatar', arguments: { prompt: 'a cheerful dwarf blacksmith' } } },+ auth,+ mkReq(),+ );+ expect(r.result.isError).toBeFalsy();+ const receipt = r.result.structuredContent.receipt;+ expect(isReceiptId(receipt.id)).toBe(true);+ expect(receipt.outcome).toBe('delivered');+ });++ it('records a mesh_forge run', async () => {+ mockDoneForge({ glb_url: 'https://three.ws/cdn/mesh.glb', job_id: 'M2', tier: 'standard', backend: 'trellis_selfhost' });+ const r = await dispatch(+ { jsonrpc: '2.0', id: 5, method: 'tools/call', params: { name: 'mesh_forge', arguments: { prompt: 'a brass pocket watch' } } },+ auth,+ mkReq(),+ );+ expect(r.result.isError).toBeFalsy();+ const receipt = r.result.structuredContent.receipt;+ expect(isReceiptId(receipt.id)).toBe(true);+ expect(receipt.outcome).toBe('delivered');+ });++ it('records a rig_mesh run, verified from the delivered file', async () => {+ const rigged = riggedGlb();+ globalThis.fetch = vi.fn(async (url) => {+ const u = String(url);+ if (u.endsWith('/rigged.glb')) return glbResponse(rigged);+ if (/\/api\/(gpt-)?forge/.test(u)) {+ return { ok: true, status: 200, json: async () => ({ status: 'done', glb_url: 'https://three.ws/cdn/rigged.glb', job_id: 'R2', durable: true }) };+ }+ return { ok: false, status: 503, json: async () => ({}) };+ });+ const r = await dispatch(+ { jsonrpc: '2.0', id: 6, method: 'tools/call', params: { name: 'rig_mesh', arguments: { glb_url: 'https://three.ws/cdn/unrigged.glb' } } },+ auth,+ mkReq(),+ );+ expect(r.result.isError).toBeFalsy();+ const receipt = r.result.structuredContent.receipt;+ expect(isReceiptId(receipt.id)).toBe(true);+ const byStage = Object.fromEntries(receipt.issues.map((i) => [i.stage, i]));+ expect(byStage.rig).toBeUndefined();+ expect(receipt.outcome).toBe('delivered');+ });});