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
// Tests for directPrompt() in api/_mcp-studio/forge-client.js: the Granite art
// director that rewrites a rough idea into a single-subject 3D spec before it
// drives the FLUX reference image.
//
// The director must run IN PROCESS (watsonx Granite lead, shared free-first
// llmComplete chain as fallback). The original implementation POSTed
// provider=watsonx to its own /api/chat, which the anonymous-provider gate
// rejects with 401, so the director silently never ran and raw two-word
// prompts (the "meme egg" class of bad generations) went straight to the image
// model. These tests pin the in-process contract so that regression cannot
// come back: no fetch to /api/chat, watsonx first, chain fallback, fail-soft
// null, and the same output cleanup as before.
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
const state = vi.hoisted(() => ({
configured: true,
watsonx: vi.fn(),
chain: vi.fn(),
}));
vi.mock('../../api/_lib/watsonx.js', () => ({
watsonxConfig: () => ({ configured: state.configured, chatModel: 'ibm/granite-3-8b-instruct' }),
watsonxChatComplete: (...args) => state.watsonx(...args),
}));
vi.mock('../../api/_lib/llm.js', () => ({
llmComplete: (...args) => state.chain(...args),
}));
import { directPrompt } from '../../api/_mcp-studio/forge-client.js';
import { MESH_DIRECTOR } from '../../api/_lib/forge-director-prompts.js';
const ORIGINAL_FETCH = globalThis.fetch;
beforeEach(() => {
state.configured = true;
state.watsonx.mockReset();
state.chain.mockReset();
});
afterEach(() => {
globalThis.fetch = ORIGINAL_FETCH;
vi.useRealTimers();
});
describe('directPrompt — in-process Granite director', () => {
it('runs watsonx Granite with the instruction as the system message and never touches the network', async () => {
globalThis.fetch = vi.fn(async () => {
throw new Error('the director must not make HTTP calls');
});
state.watsonx.mockResolvedValue({ text: 'A glossy two-tone gel capsule, studio lighting, plain background.' });
const out = await directPrompt(MESH_DIRECTOR, 'a capsule pill');
expect(out).toBe('A glossy two-tone gel capsule, studio lighting, plain background.');
expect(globalThis.fetch).not.toHaveBeenCalled();
expect(state.chain).not.toHaveBeenCalled();
const [, opts] = state.watsonx.mock.calls[0];
expect(opts.messages).toEqual([
{ role: 'system', content: MESH_DIRECTOR },
{ role: 'user', content: 'Idea: a capsule pill' },
]);
});
it('cleans the model output: wrapping quotes stripped, first line only', async () => {
state.watsonx.mockResolvedValue({ text: '"A brushed steel teapot, centered."\nSecond line the model added anyway' });
const out = await directPrompt(MESH_DIRECTOR, 'teapot');
expect(out).toBe('A brushed steel teapot, centered.');
});
it('falls back to the free llmComplete chain when watsonx is not configured', async () => {
state.configured = false;
state.chain.mockResolvedValue({ text: 'A matte ceramic robot figurine, centered.', provider: 'groq', model: 'x' });
const out = await directPrompt(MESH_DIRECTOR, 'robot');
expect(out).toBe('A matte ceramic robot figurine, centered.');
expect(state.watsonx).not.toHaveBeenCalled();
expect(state.chain).toHaveBeenCalledTimes(1);
expect(state.chain.mock.calls[0][0]).toMatchObject({ system: MESH_DIRECTOR, user: 'Idea: robot' });
});
it('falls back to the chain when watsonx throws', async () => {
state.watsonx.mockRejectedValue(new Error('watsonx 429: quota'));
state.chain.mockResolvedValue({ text: 'A worn oak chair, centered.' });
const out = await directPrompt(MESH_DIRECTOR, 'chair');
expect(out).toBe('A worn oak chair, centered.');
});
it('falls back to the chain when watsonx hangs past the director timeout', async () => {
vi.useFakeTimers();
state.watsonx.mockReturnValue(new Promise(() => {}));
state.chain.mockResolvedValue({ text: 'A cast iron lantern, centered.' });
const pending = directPrompt(MESH_DIRECTOR, 'lantern');
await vi.advanceTimersByTimeAsync(20_000);
const out = await pending;
expect(out).toBe('A cast iron lantern, centered.');
});
it('returns null (fail-soft) when every lane fails, so callers keep the raw prompt', async () => {
state.watsonx.mockRejectedValue(new Error('down'));
state.chain.mockRejectedValue(new Error('all rungs dead'));
expect(await directPrompt(MESH_DIRECTOR, 'anything')).toBeNull();
});
it('returns null on a degenerate rewrite instead of forwarding junk', async () => {
state.watsonx.mockResolvedValue({ text: '""' });
expect(await directPrompt(MESH_DIRECTOR, 'anything')).toBeNull();
});
// The truncation guard (isUsableDirectorRewrite) lives between the model call
// and the return, so directPrompt's contract depends on it. Pinning it here
// keeps the two from drifting apart: every fixture above now ends on terminal
// punctuation because a rewrite that does NOT is treated as clipped, and the
// caller keeps their own wording instead.
it('rejects a rewrite that stopped mid-sentence, so the caller keeps their prompt', async () => {
state.watsonx.mockResolvedValue({ text: 'A classic wooden rocking chair with gracefully curved' });
expect(await directPrompt(MESH_DIRECTOR, 'rocking chair')).toBeNull();
});
it('rejects a rewrite no longer than what the caller typed', async () => {
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' });
});
});