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
fix(forge): build a finished job's poll frame once and remember it, so later polls answer in milliseconds
nirholasf54a0033a63a
diff --git a/api/_lib/forge-done-cache.js b/api/_lib/forge-done-cache.jsnew file mode 100644index 000000000..8a0a99259--- /dev/null+++ b/api/_lib/forge-done-cache.js@@ -0,0 +1,39 @@+// Remembers the first finished frame of a forge job so every later poll of a+// done job answers from cache instead of rebuilding it.+//+// Why: the done branch of the poll materializes the creation and runs the+// vision quality gate. Both are worth doing ONCE. Measured live on 2026-08-27,+// every poll of an already-finished job re-ran them and took 13-33 s, which+// pushed the OKX forge_status tool (15 s client bound) into "timed out" on+// roughly every other read of a finished model. A done job is terminal: its+// frame cannot change, so the first one built is the one every poll gets.+//+// Keyed by a hash of the job handle (handles are signed tokens up to 1 KB) and+// held for six hours, which outlives any client's polling loop. The shared+// cache degrades to per-instance memory without Redis, which still dedupes+// the common case of one client polling one instance.++import { createHash } from 'node:crypto';+import { cacheGet, cacheSet } from './cache.js';++export const DONE_FRAME_TTL_S = 6 * 3600;++export function doneFrameKey(jobId) {+ return `forge:done:${createHash('sha256').update(String(jobId)).digest('hex').slice(0, 40)}`;+}++// The frame a done poll answered with, or null when this job has not finished+// on this instance (or its record expired).+export async function recallDoneFrame(jobId) {+ if (!jobId) return null;+ const v = await cacheGet(doneFrameKey(jobId));+ return v && typeof v === 'object' && v.status === 'done' ? v : null;+}++// Store a finished frame. Only a genuinely done frame with a model is worth+// remembering; anything else is a caller bug, not a cache entry.+export async function rememberDoneFrame(jobId, frame) {+ if (!jobId || !frame || frame.status !== 'done' || !frame.glb_url) return false;+ await cacheSet(doneFrameKey(jobId), frame, DONE_FRAME_TTL_S);+ return true;+}diff --git a/api/_mcp-studio/gpt-forge-client.js b/api/_mcp-studio/gpt-forge-client.jsindex a121977ca..b36f63423 100644--- a/api/_mcp-studio/gpt-forge-client.js+++ b/api/_mcp-studio/gpt-forge-client.js@@ -238,9 +238,13 @@ export async function pollJob(base, jobId, { timeoutMs, intervalMs } = {}) {export async function pollOnce(base, jobId) {let res;try {+ // The FIRST poll that finds a job done materializes the creation and runs+ // the quality gate (20-30 s measured); every later poll of that job is+ // served from the done-frame cache in milliseconds. 30 s covers the one+ // slow read without letting a stalled upstream hold a buyer for a minute.res = await fetch(`${base}/api/gpt-forge?job=${encodeURIComponent(jobId)}`, {headers: { accept: 'application/json' },- signal: AbortSignal.timeout(15_000),+ signal: AbortSignal.timeout(30_000),});} catch (err) {if (err?.name === 'TimeoutError' || err?.name === 'AbortError')diff --git a/api/gpt-forge.js b/api/gpt-forge.jsindex 00ca217ca..e80566504 100644--- a/api/gpt-forge.js+++ b/api/gpt-forge.js@@ -127,6 +127,7 @@ import {} from './_lib/credits.js';import { markProviderCooldown, providersInCooldown } from './_lib/provider-health.js';import { acquireLock, releaseLock, cacheGet, cacheSet } from './_lib/cache.js';+import { recallDoneFrame, rememberDoneFrame } from './_lib/forge-done-cache.js';import { sanitizeJobError } from './_lib/provider-job-error.js';import { normalizeForgeOptions, providerReconstructParams, summarizeForgeOptions } from './_lib/forge-options.js';import { bindJobToOptions, optionsForJob } from './_lib/forge-job-options.js';@@ -2743,6 +2744,12 @@ async function pollJob(req, res, jobId) {return pollPipeline(res, token.taskId, jobId);}+ // A finished job is terminal: answer every later poll with the frame the+ // first done poll built, instead of re-materializing and re-scoring it+ // (13-33 s per poll, measured 2026-08-27). See _lib/forge-done-cache.js.+ const remembered = await recallDoneFrame(jobId);+ if (remembered) return json(res, 200, remembered);+// Poll-time failover may have re-dispatched this generation onto another// lane during an earlier poll (see _lib/forge-failover.js). The client keeps// polling the ORIGINAL id; chase the successor chain to the live handle@@ -2904,7 +2911,7 @@ async function pollJob(req, res, jobId) {referenceImageUrl: meta?.preview_image_url || null,});}- return json(res, 200, {+ const doneFrame = {job_id: jobId,creation_id: durable?.id ?? meta?.id ?? null,status: 'done',@@ -2914,7 +2921,9 @@ async function pollJob(req, res, jobId) {quality_gate: qualityGate || undefined,compression: durable?.compression || null,...metaFields,- });+ };+ await rememberDoneFrame(jobId, doneFrame);+ return json(res, 200, doneFrame);}if (result.status === 'failed') {// Persist the RAW provider error for operators, but never relay it: thediff --git a/tests/forge-done-cache.test.js b/tests/forge-done-cache.test.jsnew file mode 100644index 000000000..c25dc06ca--- /dev/null+++ b/tests/forge-done-cache.test.js@@ -0,0 +1,35 @@+/**+ * A finished forge job's poll frame is built once and remembered+ * (api/_lib/forge-done-cache.js). Before this, every poll of a done job+ * re-materialized and re-scored it (13-33 s each, measured 2026-08-27).+ */+import { describe, it, expect } from 'vitest';++delete process.env.UPSTASH_REDIS_REST_URL;+delete process.env.UPSTASH_REDIS_REST_TOKEN;++const { doneFrameKey, recallDoneFrame, rememberDoneFrame } = await import('../api/_lib/forge-done-cache.js');++const LONG_JOB = 'f1.' + 'a'.repeat(900) + '.sig';++describe('forge done-frame cache', () => {+ it('keys by a hash so a 1 KB job token becomes a short stable key', () => {+ expect(doneFrameKey(LONG_JOB)).toMatch(/^forge:done:[0-9a-f]{40}$/);+ expect(doneFrameKey(LONG_JOB)).toBe(doneFrameKey(LONG_JOB));+ expect(doneFrameKey(LONG_JOB)).not.toBe(doneFrameKey(LONG_JOB + 'x'));+ });++ it('remembers a done frame and returns it verbatim on recall', async () => {+ const frame = { job_id: LONG_JOB, status: 'done', glb_url: 'https://cdn.test/a.glb', quality_gate: { score: 85 } };+ expect(await recallDoneFrame(LONG_JOB)).toBeNull();+ expect(await rememberDoneFrame(LONG_JOB, frame)).toBe(true);+ expect(await recallDoneFrame(LONG_JOB)).toEqual(frame);+ });++ it('refuses to remember anything that is not a finished frame with a model', async () => {+ expect(await rememberDoneFrame('f1.pending', { status: 'running' })).toBe(false);+ expect(await rememberDoneFrame('f1.nomodel', { status: 'done' })).toBe(false);+ expect(await rememberDoneFrame('', { status: 'done', glb_url: 'x' })).toBe(false);+ expect(await recallDoneFrame('f1.pending')).toBeNull();+ });+});