3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Name the running job in the render-lease error (#2050)
Nguyen Xuan An94520ea52ddb
diff --git a/changes/2050.md b/changes/2050.mdnew file mode 100644index 00000000..24654b38--- /dev/null+++ b/changes/2050.md@@ -0,0 +1 @@+- A scene tool refused while a render job runs now names that job, its frame count and the tool to call next (#2050)diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.mdindex 0b75712c..589e399b 100644--- a/docs/agent-render-jobs.md+++ b/docs/agent-render-jobs.md@@ -31,7 +31,7 @@ The store records UUIDs that `scene_capabilities` lists after a restart.The runtime captures the source recipe and verified asset bytes before returning a job ID.The job uses a separate browser page and temporarily leases the single renderer.-Preview rendering and edits pause during a job. Inspection and recipe export remain available.+While a job runs, these tools fail until it finishes or is cancelled: `scene_create`, `scene_create_asset`, `scene_apply`, `mesh_edit`, `mesh_stack`, `scene_look`, `scene_review`, `scene_checkpoint`, `scene_restore`, `scene_release_checkpoint`, `scene_export_glb`, `scene_export_web`, `scene_dispose` and `scene_render_submit`. Inspection (`scene_inspect`, `mesh_inspect`, `scene_walkmap`), `scene_export_recipe` and the `scene_render_*` status, cancel, result and release tools stay available. The error names the running job, how many frames it has done and the two tools to call: `scene_render_status` with its `jobId`, or `scene_render_cancel`.The source revision, pose and checkpoints survive completion or cancellation.Cancellation becomes terminal after the owned encoder and job page stop and the preview recovers.diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex 3327fc21..ebf150cc 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -111,6 +111,12 @@ const VENDOR_FILES = Object.freeze({});/** Checks the launch paths that need no job folder; the CLI runs it before serving so a bad value exits with its message. */+// What a tool that needs the preview renderer says while a render job holds it: which job, how far it is, and the next call.+function leaseHeldMessage(record) {+ const progress = record.state === 'running' ? ` (frame ${record.progress.frames} of ${record.settings.frameCount})` : '';+ return `The renderer is leased to render job ${record.jobId}, which is ${record.state}${progress}. Poll scene_render_status with {"jobId":"${record.jobId}"} until it is completed, or stop it with scene_render_cancel, then call this tool again.`;+}+export function validateLaunchPaths({ browser, assets, packs, ffmpeg = 'ffmpeg', audio }) {if (browser !== undefined && (typeof browser !== 'string' || !existsSync(browser))) {throw new Error('The configured browser executable does not exist.');@@ -339,19 +345,22 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browreturn { path, filename, mimeType: 'model/gltf-binary', bytes: bytes.length,sha256: createHash('sha256').update(bytes).digest('hex'), keptExports: savedGlbPaths.length };}- /** True while the renderer is still leased: a render job exists that has not reached a terminal state. */- async function rendererStillLeased() {- if (phase !== 'rendering') return false;+ /** The render job that still holds the renderer: one that has not reached a terminal state. Undefined when the renderer is free. */+ async function leasingJob() {+ if (phase !== 'rendering') return undefined;const terminal = ['completed', 'cancelled', 'failed', 'interrupted'];- if ((await jobs()).list().some(record => !terminal.includes(record.state))) return true;+ const running = (await jobs()).list().find(record => !terminal.includes(record.state));+ if (running) return running;// A queued job can be cancelled before its runner acquires the renderer.phase = 'ready';- return false;+ return undefined;+ }+ async function rendererStillLeased() {+ return (await leasingJob()) !== undefined;}async function requirePreviewRenderer() {- if (await rendererStillLeased()) {- throw new Error('The renderer is leased to a render job. Wait for completion or cancel the job.');- }+ const holder = await leasingJob();+ if (holder) throw new Error(leaseHeldMessage(holder));}function catalog() {if (!assetRoot && !packsRoot) throw new Error('Configure --assets or --packs with an absolute directory before importing GLB assets.');diff --git a/skills/render-crucible-media/references/limits-and-checks.md b/skills/render-crucible-media/references/limits-and-checks.mdindex d085abb6..d7c24f8a 100644--- a/skills/render-crucible-media/references/limits-and-checks.md+++ b/skills/render-crucible-media/references/limits-and-checks.md@@ -26,8 +26,10 @@ before you promise a size or a sound track.`maxSeconds` per frame.- Output files of one job: 128 MiB in all, 12 MiB a frame (48 MiB for `png16` or `exr`); a job over it fails with that limit.- Placed assets and `.67vg` grid files of one scene count together toward a 64 MiB cap; a scene over it fails with the cap message.-- A job leases the single preview renderer: previews and edits pause while it runs, inspection and recipe export stay- available. Plan one job at a time.+- A job leases the single preview renderer. While it runs, `scene_create`, `scene_create_asset`, `scene_apply`, `mesh_edit`, `mesh_stack`, `scene_look`,+ `scene_review`, `scene_checkpoint`, `scene_restore`, `scene_release_checkpoint`, `scene_export_glb`, `scene_export_web`, `scene_dispose` and `scene_render_submit`+ fail with the running job's ID and frame count; call `scene_render_status` with that `jobId`, or `scene_render_cancel`. Inspection, recipe export and the+ job tools stay available. Plan one job at a time.## Check the resultdiff --git a/tests/agent-runtime.test.js b/tests/agent-runtime.test.jsindex 025266f9..9be9c088 100644--- a/tests/agent-runtime.test.js+++ b/tests/agent-runtime.test.js@@ -422,6 +422,26 @@ runTest('scene_render_status of a finished job still answers while a newer job h} finally { await runtime.close(); }});+runTest('a tool blocked by a render job names the job, how far it is and the tools to call next (#2050)', async () => {+ const runningJobId = randomUUID();+ const records = [{ jobId: runningJobId, state: 'running', progress: { frames: 3, maximumPendingFrames: 1 }, settings: { frameCount: 24 } }];+ const controller = { list: () => records, status: jobId => records.find(record => record.jobId === jobId), close: async () => {}, submit: async () => ({ jobId: runningJobId }) };+ const { runtime, sessionId } = await reviewRuntimeHarness({+ runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },+ contextOverrides: { createAgentRenderJobs: async () => controller } });+ try {+ await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });+ for (const blocked of [() => runtime.look({ sessionId }), () => runtime.dispose({ sessionId }), () => runtime.exportGlb({ sessionId })]) {+ await assert.rejects(blocked(), error => {+ assert.ok(error.message.includes(runningJobId), error.message);+ assert.match(error.message, /running \(frame 3 of 24\)/);+ assert.match(error.message, /scene_render_status.*scene_render_cancel/);+ return true;+ });+ }+ } finally { await runtime.close(); }+});+async function runOversizeJob({ requested, jobRender, memory }) {let runJob;const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };