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.

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.js
index 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.js
index 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_job
rigged: 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.js
index 7b5dbc1f0..ca7ebe463 100644
--- a/tests/run-receipt.test.js
+++ b/tests/run-receipt.test.js
@@ -30,6 +30,14 @@ import { summarizeStats, inspectRiggedGlb, engineLabel, sealReceipt, resetSignin
import { 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');
+ });
});