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.

fix(forge): stop discarding every director brief, and make run receipts name why a brief fell back

nirholas41e8e201ae65
diff --git a/api/_lib/forge-director-prompts.js b/api/_lib/forge-director-prompts.js
index 1844059fa..eb122f017 100644
--- a/api/_lib/forge-director-prompts.js
+++ b/api/_lib/forge-director-prompts.js
@@ -86,6 +86,17 @@ export function meshSubjectClass(prompt) {
return classifySubject(prompt);
}
+// The forge accepts a prompt of at most 1000 characters (api/gpt-forge.js), and
+// the director guard drops anything longer. Unbudgeted, the chain's specs ran
+// 1032 to 1620 characters on 2026-10-11, so every brief was thrown away and the
+// raw idea went to paint instead; the signed run receipts showed it as a
+// "recovered" brief on every run. The budget is stated in words because the
+// chain's models measurably ignore a character count (an "under 600 characters"
+// ask still came back at 1071 to 1421) while holding a word count; 90 words of
+// spec prose run about 600 characters, leaving headroom under the cap.
+export const BRIEF_BUDGET_WORDS = 90;
+const BRIEF_BUDGET_DIRECTIVE = `Keep the whole prompt under ${BRIEF_BUDGET_WORDS} words. `;
+
// Build the MESH_DIRECTOR system prompt for a given subject class — one
// isolated subject, its construction, per-part PBR materials, one held art
// style, subject-specific realism cues, and fine surface detail, ending in
@@ -111,7 +122,9 @@ export function meshDirectorFor(subject = 'object') {
'Always end with these composition constraints so the ' +
'reference image reconstructs cleanly: full subject in frame, centered, isolated on a plain neutral ' +
'background, one camera angle, even studio lighting, no cropping, no motion blur, no text or watermark, no ' +
- 'collage or multi-view grid, no second subject. Output ONLY the rewritten prompt as a single line — no ' +
+ 'collage or multi-view grid, no second subject. ' +
+ BRIEF_BUDGET_DIRECTIVE +
+ 'Output ONLY the rewritten prompt as a single line: no ' +
'preamble, no quotes.'
);
}
@@ -178,6 +191,7 @@ export function avatarDirectorFor(subject = 'person') {
'constraints: full body in frame head-to-toe, centered, isolated on a plain neutral background, no props ' +
'gripped or crossing the silhouette, one camera angle facing the character, even studio lighting, no ' +
'cropping, no motion blur, no text or watermark, no collage or multi-view grid, no second character. ' +
+ BRIEF_BUDGET_DIRECTIVE +
'Output ONLY the rewritten prompt as a single line — no preamble, no quotes.'
);
}
diff --git a/api/_lib/run-receipt.js b/api/_lib/run-receipt.js
index a60120f40..7ed26e3a7 100644
--- a/api/_lib/run-receipt.js
+++ b/api/_lib/run-receipt.js
@@ -167,19 +167,25 @@ export function finishReceipt(receipt, { outcome, glbUrl, viewerUrl, now = Date.
finished_at: final === 'pending' ? null : new Date(now).toISOString(),
duration_ms: final === 'pending' || !Number.isFinite(started) ? null : Math.max(0, now - started),
outcome: final,
- summary: summarize(final, issues),
+ summary: summarize(final, issues, receipt.stages),
issues,
output: glbUrl ? { glb_url: glbUrl, ...(viewerUrl ? { viewer_url: viewerUrl } : {}) } : null,
};
}
-function summarize(outcome, issues) {
+function summarize(outcome, issues, stages = []) {
const missed = issues.filter((i) => i.verdict === 'missed');
const recovered = issues.filter((i) => i.verdict === 'recovered');
+ // A skipped stage is not an issue, but it is not a pass either: "every stage
+ // met" over a stage that never ran is the overclaim receipts exist to stop.
+ const skipped = stages.filter((s) => s.verdict === 'skipped');
const parts = [OUTCOME_LABELS[outcome] || outcome];
if (missed.length) parts.push(`${missed.length} stage${missed.length === 1 ? '' : 's'} missed (${missed.map((i) => i.label).join(', ')})`);
if (recovered.length) parts.push(`${recovered.length} carried by a fallback (${recovered.map((i) => i.label).join(', ')})`);
- if (!missed.length && !recovered.length && outcome === 'delivered') parts.push('every stage met its contract');
+ if (!missed.length && !recovered.length && outcome === 'delivered') {
+ parts.push(skipped.length ? 'Every stage that ran met its contract' : 'Every stage met its contract');
+ }
+ if (skipped.length) parts.push(`${skipped.length} skipped (${skipped.map((s) => s.label).join(', ')})`);
return `${parts.join('. ')}.`;
}
@@ -252,7 +258,28 @@ export function subjectGateStage({ hasImage, givenMesh, nonHumanoid, override })
* fixed one as the fallback) or 'mesh' (an optional enrichment; the raw prompt
* is a valid brief on its own).
*/
-export function briefStage({ kind, hasImage, directed, knownMark = false, ms }) {
+// Why the director's brief was not used, in words a reader can check against
+// the stage time. `fallback` is what directPrompt reported via onFallback.
+function directorFallbackCause(fallback) {
+ switch (fallback?.reason) {
+ case 'too_long':
+ return `The director's brief ran to ${fallback.chars ? `${fallback.chars} characters` : 'over 1000 characters'}; the forge accepts at most 1000, so it was set aside.`;
+ case 'unfinished':
+ return 'The director reply stopped mid-sentence, so it was treated as clipped and set aside.';
+ case 'link':
+ return 'The director reply carried a link, which marks a provider notice rather than a brief, so it was set aside.';
+ case 'not_enriched':
+ return 'The director reply added nothing to the prompt, so the original wording was kept.';
+ case 'empty':
+ return 'The director returned an empty reply.';
+ case 'no_reply':
+ return 'No reply from the director models within the time allowed.';
+ default:
+ return 'The director did not return a usable brief.';
+ }
+}
+
+export function briefStage({ kind, hasImage, directed, knownMark = false, fallback = null, ms }) {
if (hasImage) {
return { id: 'brief', label: 'Brief', expected: 'A brief for the reference picture.', observed: 'A reference image was supplied, so it was used directly.', verdict: 'skipped', ms };
}
@@ -266,6 +293,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })
ms,
};
}
+ const cause = directorFallbackCause(fallback);
if (kind === 'avatar') {
const expected = 'A director-written brief that frames the whole figure head to toe in a neutral A-pose.';
return directed
@@ -276,7 +304,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })
expected,
observed: 'The fixed full-body brief was appended to the prompt as written.',
verdict: 'recovered',
- cause: 'The director model did not return a usable brief in time; the fixed brief keeps the framing.',
+ cause: `${cause} The fixed brief keeps the framing.`,
ms,
};
}
@@ -289,7 +317,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })
expected,
observed: 'The prompt was used as written.',
verdict: 'recovered',
- cause: 'The director model did not return a usable brief in time.',
+ cause,
ms,
};
}
diff --git a/api/_mcp-studio/forge-client.js b/api/_mcp-studio/forge-client.js
index 6dafd3231..31d27f222 100644
--- a/api/_mcp-studio/forge-client.js
+++ b/api/_mcp-studio/forge-client.js
@@ -240,41 +240,82 @@ export async function rig(base, glbUrl, { timeoutEnv } = {}) {
const DIRECTOR_MAX_TOKENS = 400;
const DIRECTOR_TIMEOUT_MS = 20_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.
+// Longest brief we forward, and the longest prompt the forge itself accepts
+// (api/gpt-forge.js rejects anything over 1000). The director prompts ask for
+// under 800 (BRIEF_BUDGET_CHARS) so a spec has room to spare.
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 ("A small," and "A classic wooden rocking chair
-// with gracefully curved"), as does any fragment ending on a separator or a
-// dangling connective, with no per-word list to keep current.
+// a finished sentence. A generation that ran out of tokens cannot finish one,
+// which makes the ending the one signal that separates a whole brief from a
+// clipped one without guessing at grammar. Both production truncations fail it
+// ("A small," and "A classic wooden rocking chair with gracefully curved"), as
+// does any fragment ending on a separator or a dangling connective.
const ENDS_COMPLETE = /[.!?]["'\u201d\u2019)\]]*$/;
+// The prompts also mandate the LAST words of the brief: the composition list
+// closing on "no second subject" (mesh) or "no second character" (avatar). The
+// chain copies that list verbatim and often stops without a period, and treating
+// those as clipped threw away every brief on 2026-10-11 (run receipts showed the
+// brief "recovered" on each studio run). A clip lands mid-word or mid-list, never
+// exactly on the mandated last phrase, so that phrase is as whole an ending as a
+// period. "no second" alone is still a clip.
+const ENDS_ON_CLOSING_CONSTRAINT = /(?:\bno second (?:subject|character)s?|\bone (?:subject|character) only)$/i;
+
// 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;
+// own words, and if not, name why: the run receipt states the reason, so a
+// fallback is never filed under a guess. The director is a quality lever that
+// must never cost a caller their intent, so anything named here 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. gpt-forge-client.js re-exports this.
+// Returns null when usable, else 'empty' | 'too_long' | 'unfinished' | 'link' |
+// 'not_enriched'.
+export function directorRewriteProblem(refined, rawPrompt) {
+ if (typeof refined !== 'string') return 'empty';
const text = refined.trim();
- if (text.length < 3 || text.length > DIRECTOR_MAX_CHARS) return false;
- if (!ENDS_COMPLETE.test(text)) return false;
+ if (text.length < 3) return 'empty';
+ if (text.length > DIRECTOR_MAX_CHARS) return 'too_long';
+ if (!ENDS_COMPLETE.test(text) && !ENDS_ON_CLOSING_CONSTRAINT.test(text)) return 'unfinished';
+ // 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 'link';
// 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 far
// 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;
+ if (raw && text.length <= raw.length) return 'not_enriched';
+ return null;
+}
+
+export function isUsableDirectorRewrite(refined, rawPrompt) {
+ return directorRewriteProblem(refined, rawPrompt) === null;
+}
+
+// Shared tail of both clients' directPrompt: clean the model reply, judge it,
+// and tell the caller why it was dropped. `onFallback` receives
+// { reason, chars? } where reason is 'no_reply' or a directorRewriteProblem code.
+export function finishDirectorReply(text, rawPrompt, onFallback) {
+ if (!text) {
+ onFallback?.({ reason: 'no_reply' });
+ 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();
+ const reason = directorRewriteProblem(refined, rawPrompt);
+ if (reason === null) return refined;
+ // Returning null here is the documented fail-soft path: the caller forwards
+ // the caller's original prompt unchanged, which is always a valid brief.
+ onFallback?.(reason === 'too_long' ? { reason, chars: refined.length } : { reason });
+ return null;
}
-export async function directPrompt(instruction, rawPrompt) {
+export async function directPrompt(instruction, rawPrompt, { onFallback } = {}) {
const user = `Idea: ${rawPrompt}`;
let text = null;
@@ -316,18 +357,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/gpt-forge-client.js b/api/_mcp-studio/gpt-forge-client.js
index 879786aaf..9b608a7cf 100644
--- a/api/_mcp-studio/gpt-forge-client.js
+++ b/api/_mcp-studio/gpt-forge-client.js
@@ -18,6 +18,7 @@
import { selfOrigin } from '../_lib/self-origin.js';
import { watsonxConfig, watsonxChatComplete } from '../_lib/watsonx.js';
import { llmComplete } from '../_lib/llm.js';
+import { isUsableDirectorRewrite, finishDirectorReply } from './forge-client.js';
import { TICKET_HEADER, newTicket, ticketHandle } from '../_lib/forge-submit-ticket.js';
const DEFAULT_TIMEOUT_MS = 180_000;
@@ -361,45 +362,11 @@ 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 rewrite guard is shared with forge-client.js so the two clients cannot
+// drift apart again (this copy once had the URL check and the other did not).
+export { isUsableDirectorRewrite };
-// 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;
@@ -446,18 +413,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 c183c513b..48c5fcc2c 100644
--- a/api/_mcp-studio/tools.js
+++ b/api/_mcp-studio/tools.js
@@ -447,9 +447,10 @@ async function handleForgeFree(args, _auth, req, ctx = {}) {
run.add(briefStage({ kind: 'mesh', knownMark: true }));
} else {
const t0 = Date.now();
- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);
+ 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), ms: Date.now() - t0 }));
+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));
}
return finishMesh(run, {
base,
@@ -518,9 +519,10 @@ async function handleTextToAvatar(args, _auth, req, ctx = {}) {
if (prompt && !imageUrl) {
const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';
const t0 = Date.now();
- const directed = await directPrompt(avatarDirectorFor(subject), prompt);
+ 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), ms: Date.now() - t0 }));
+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));
} else {
run.add(briefStage({ kind: 'avatar', hasImage: true }));
}
@@ -556,9 +558,10 @@ async function handleMeshForge(args, _auth, req, ctx = {}) {
run.add(briefStage({ kind: 'mesh', knownMark: true }));
} else {
const t0 = Date.now();
- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);
+ 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), ms: Date.now() - t0 }));
+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));
}
} else {
run.add(briefStage({ kind: 'mesh', hasImage: true }));
@@ -656,9 +659,10 @@ async function handleForgeAvatar(args, _auth, req, ctx = {}) {
if (prompt && !imageUrl) {
const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';
const t0 = Date.now();
- const directed = await directPrompt(avatarDirectorFor(subject), prompt);
+ 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), ms: Date.now() - t0 }));
+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));
} else {
run.add(briefStage({ kind: 'avatar', hasImage: true }));
}
diff --git a/data/changelog.json b/data/changelog.json
index e8920eff6..7dd9b8d6d 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-11",
+ "title": "The prompt director works again, found by its own run receipts",
+ "link": "/runs",
+ "summary": "The first receipts showed the director's brief falling back on every Studio run. The replies were arriving in 5 to 10 seconds but ran past the 1000-character prompt cap or ended on the closing constraint the director is told to end on, and both were discarded as clipped. The director now writes to a word budget the models actually follow, the guard accepts the mandated ending, both forge clients share one guard, and a receipt now names the exact reason a brief fell back (too long with its length, unfinished, no reply) instead of a generic timeout. Receipts also stop saying every stage met when a stage was skipped.",
+ "tags": [
+ "fix"
+ ]
+ },
{
"date": "2026-10-11",
"title": "Every 3D generation now writes a signed run receipt",
diff --git a/tests/api/forge-director.test.js b/tests/api/forge-director.test.js
index c386b6502..db82e2e30 100644
--- a/tests/api/forge-director.test.js
+++ b/tests/api/forge-director.test.js
@@ -123,4 +123,38 @@ describe('directPrompt — in-process Granite director', () => {
state.watsonx.mockResolvedValue({ text: 'A red car.' });
expect(await directPrompt(MESH_DIRECTOR, 'a red sports car with chrome trim')).toBeNull();
});
+
+ // The run receipt reports why a brief fell back, so directPrompt tells the
+ // caller which failure it hit rather than collapsing them all into null.
+ it('reports the fallback reason so the receipt can state it exactly', async () => {
+ const seen = [];
+ const onFallback = (f) => seen.push(f);
+
+ state.watsonx.mockResolvedValue({ text: `${'A brass lantern with a glass chimney, '.repeat(30)}centered.` });
+ expect(await directPrompt(MESH_DIRECTOR, 'lantern', { onFallback })).toBeNull();
+ expect(seen.at(-1)).toMatchObject({ reason: 'too_long' });
+ expect(seen.at(-1).chars).toBeGreaterThan(1000);
+
+ state.watsonx.mockResolvedValue({ text: 'A classic wooden rocking chair with gracefully curved' });
+ await directPrompt(MESH_DIRECTOR, 'rocking chair', { onFallback });
+ expect(seen.at(-1)).toMatchObject({ reason: 'unfinished' });
+
+ state.watsonx.mockRejectedValue(new Error('down'));
+ state.chain.mockRejectedValue(new Error('all rungs dead'));
+ await directPrompt(MESH_DIRECTOR, 'anything', { onFallback });
+ expect(seen.at(-1)).toMatchObject({ reason: 'no_reply' });
+
+ state.watsonx.mockResolvedValue({ text: 'A worn oak chair with turned legs, centered.' });
+ const before = seen.length;
+ expect(await directPrompt(MESH_DIRECTOR, 'chair', { onFallback })).toBe('A worn oak chair with turned legs, centered.');
+ expect(seen.length).toBe(before);
+ });
+
+ it('reports the same reasons from the client the studio tools use', async () => {
+ const { directPrompt: studioDirect } = await import('../../api/_mcp-studio/gpt-forge-client.js');
+ const seen = [];
+ state.watsonx.mockResolvedValue({ text: `${'A brass lantern with a glass chimney, '.repeat(30)}centered.` });
+ expect(await studioDirect(MESH_DIRECTOR, 'lantern', { onFallback: (f) => seen.push(f) })).toBeNull();
+ expect(seen[0]).toMatchObject({ reason: 'too_long' });
+ });
});
diff --git a/tests/forge-director-rewrite.test.js b/tests/forge-director-rewrite.test.js
index a8d60d851..6f41ed3cb 100644
--- a/tests/forge-director-rewrite.test.js
+++ b/tests/forge-director-rewrite.test.js
@@ -8,7 +8,9 @@
// the director's stated contract: it may improve a generation, never break one.
import { describe, expect, it } from 'vitest';
-import { isUsableDirectorRewrite } from '../api/_mcp-studio/forge-client.js';
+import { isUsableDirectorRewrite, directorRewriteProblem } from '../api/_mcp-studio/forge-client.js';
+import { isUsableDirectorRewrite as isUsableFromGptClient } from '../api/_mcp-studio/gpt-forge-client.js';
+import { meshDirectorFor, avatarDirectorFor } from '../api/_lib/forge-director-prompts.js';
const RAW = 'a small ceramic teapot with a bamboo handle';
@@ -71,8 +73,52 @@ describe('isUsableDirectorRewrite', () => {
expect(isUsableDirectorRewrite(undefined, RAW)).toBe(false);
});
+ // Run receipts showed the brief falling back on every studio run on 2026-10-11.
+ // The director prompts tell the model to END on the composition list ("... no
+ // collage or multi-view grid, no second subject"), and real outputs from the
+ // chain copy that list verbatim with no closing period, so the period-only
+ // completeness test rejected every well-formed brief it was asked to produce.
+ it('accepts a brief that ends on the mandated closing constraint without a period', () => {
+ const spec = COMPLETE_SPEC.replace(/, no text or watermark\.$/, ', no text or watermark, no collage or multi-view grid, no second subject');
+ expect(isUsableDirectorRewrite(spec, RAW)).toBe(true);
+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'no second character'), RAW)).toBe(true);
+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'one character only'), RAW)).toBe(true);
+ // A clip inside that same closing list is still a clip.
+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'no second'), RAW)).toBe(false);
+ });
+
+ it('asks the director for a brief the forge will accept (it rejects prompts over 1000 characters)', () => {
+ for (const ins of [meshDirectorFor('object'), avatarDirectorFor('person')]) {
+ // Words, not characters: the chain's models ignore a character count.
+ const m = /under (\d+) words/.exec(ins);
+ expect(m, 'the director prompt states a length budget').not.toBeNull();
+ // About 7 characters per word of spec prose; stay well under 1000.
+ expect(Number(m[1]) * 7).toBeLessThan(1000);
+ }
+ });
+
+ it('is one implementation shared by both forge clients', () => {
+ expect(isUsableFromGptClient).toBe(isUsableDirectorRewrite);
+ });
+
it('still accepts an enriched spec when the caller brief is absent', () => {
expect(isUsableDirectorRewrite(COMPLETE_SPEC, '')).toBe(true);
expect(isUsableDirectorRewrite(COMPLETE_SPEC, undefined)).toBe(true);
});
});
+
+// The run receipt has to say WHY a brief fell back, so the guard names the
+// problem instead of only answering yes or no. Before this every fallback was
+// filed as "did not return a usable brief in time", which was false for each of
+// the 2026-10-11 runs: the replies arrived in 5 to 10 s and were too long.
+describe('directorRewriteProblem', () => {
+ it('names each way a rewrite can be unusable', () => {
+ expect(directorRewriteProblem(COMPLETE_SPEC, RAW)).toBeNull();
+ expect(directorRewriteProblem(`${'x'.repeat(1000)}.`, RAW)).toBe('too_long');
+ expect(directorRewriteProblem('A small,', RAW)).toBe('unfinished');
+ expect(directorRewriteProblem(`${COMPLETE_SPEC.slice(0, -1)} at https://example.com.`, RAW)).toBe('link');
+ expect(directorRewriteProblem('A red car.', 'a red sports car with chrome trim')).toBe('not_enriched');
+ expect(directorRewriteProblem('', RAW)).toBe('empty');
+ expect(directorRewriteProblem(null, RAW)).toBe('empty');
+ });
+});
diff --git a/tests/run-receipt.test.js b/tests/run-receipt.test.js
index 59069b19c..2ccf3aee3 100644
--- a/tests/run-receipt.test.js
+++ b/tests/run-receipt.test.js
@@ -98,10 +98,25 @@ describe('run receipt core', () => {
expect(done.outcome).toBe('delivered');
expect(done.issues).toEqual([]);
expect(done.duration_ms).toBe(3000);
- expect(done.summary).toMatch(/every stage met its contract/);
+ expect(done.summary).toBe('Delivered as expected. Every stage met its contract.');
expect(done.stages.find((s) => s.id === 'mesh').observed).toMatch(/high-detail tier on Hunyuan3D/);
});
+ // A skipped stage is not an issue, but it is not a pass either. The 2026-10-11
+ // rig_mesh proof run on a lantern read "every stage met its contract" while the
+ // humanoid check had never run, which is exactly the overclaim receipts exist
+ // to prevent.
+ it('never says every stage met when a stage was not checked', () => {
+ const r = startReceipt({ tool: 'rig_mesh', prompt: null, now: 1000 });
+ addStage(r, inputStage({ allowed: true, hasImage: false, hasPrompt: true }));
+ addStage(r, subjectGateStage({ givenMesh: true }));
+ addStage(r, deliveryStage({ frame: { glb_url: 'https://x/a.glb', durable: true } }));
+ const done = finishReceipt(r, { glbUrl: 'https://x/a.glb', now: 2000 });
+ expect(done.outcome).toBe('delivered');
+ expect(done.summary).not.toMatch(/every stage met/i);
+ expect(done.summary).toBe('Delivered as expected. Every stage that ran met its contract. 1 skipped (Subject check).');
+ });
+
it('names a quiet tier downgrade as recovered, with the cause', () => {
const s = meshStage({ frame: { glb_url: 'https://x/a.glb', tier: 'standard', backend: 'trellis_selfhost' }, expectedTier: 'high', labelFor: engineLabel });
expect(s.verdict).toBe('recovered');
@@ -118,6 +133,17 @@ describe('run receipt core', () => {
expect(briefStage({ kind: 'mesh', knownMark: true }).verdict).toBe('met');
});
+ it('states exactly why the director brief fell back, never a generic timeout', () => {
+ const long = briefStage({ kind: 'mesh', directed: false, fallback: { reason: 'too_long', chars: 1245 } });
+ expect(long.verdict).toBe('recovered');
+ expect(long.cause).toMatch(/1245 characters/);
+ expect(long.cause).toMatch(/1000/);
+ expect(long.cause).not.toMatch(/in time/);
+ expect(briefStage({ kind: 'mesh', directed: false, fallback: { reason: 'unfinished' } }).cause).toMatch(/mid-sentence|unfinished/);
+ expect(briefStage({ kind: 'avatar', directed: false, fallback: { reason: 'no_reply' } }).cause).toMatch(/no reply/i);
+ expect(briefStage({ kind: 'avatar', directed: false, fallback: { reason: 'too_long', chars: 1100 } }).cause).toMatch(/fixed brief/);
+ });
+
it('turns away a non-humanoid avatar before spending GPU time, and says so', () => {
const s = subjectGateStage({ nonHumanoid: true });
expect(s.verdict).toBe('missed');