3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Report a backend fallback only when the native tracer did not draw the frame (#2290)
Nguyen Xuan Anb82bdfbc1199
diff --git a/changes/2290.md b/changes/2290.mdnew file mode 100644index 00000000..b0035152--- /dev/null+++ b/changes/2290.md@@ -0,0 +1 @@+- A native trace that succeeds no longer reports a backend fallback and fails its job with "Snapshot must contain finite, acyclic JSON"; a real fallback always names a reason.diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex 24de5faf..355094b9 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -22,7 +22,7 @@ import { chooseDenoiser, finishWithOidn } from './agent-path-trace-denoise.mjs';import { createNativeSequence } from './agent-native-sequence.mjs';import { chooseNativeTemporal, createTemporalAccumulator, temporalFrameSeed } from './agent-native-temporal.mjs';import { readNativeCapacity } from './native-capacity.mjs';-import { describeBackendFallback, explainFailureAfterFallback } from '../src/agent-backend-fallback.js';+import { backendFallbackForFrame, explainFailureAfterFallback } from '../src/agent-backend-fallback.js';import { chooseNativeInstancing, chooseNativeKernel, chooseTraceBackend, createNativeTracerLocator, fetchNativeExport, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';import { addonCapabilities, addonFileFor, addonImportMap } from './mcp-addons.mjs';import { createAgentAssetCatalog, fingerprintAssetDirectory } from './agent-asset-catalog.mjs';@@ -1068,9 +1068,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browbackendNote += ' The ' + traceOptions.backend + ' backend ran instead.';}}- const fallback = settings.renderer.backend === 'native' && traceOptions.backend !== 'native'- ? describeBackendFallback({ requestedBackend: 'native', usedBackend: traceOptions.backend, fallbackReason })- : undefined;+ const fallback = backendFallbackForFrame({ requestedBackend: settings.renderer.backend, tracedNatively: Boolean(traced), usedBackend: traceOptions.backend, fallbackReason });if (!traced) {try {traced = await jobPage.evaluate(input => window.__agentPreview.pathTrace(input), { ...frameInput, options: traceOptions });diff --git a/src/agent-backend-fallback.js b/src/agent-backend-fallback.jsindex 8cd530b6..f36b7fab 100644--- a/src/agent-backend-fallback.js+++ b/src/agent-backend-fallback.js@@ -6,6 +6,19 @@ export function describeBackendFallback({ requestedBackend, usedBackend, fallbacreturn { requestedBackend, usedBackend, fallbackReason };}+/**+ * The fallback a traced frame reports, or undefined when the frame ran where it was asked to. A native frame traces with+ * the gpu kernel option, so the used backend alone cannot tell a native frame from a fallen back one: pass whether the+ * native tracer drew it.+ */+export function backendFallbackForFrame({ requestedBackend, tracedNatively, usedBackend, fallbackReason }) {+ if (requestedBackend !== 'native' || tracedNatively) return undefined;+ const reason = typeof fallbackReason === 'string' && fallbackReason.length > 0+ ? fallbackReason+ : 'the native tracer did not draw this frame.';+ return describeBackendFallback({ requestedBackend, usedBackend, fallbackReason: reason });+}+/*** The error a fallen back job fails with, now naming the fallback. The original message stays first, so its own advice* (such as the triangle limit) still reads the same; the added sentence says why native was not used and what to pass.diff --git a/tests/native-fallback-reason.test.js b/tests/native-fallback-reason.test.jsindex cf98442a..d14d2ee0 100644--- a/tests/native-fallback-reason.test.js+++ b/tests/native-fallback-reason.test.js@@ -1,7 +1,7 @@import test from 'node:test';import assert from 'node:assert/strict';import { chooseTraceBackend, createNativeTracerLocator } from '../scripts/agent-native-trace.mjs';-import { describeBackendFallback, explainFailureAfterFallback } from '../src/agent-backend-fallback.js';+import { backendFallbackForFrame, describeBackendFallback, explainFailureAfterFallback } from '../src/agent-backend-fallback.js';const TRIANGLE_LIMIT_MESSAGE = 'This GPU path trace takes at most 2000000 triangles in total, got 2500000.';@@ -34,3 +34,21 @@ test('a job that ran on the backend it asked for keeps its error unchanged', ()const error = new RangeError(TRIANGLE_LIMIT_MESSAGE);assert.equal(explainFailureAfterFallback(error, undefined).message, TRIANGLE_LIMIT_MESSAGE);});++test('a frame the native tracer drew reports no fallback, though it traced with the gpu kernel option', () => {+ const fallback = backendFallbackForFrame({ requestedBackend: 'native', tracedNatively: true, usedBackend: 'gpu', fallbackReason: undefined });+ assert.equal(fallback, undefined);+});++test('a native frame that fell back always names a reason string', () => {+ const withReason = backendFallbackForFrame({ requestedBackend: 'native', tracedNatively: false, usedBackend: 'cpu', fallbackReason: 'the adapter was lost.' });+ assert.deepEqual(withReason, { requestedBackend: 'native', usedBackend: 'cpu', fallbackReason: 'the adapter was lost.' });+ const withoutReason = backendFallbackForFrame({ requestedBackend: 'native', tracedNatively: false, usedBackend: 'gpu', fallbackReason: undefined });+ assert.equal(typeof withoutReason.fallbackReason, 'string');+ assert.ok(withoutReason.fallbackReason.length > 0);+ assert.doesNotThrow(() => JSON.stringify(withoutReason));+});++test('a job that did not ask for native never reports a fallback', () => {+ assert.equal(backendFallbackForFrame({ requestedBackend: 'gpu', tracedNatively: false, usedBackend: 'gpu', fallbackReason: undefined }), undefined);+});