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): 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.js
new file mode 100644
index 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.js
index 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.js
index 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: the
diff --git a/tests/forge-done-cache.test.js b/tests/forge-done-cache.test.js
new file mode 100644
index 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();
+ });
+});