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.

forge(async): carry the PBR opt-out across a job handle and emit forge.completed/failed webhooks

nirholasd18c9ac2cab8
diff --git a/api/_lib/forge-job-options.js b/api/_lib/forge-job-options.js
index ea7aa95b4..3cdc6428a 100644
--- a/api/_lib/forge-job-options.js
+++ b/api/_lib/forge-job-options.js
@@ -5,10 +5,11 @@
// the SAME serverless invocation that submits the job. An asynchronous lane
// (Replicate/TRELLIS, Hunyuan3D, sketch, BYOK) completes in a LATER, separate
// invocation of pollJob(), which only has the job handle — not the original
-// request body. This module remembers the request-affecting subset (today,
-// just the post-generation compression choice) against the job handle for the
-// lifetime of a single poll cycle, so a completed async job still gets the
-// caller's requested output_format applied at materialize time.
+// request body. This module remembers the request-affecting subset (the
+// post-generation compression choice, and whether the caller opted OUT of the
+// PBR material completion pass) against the job handle for the lifetime of a
+// single poll cycle, so a completed async job still gets the caller's requested
+// output_format and material handling applied at materialize time.
//
// Mirrors the bindJobToCacheKey/cacheKeyForJob idiom in forge-cache.js exactly:
// best-effort, short-TTL, fail-open without Redis (a cache/store outage just
@@ -25,24 +26,32 @@ function client(override) {
}
/**
- * Remember the compression choice a just-submitted job should apply at
+ * Remember the post-generation choices a just-submitted job should apply at
* completion. No-op (and safe to call unconditionally) when there is nothing
* non-default to remember, or when Redis is unavailable.
*/
export async function bindJobToOptions(jobHandle, opts, { redis } = {}) {
const r = client(redis);
if (!r || !jobHandle || !opts) return;
- if (opts.compression === 'none') return; // default behavior needs no binding
+ const compression = opts.compression === 'none' ? null : opts.compression;
+ // derivePbr is opt-OUT, so only an explicit false is worth remembering: an
+ // unbound job takes the default-on path at materialize time either way.
+ const derivePbr = opts.derivePbr === false ? false : null;
+ if (!compression && derivePbr === null) return; // default behavior needs no binding
+ const value = {
+ ...(compression ? { compression } : {}),
+ ...(derivePbr === false ? { derivePbr: false } : {}),
+ };
try {
- await r.set(`${PREFIX}${jobHandle}`, JSON.stringify({ compression: opts.compression }), { ex: TTL_S });
+ await r.set(`${PREFIX}${jobHandle}`, JSON.stringify(value), { ex: TTL_S });
} catch {
/* best-effort */
}
}
/**
- * Resolve the compression choice bound to a job handle, or null when none was
- * bound (the common case — no options requested, or Redis unavailable).
+ * Resolve the post-generation choices bound to a job handle, or null when none
+ * were bound (the common case — no options requested, or Redis unavailable).
*/
export async function optionsForJob(jobHandle, { redis } = {}) {
const r = client(redis);
@@ -51,7 +60,10 @@ export async function optionsForJob(jobHandle, { redis } = {}) {
const raw = await r.get(`${PREFIX}${jobHandle}`);
if (!raw) return null;
const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
- return value && typeof value.compression === 'string' ? value : null;
+ if (!value || typeof value !== 'object') return null;
+ const hasCompression = typeof value.compression === 'string';
+ const hasDerivePbr = value.derivePbr === false;
+ return hasCompression || hasDerivePbr ? value : null;
} catch {
return null;
}
diff --git a/api/_lib/webhook-dispatch.js b/api/_lib/webhook-dispatch.js
index afe949d10..8451ffd13 100644
--- a/api/_lib/webhook-dispatch.js
+++ b/api/_lib/webhook-dispatch.js
@@ -24,6 +24,16 @@ const EVENT_TYPES = [
'agent.created',
'agent.updated',
'agent.deleted',
+ // Generation jobs. A forge job is asynchronous and can outlive the browser
+ // that started it (see docs/forge-background-generation.md), so an
+ // integrator who submits over the API has no way to learn the outcome
+ // except by polling. These two events close that: they fire from the two
+ // universal terminal writers in forge-store.js (materializeCreation and
+ // markFailed), which every lane flows through, so a job that finishes on
+ // the free browser lane, the x402 paid lane or the unattended finalizer
+ // all deliver the same event exactly once.
+ 'forge.completed',
+ 'forge.failed',
];
export { EVENT_TYPES };
diff --git a/api/forge.js b/api/forge.js
index 5d7586a13..11ba25a9f 100644
--- a/api/forge.js
+++ b/api/forge.js
@@ -618,6 +618,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
glbUrl: submitted.resultGlbUrl,
quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
// One auto-retry on a flagged low-quality/degenerate output (CLAUDE.md: no
@@ -655,6 +656,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
glbUrl: retry.resultGlbUrl,
quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
if (retryDurable) {
durable = retryDurable;
@@ -694,6 +696,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
glbUrl: r.resultGlbUrl, quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
},
@@ -889,6 +892,7 @@ async function runHfImageLane({
glbUrl: resultGlbUrl,
quality: true,
compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
// One auto-retry on a flagged low-quality/degenerate output. Only attempted
@@ -932,6 +936,7 @@ async function runHfImageLane({
glbUrl: retryFinished.resultGlbUrl,
quality: true,
compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
if (retryDurable) {
durable = retryDurable;
@@ -981,6 +986,7 @@ async function runHfImageLane({
const rd = await materializeCreation({
replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
glbUrl: rf.resultGlbUrl, quality: true, compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
} finally {
@@ -1655,6 +1661,7 @@ async function startJob(req, res) {
glbUrl: submitted.resultGlbUrl,
quality: true,
compress: opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts.derivePbr !== false,
});
return json(res, 200, {
job_id: null,
@@ -2879,6 +2886,7 @@ async function pollJob(req, res, jobId) {
glbUrl: result.resultGlbUrl,
quality: true,
compress: boundOpts?.compression || null,
+ derivePbr: boundOpts?.derivePbr !== false,
});
// Populate the result cache this job was bound to at submit time (text→3D,
// non-high-tier, platform-keyed lanes only: see forgeResultCacheKey). A