Skip to content

3D engine that AI agents drive

Name the running job in the render-lease error (#2050)

Nguyen Xuan An94520ea52ddb
diff --git a/changes/2050.md b/changes/2050.md
new file mode 100644
index 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.md
index 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.mjs
index 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', brow
return { 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.md
index 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 result
diff --git a/tests/agent-runtime.test.js b/tests/agent-runtime.test.js
index 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' }) };