Skip to content

3D engine that AI agents drive

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.md
new file mode 100644
index 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.mjs
index 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', brow
backendNote += ' 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.js
index 8cd530b6..f36b7fab 100644
--- a/src/agent-backend-fallback.js
+++ b/src/agent-backend-fallback.js
@@ -6,6 +6,19 @@ export function describeBackendFallback({ requestedBackend, usedBackend, fallbac
return { 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.js
index 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);
+});