Skip to content

3D engine that AI agents drive

Report a job's kernel compile in its render report (#1949)

Nguyen Xuan Anff0300bfdccf
diff --git a/changes/1949-job-compile.md b/changes/1949-job-compile.md
new file mode 100644
index 00000000..45e265c2
--- /dev/null
+++ b/changes/1949-job-compile.md
@@ -0,0 +1 @@
+- A film or stills job whose first frame compiled kernels now says so in its render report, also in the concise result, and the render estimate no longer counts that one-time compile (#1949).
diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.md
index ea900b5e..41bcfd10 100644
--- a/docs/agent-render-jobs.md
+++ b/docs/agent-render-jobs.md
@@ -250,7 +250,7 @@ An `image`, `stills` or `video` job can ask for the offline [path tracer](https:
Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/cook` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises (OIDN runs on a device kept alive between frames when the OIDN library is installed, so only the first frame pays for the device and the filter commit; `metrics.pathTracer.oidnMode` says `in-process` or `cli`) and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/crucible-denoise-oidn` and its binary are installed, else (or when OIDN fails) the GPU a-trous filter of the native tracer with a note in `metrics.pathTracer.denoiserNote` (`denoiser: "atrous"`; it is biased, it smooths; `denoise: "wavelet"` asks for the CPU filter). The report carries `kernel` and `averageSamples`. The Cycles-matching kernel takes up to 4,000,000 unique triangles (copies of a shared mesh count once, and the scene may hold four times that with every copy counted); the job reads the scene from its page as one Blob over the DevTools stream (about half the time of returning it as base64, and no single message bounds it); from the second frame of a `stills` or `video` job the page sends only the table bytes that changed since the frame before (a scene with moving particles sends the particles, not the static meshes; a table that changed length sends the changes in the bytes it shares with the old one and the new tail), the job rebuilds the same tables from them, and `metrics.pathTracer.exportSentBytes` says how many bytes crossed (`JS67_NATIVE_EXPORT_DELTA=off` reads every table whole); the `cpu` backend and the older kernel keep 400,000, and the `gpu` backend takes what the page's WebGL2 context holds, up to 2,000,000 (see [path-tracer.md](https://github.com/codepawl/crucible/blob/main/docs/path-tracer.md)). A larger scene is refused with an error that names the limit. On the Cycles-matching kernel the job sends each material whole (FORMAT-v2 tables, instanced or not): blend opacity (`alphaMode: "blend"` with `opacity` below 1), sheen, `specular` and `specularColor`, anisotropy, iridescence, attenuation, and the clearcoat, transmission, sheen, anisotropy and coat normal maps all reach the kernel, and `metrics.pathTracer.ignored` lists only what it does not shade (the legacy kernel keeps the v1 tables and the old notes). A scene whose materials cannot be exported whole is traced from the v1 tables for that frame with the reason in `materialsReason`; the native tracer stays usable. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A native `stills` or `video` job (the Cycles-matching kernel) also keeps one native session for the whole job: a frame that only moves the camera reuses the uploaded scene, the compiled kernel and the acceleration structures; changed materials, lights, instance transforms or triangles (the table may change length) are sent to the session, which rebuilds only the changed meshes' acceleration structures; a frame whose record counts, placed meshes, emissive meshes, textures or environment changed gets a new session, and a failed session update or render falls back to a new session or a one-shot trace for that frame. `metrics.pathTracer.nativeSession` says which one each frame took (`path` is `new-session`, `reused`, `updated` or `one-shot`, with `reason`, `changedTables`, `changedMeshes` (after a triangles update), `pipelineReused` and `accelerationReused`); `metrics.nativeSessionRoutes` lists the `path` of every frame. A job reuses the session only when the tables the page exports are equal to the previous frame's apart from the camera (`reused`), or differ in material values, lights, instance transforms or triangles (`updated`). Geometry that moves with the time, such as particle systems (sparks, swaying hair) or a moved node in a scene exported as flattened triangles, goes through `updated` and costs one BLAS build per changed mesh plus the TLAS. A changed emissive mesh, other record counts or another set of placed meshes gives that frame a new session, which costs what a one-shot trace costs and is byte-identical to it; `reason` names the first table that differed. A single-frame job and `JS67_NATIVE_KERNEL=legacy` trace one-shot and carry no `nativeSession`; `JS67_NATIVE_SESSIONS=off` in the server's environment traces every frame one-shot (default on). The session is closed when the job ends or fails, and every frame of a stills job equals the one-shot render byte for byte. A native video also blends its frames over time, so the noise the denoiser leaves does not shimmer from frame to frame: each pixel finds where its surface point was in the frame before (from the first-hit distance and the two cameras) and the filtered light is averaged with what was gathered there. A pixel whose surface was hidden, off screen, another surface or seen from a direction more than about 6 degrees away in the frame before starts again, so a cut to another view starts again too, and the whole image starts again at a new shot of a `timeline` and on any frame whose scene, light or render settings changed (its route is not `reused`), so a video with moving parts or lights, or a dip through black, gets no blending on those frames. Each frame of such a video traces with its own seed (`seed` plus the frame number), and `metrics.pathTracer.temporal` reports `historyShare` (the share of pixels that found their history, from the last frame) with `restarted` saying why an image started again. The blend assumes a still scene under a moving camera: light that depends on the view (a sharp reflection, a highlight, the view through glass) trails the camera by a few frames, and an orthographic camera is not blended. `JS67_NATIVE_TEMPORAL=off` in the server's environment turns the blending off, which makes every video frame equal its one-shot render again. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). A scene with `postPasses` is traced without them: the PNG is the plain traced frame and `metrics.diagnostics` carries a `post-passes-skipped` warning naming the passes (see [user-passes.md](user-passes.md)). `passes` are refused with it, because the tracer has no object ID, depth or normal pass; part findings (framing, floating, intersecting, textures, z-fighting) still reach `metrics.diagnostics` from the first frame, with a `findings-unavailable` entry saying that exposure findings are not available on a traced job (see [mcp.md](mcp.md)). The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.
-A native frame that compiled its kernel says so in `metrics.pathTracer`: `compileSeconds` is the compile, `gpuTraceSeconds` the trace; a compile over one second adds `kernelCompileNote`. The first trace of each scene variant (a scene with no emitter is its own variant) compiles; later frames of the job reuse it. Details: [path-tracer.md](https://github.com/codepawl/crucible/blob/main/docs/path-tracer.md).
+A native frame that compiled its kernel says so in `metrics.pathTracer`: `compileSeconds` is the compile, `gpuTraceSeconds` the trace; a compile over one second adds `kernelCompileNote`. The first trace of each scene variant (a scene with no emitter is its own variant) compiles; later frames of the job reuse it. `metrics.pathTracer` describes the last frame, so the job adds the compile of every frame into `metrics.kernelCompile`, and `metrics.report.kernelCompile` carries it with a note once it reaches one second (see [mcp.md](mcp.md)). Details: [path-tracer.md](https://github.com/codepawl/crucible/blob/main/docs/path-tracer.md).
## Controller API
diff --git a/docs/mcp.md b/docs/mcp.md
index eaf7865b..78bf2c67 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -241,7 +241,7 @@ Measured on 2026-11-15 with `node scripts/measure-render-estimate.mjs` (RTX 3060
The runtime keeps the last 16 jobs run from this jobs folder in `render-history.json`: each entry holds the model's estimate and the measurement of one finished job, with its kind (raster or path tracer, image or video, backend). Once two jobs of the same kind are there, the estimate is multiplied by the median measured-over-estimated ratio of those jobs, never by more than 4 either way, and `basis` says so, including when the time factor hit the 4x limit and when memory had too little history of its own. A job that ran at a smaller size than requested (the memory budget cut the frame) is not recorded. The file stays on the machine; a damaged file counts as no history. `modelSeconds` and `modelPeakMemoryMiB` are the numbers before this correction.
-When a job completes, `scene_render_result` has `metrics.report`, one record of what happened: `measured` (`seconds`, `peakMemoryMiB`, `frames`, `secondsPerFrame`), the `estimate` it was compared with and `secondsRatio` (measured over estimated), `samplesDrawn` and `samplesRequested` for a path trace, `noise` for a path trace, and `fallbacks`, a list of sentences for everything that ran differently from the request (a frame cut down to fit `--memory`, a backend that fell back, a denoiser that was swapped). `noise.relative` is the estimated noise of the frame before any denoiser: the root mean square of each pixel's standard error (from the tracer's variance buffer) over the frame's mean luminance, so 0.03 means a typical pixel is off by 3% of the average brightness. `noise.verdict` says what to do: from 0.03 up it is `noisy: raise renderer.samples or set renderer.denoise` (only `raise renderer.samples` when a denoiser already ran), below it `clean enough`. The line sits between a 4 and a 16 sample trace of one small lit test scene (0.038 and 0.020); it comes from those numbers, not from a survey of scenes. Under 2 samples per pixel, or on a black frame, `relative` is `null` and the verdict says it was not measured. A raster job has no `noise`. The concise answer keeps only `seconds`, `secondsRatio`, `fallbacks` and a measured `noise` of it; the detailed answer has the whole record and the raw counters it is built from (`peakNodeBytes`, `peakBrowserHeap`, `elapsedSeconds`).
+When a job completes, `scene_render_result` has `metrics.report`, one record of what happened: `measured` (`seconds`, `peakMemoryMiB`, `frames`, `secondsPerFrame`), the `estimate` it was compared with and `secondsRatio` (measured over estimated), `samplesDrawn` and `samplesRequested` for a path trace, `noise` for a path trace, and `fallbacks`, a list of sentences for everything that ran differently from the request (a frame cut down to fit `--memory`, a backend that fell back, a denoiser that was swapped). A native trace that compiled kernels for at least one second across the job adds `kernelCompile` (`seconds`, `frames`, `note`): the first trace of each scene variant compiles, the time counts in `seconds` and `secondsRatio`, and the estimate history learns the job without it. `noise.relative` is the estimated noise of the frame before any denoiser: the root mean square of each pixel's standard error (from the tracer's variance buffer) over the frame's mean luminance, so 0.03 means a typical pixel is off by 3% of the average brightness. `noise.verdict` says what to do: from 0.03 up it is `noisy: raise renderer.samples or set renderer.denoise` (only `raise renderer.samples` when a denoiser already ran), below it `clean enough`. The line sits between a 4 and a 16 sample trace of one small lit test scene (0.038 and 0.020); it comes from those numbers, not from a survey of scenes. Under 2 samples per pixel, or on a black frame, `relative` is `null` and the verdict says it was not measured. A raster job has no `noise`. The concise answer keeps only `seconds`, `secondsRatio`, `fallbacks`, the `kernelCompile` note and a measured `noise` of it; the detailed answer has the whole record and the raw counters it is built from (`peakNodeBytes`, `peakBrowserHeap`, `elapsedSeconds`).
Limits of the estimate: it covers a job's own time, not the wait for a busy machine; memory is the sampled Node RSS plus the browser JS heap, which is a lower bound for GPU memory; path tracer estimates assume the CPU or GPU backend named in the settings, and a native tracer that cannot run falls back (see `fallbacks`).
diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjs
index 3a0045f3..3a44d730 100644
--- a/scripts/agent-native-trace.mjs
+++ b/scripts/agent-native-trace.mjs
@@ -1,6 +1,7 @@
// renderer.backend "native" on render jobs: the optional hardware ray query tracer (Cook, @codepawlhq/cook) traces the scene
// the job page exported, then the job runner denoises and writes the PNG. The package and its binary are optional: when they,
// or a Vulkan ray query adapter, are missing, the job runs on the gpu or cpu backend and the report says why.
+import { NOTEWORTHY_COMPILE_SECONDS } from './agent-render-estimate.mjs';
import { existsSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
@@ -367,8 +368,6 @@ export function yieldToEventLoop() {
return new Promise(resolve => setImmediate(resolve));
}
-/** A kernel compile shorter than this is not worth a sentence in the report. */
-const NOTEWORTHY_COMPILE_SECONDS = 1;
/**
* The sentence for a frame that spent seconds compiling its kernel, or undefined when it did not. Cook compiles one kernel per
diff --git a/scripts/agent-render-estimate.mjs b/scripts/agent-render-estimate.mjs
index 58513aa1..de1f4b7c 100644
--- a/scripts/agent-render-estimate.mjs
+++ b/scripts/agent-render-estimate.mjs
@@ -88,6 +88,27 @@ function round(value, digits) {
return Math.round(value * scale) / scale;
}
+// A kernel compile shorter than this is lost beside a trace; the native tracer's per-frame note uses the same line.
+export const NOTEWORTHY_COMPILE_SECONDS = 1;
+
+/**
+ * Adds one traced frame's kernel compile to the job's total. The path tracer report in the metrics describes only the last
+ * frame, so without this a film whose first frame compiled for seconds ended with no trace of it (#1949).
+ */
+export function addKernelCompile(total, frameReport) {
+ const seconds = frameReport?.compileSeconds;
+ if (!(seconds > 0)) return total;
+ return { seconds: (total?.seconds ?? 0) + seconds, frames: (total?.frames ?? 0) + 1 };
+}
+
+function kernelCompileFrom(metrics) {
+ const compile = metrics.kernelCompile;
+ if (!(compile?.seconds >= NOTEWORTHY_COMPILE_SECONDS)) return undefined;
+ const seconds = round(compile.seconds, 1);
+ const note = `First render of this scene variant: ${seconds.toFixed(1)} s of the job compiled kernels, which is not trace time and is counted in secondsRatio. A later job of the same variant in this server reuses them.`;
+ return { seconds, frames: compile.frames, note };
+}
+
function pathTracerFrameSeconds({ size, settings, backend }) {
const renderer = settings.renderer;
const secondsPerSampleBounce = COST_MODEL.pathTracerSecondsPerSampleBounce[renderer.backend ?? backend] ?? COST_MODEL.pathTracerSecondsPerSampleBounce.cpu;
@@ -208,6 +229,8 @@ export function renderReport({ estimate, settings, metrics }) {
report.secondsRatio = round(measuredSeconds / estimate.seconds, 2);
}
if (frameWasReduced(metrics)) report.frameReduced = true;
+ const kernelCompile = kernelCompileFrom(metrics);
+ if (kernelCompile) report.kernelCompile = kernelCompile;
const traced = metrics.pathTracer;
if (traced) {
// The path tracer's report describes the last frame; the samples asked for are in the job's settings.
@@ -241,7 +264,8 @@ export function historyWithJob(history, { settings, backend, estimate, report })
const entry = {
kind: jobKind(settings, backend),
estimatedSeconds: estimate.modelSeconds,
- measuredSeconds: report.measured.seconds,
+ // A compile is paid once per scene variant and process; the estimate is for the render, so the history learns without it.
+ measuredSeconds: Math.max(0.01, round(report.measured.seconds - (report.kernelCompile?.seconds ?? 0), 2)),
estimatedPeakMemoryMiB: estimate.modelPeakMemoryMiB,
measuredPeakMemoryMiB: report.measured.peakMemoryMiB,
};
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index 24de5faf..b88b9a09 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -43,7 +43,7 @@ import { resolveJobRoot } from './agent-job-root.mjs';
import { createAgentRenderJobs, EXPORT_DIRECTORY_NAME, HIGH_PRECISION_FRAME_FACTOR, RENDER_HISTORY_FILE, normalizeJobSettings, frameByteLimitFor, oversizeFrameBudgetError } from './agent-render-jobs.mjs';
import { RENDER_QUALITY_NOTE, applyQuality, tierReport } from './agent-render-quality.mjs';
import { RENDER_BUDGET_NOTE, chooseBudgetSettings, parseBudget } from './agent-render-budget.mjs';
-import { RENDER_ESTIMATE_NOTE, estimateRenderJob, historyWithJob, parseHistory, pathTraceTriangleProblem, renderReport, sceneSizeFrom } from './agent-render-estimate.mjs';
+import { RENDER_ESTIMATE_NOTE, addKernelCompile, estimateRenderJob, historyWithJob, parseHistory, pathTraceTriangleProblem, renderReport, sceneSizeFrom } from './agent-render-estimate.mjs';
import { objectIdMetrics } from './agent-object-id-metrics.mjs';
import { renderIconsInPage } from './agent-icon-page.mjs';
import { ICON_CAPABILITIES } from '../src/icon-sheet.js';
@@ -1089,6 +1089,8 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
metrics.width = width;
metrics.height = height;
metrics.pathTracer = traced.report;
+ const kernelCompile = addKernelCompile(metrics.kernelCompile, traced.report);
+ if (kernelCompile) metrics.kernelCompile = kernelCompile;
if (frame === 0) {
const looked = await jobPage.evaluate(input => window.__agentPreview.findings(input), frameInput);
mergeFrameDiagnostics(metrics, [pathTracerFindingsLimit(), pathTracerSkippedPassesWarning(snapshot.recipe.postPasses), ...looked.diagnostics].filter(Boolean));
diff --git a/scripts/mcp-response-format.mjs b/scripts/mcp-response-format.mjs
index 7abcf3e0..3d9922bd 100644
--- a/scripts/mcp-response-format.mjs
+++ b/scripts/mcp-response-format.mjs
@@ -66,6 +66,7 @@ function conciseRenderReport(report) {
const concise = { seconds: report.measured?.seconds };
if (report.secondsRatio !== undefined) concise.secondsRatio = report.secondsRatio;
if (report.fallbacks?.length) concise.fallbacks = report.fallbacks;
+ if (report.kernelCompile) concise.kernelCompile = report.kernelCompile.note;
if (report.noise?.relative != null) concise.noise = report.noise;
return concise;
}
diff --git a/tests/render-estimate.test.js b/tests/render-estimate.test.js
index dc26ccaf..031475a9 100644
--- a/tests/render-estimate.test.js
+++ b/tests/render-estimate.test.js
@@ -8,7 +8,7 @@ import { conciseJobResult } from '../scripts/mcp-response-format.mjs';
import { planRenderSize } from '../src/budget.js';
import { MAXIMUM_MEMORY_MIB } from '../src/agent-scene-capabilities.js';
import {
- CORRECTION_BOUND, HISTORY_LIMIT, correctionFromHistory, estimateRenderJob, historyWithJob, jobKind, parseHistory, renderReport, sceneSizeFrom,
+ CORRECTION_BOUND, HISTORY_LIMIT, addKernelCompile, correctionFromHistory, estimateRenderJob, historyWithJob, jobKind, parseHistory, renderReport, sceneSizeFrom,
} from '../scripts/agent-render-estimate.mjs';
const recipe = { format: 'crucible.scene', materials: [{ id: 'wood', map: 'planks' }, { id: 'steel', normalMap: 'dents' }, { id: 'plain' }] };
@@ -208,3 +208,27 @@ test('the reduced-frame fallback never asks for a --memory value over the ceilin
const [reachable] = renderReport({ settings: settingsFor({}), metrics: { ...metrics, requiredMemoryMiB: MAXIMUM_MEMORY_MIB, memoryBudgetMiB: 192 } }).fallbacks;
assert.match(reachable, new RegExp(`Restart it with --memory ${MAXIMUM_MEMORY_MIB} or more`));
});
+
+test('a film whose first frame compiled kernels says so after its last frame, apart from trace time (#1949)', () => {
+ const frames = [{ compileSeconds: 7.04 }, { compileSeconds: 0 }, {}, { compileSeconds: 0.002 }];
+ const kernelCompile = frames.reduce(addKernelCompile, undefined);
+ assert.equal(kernelCompile.frames, 2);
+ const settings = settingsFor({ renderer: { type: 'pathTracer', backend: 'native', samples: 16 } });
+ const metrics = { elapsedSeconds: 9, pathTracer: frames.at(-1), kernelCompile };
+ const estimate = { modelSeconds: 2, modelPeakMemoryMiB: 200, seconds: 2, peakMemoryMiB: 200, basis: 'scene size' };
+ const report = renderReport({ estimate, settings, metrics });
+ assert.equal(report.kernelCompile.seconds, 7);
+ assert.match(report.kernelCompile.note, /^First render of this scene variant: 7\.0 s of the job compiled kernels/);
+ assert.match(report.kernelCompile.note, /counted in secondsRatio/);
+ const concise = conciseJobResult({ jobId: 'x', sourceRevision: 1, artifacts: [], metrics: { report } });
+ assert.equal(concise.metrics.report.kernelCompile, report.kernelCompile.note);
+ // The estimate history learns the render without the one-time compile.
+ assert.equal(historyWithJob([], { settings, backend: 'gpu', estimate, report })[0].measuredSeconds, 2);
+});
+
+test('a job whose compile stayed under a second, or that compiled nothing, carries no compile note', () => {
+ const settings = settingsFor({});
+ assert.equal(addKernelCompile(undefined, { compileSeconds: 0 }), undefined);
+ assert.equal(renderReport({ settings, metrics: { elapsedSeconds: 1, kernelCompile: { seconds: 0.4, frames: 1 } } }).kernelCompile, undefined);
+ assert.equal('kernelCompile' in renderReport({ settings, metrics: { elapsedSeconds: 1 } }), false);
+});