3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import test, { after, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { createAgentRuntime } from '../scripts/agent-runtime.mjs';
import { createAgentAssetCatalog } from '../scripts/agent-asset-catalog.mjs';
import { isPreviewHost } from '../scripts/preview-host.mjs';
import { addonCapabilities, addonFileFor, addonImportMap } from '../scripts/mcp-addons.mjs';
import { sampleBrowserHeap, exceedsMemoryGuard } from '../scripts/agent-memory-guard.mjs';
import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, truncate, utimes, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, isAbsolute, join } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { readVolumeGridFiles } from '../src/mcp-volume-grids.js';
import { writeWebBuild } from '../scripts/web-export.mjs';
import { EXPORT_DIRECTORY_NAME, RENDER_HISTORY_FILE, normalizeJobSettings } from '../scripts/agent-render-jobs.mjs';
import { createServer } from 'node:http';
import { createHash, randomUUID } from 'node:crypto';
import { createContext, Script } from 'node:vm';
import { VEGETATION_CAPABILITY_NOTE } from '../src/agent-vegetation-notes.js';
import { CROWD_CAPABILITY_NOTE } from '../src/agent-crowd-notes.js';
import { SETTLE_CAPABILITY_NOTE } from '../src/settle-notes.js';
import { RENDER_ESTIMATE_NOTE, estimateRenderJob, historyWithJob, parseHistory, renderReport, sceneSizeFrom } from '../scripts/agent-render-estimate.mjs';
import { RENDER_BUDGET_NOTE, chooseBudgetSettings, parseBudget } from '../scripts/agent-render-budget.mjs';
import { RENDER_QUALITY_NOTE, applyQuality, tierReport } from '../scripts/agent-render-quality.mjs';
import { GAME_CAPABILITIES } from '../src/game-setup-notes.js';
import { USER_PASS_CAPABILITIES } from '../src/user-pass.js';
import { MESH_BLEND_CAPABILITIES } from '../src/mesh-blend.js';
import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';
import { estimateFrameBytes } from '../src/budget.js';
import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_FPS, MAXIMUM_JOB_FRAMES, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_SEQUENCE_JOB_SIDE, MAXIMUM_SEQUENCE_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';
import { recipeAssetNeeds } from '../src/agent-scene-assets.js';
import { gameAssetIds } from '../src/game-assets.js';
import { sequenceFrameIds } from '../src/agent-texture-sequence.js';
import { catalogLookReferences, BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES } from '../src/look-catalog.js';
import { TEXTURE_SEQUENCE_CAPABILITIES } from '../src/texture-sequence-limits.js';
import { AGENT_ASSET_LIMITS, assertCombinedAssetBytes } from '../src/agent-asset-limits.js';
import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';
import { audioInputArguments, createAudioLibrary, measureStreamSeconds } from '../scripts/job-audio.mjs';
import { filmTimelineDuration, filmTimelineShotStarts, sampleFilmTimeline } from '../src/film-timeline.js';
import { normalizeReview, REVIEW_LIMITS } from '../scripts/agent-review.mjs';
import { BRANCH_LIMITS, validateBranchName } from '../src/agent-branches.js';
import { sessionProblem, SCENE_STORE_LIMITS } from '../src/agent-errors.js';
import { ANNOTATE_LIMITS, describeMarks, validateMarks } from '../src/agent-annotate.js';
import { openReviewPage } from './support/review-page-dom.mjs';
import * as packLimits from '../src/pack-manifest.js';
import { createPackRegistry } from '../scripts/agent-packs.mjs';
const HARNESS_TEST_TIMEOUT_MS = 30000;
function runTest(name, body) {
return test(name, { timeout: HARNESS_TEST_TIMEOUT_MS }, body);
}
runTest('runtime reports real scene capabilities without launching a browser and closes idempotently', async () => {
const runtime = createAgentRuntime({ backend: 'cpu', memory: 64 });
const capabilities = await runtime.capabilities();
assert.equal(capabilities.phase, 'idle');
assert.equal(capabilities.scene.schemaVersion, 1);
assert.equal(capabilities.preview.maximumActiveScenes, 4);
assert.equal(capabilities.preview.memoryBudgetMiB, 64);
assert.equal(capabilities.preview.backend, 'cpu');
assert.equal(capabilities.review.maximumShots, 4);
assert.deepEqual([capabilities.jobs.maximumWidth, capabilities.jobs.maximumHeight, capabilities.jobs.maximumPixels], [3840, 3840, 3840 * 2160]);
assert.deepEqual([capabilities.jobs.maximumSequenceWidth, capabilities.jobs.maximumSequenceHeight, capabilities.jobs.maximumSequencePixels], [1920, 1920, 1920 * 1080]);
assert.equal(capabilities.review.maximumGridHeight, 1008);
assert.equal(capabilities.review.maximumPendingFrames, 1);
assert.equal(capabilities.sceneLimits.maxGeometryBytes, 32 * 1024 * 1024);
await runtime.close();
await runtime.close();
assert.equal((await runtime.capabilities()).phase, 'closed');
await assert.rejects(runtime.create({ recipe: {} }), /closed/);
});
const openHarnesses = [];
// Every test must end in seconds: a runtime that throws inside the sandbox leaves page promises and
// deadline timers pending, which kept the CI shard alive for 15 minutes (#1212).
afterEach(async () => {
const harnesses = openHarnesses.splice(0);
for (const { runtime, sandboxTimers, releasePages } of harnesses) {
releasePages();
let closeTimer;
await Promise.race([runtime.close().catch(() => {}),
new Promise(resolve => { closeTimer = setTimeout(resolve, 2000); })]);
clearTimeout(closeTimer);
for (const timer of sandboxTimers) clearTimeout(timer);
}
});
// Race a "started" signal against the call that should start it, so a throw inside the runtime
// fails the test with that error instead of waiting for a signal that never comes.
function startedOrFailed(started, pending) {
return Promise.race([started, pending.then(() => undefined)]);
}
// Names the runtime module imports, resolved from the module's own import lines so a new
// constant cannot be missing from the sandbox.
async function importedBindings(source) {
const bindings = {};
const importPattern = /^import\s+(?:(\w+)|\{([^}]*)\})\s+from\s+'([^']+)'/gm;
for (const [, defaultName, namedList, specifier] of source.matchAll(importPattern)) {
if (specifier.endsWith('.json')) continue;
const moduleUrl = specifier.startsWith('.') ? new URL(`../scripts/${specifier}`, import.meta.url).href : specifier;
const namespace = await import(moduleUrl);
if (defaultName) bindings[defaultName] = namespace.default;
for (const entry of (namedList ?? '').split(',').map(item => item.trim()).filter(Boolean)) {
const [exported, local = exported] = entry.split(/\s+as\s+/);
bindings[local] = namespace[exported];
}
}
return bindings;
}
const ANNOTATE_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=';
const ANNOTATE_CAMERA = { eye: [0, 0, 10], target: [0, 0, 0], up: [0, 1, 0], fov: 60, near: 0.1, far: 100 };
function annotateFrameOf({ width, height }, revision, motionTime) {
return { mimeType: 'image/png', data: ANNOTATE_PNG, metadata: { width, height, revision, motionTime: motionTime ?? null }, width, height, camera: ANNOTATE_CAMERA };
}
// A scene with one lamp on the view axis: a ray that starts left of the axis misses it, the others hit it.
function hitNearestLamp(ray) {
return ray.direction[0] < -0.2 ? null : { id: 'lamp', point: [0, 1, 0], normal: [0, 1, 0], distance: 10, material: 'brass' };
}
async function reviewRuntimeHarness({ failShot, blockShot = false, oversize = false, deadlineMs,
failDispose = false, heapSize = 1024, stallPrivatePage = false, blockPrivateCreate = false, resumeDelayMs = 0, suspendDelayMs = 0, failResume = false, hangMethod, failPrivateCreate = false, failPrivateCreateMessage, disposeGate, disposeLostBridge = false, hangBrowserClose = false, closeTimeoutMs, failFirstGoto = false, jobRender, sceneBake, exportedRecipe, runtimeOptions = {}, contextOverrides = {}, lookBytesPerPixel = 0, inspection } = {}) {
const events = [];
const sourceCalls = [];
const sandboxTimers = new Set();
const viewports = [];
const deadlines = [];
let privatePage;
let sourceRevision = 0;
let resolveShotStarted;
const shotStarted = new Promise(resolve => { resolveShotStarted = resolve; });
let resolveAcquisitionStarted;
const acquisitionStarted = new Promise(resolve => { resolveAcquisitionStarted = resolve; });
let resolvePrivatePage;
const acquiredPage = new Promise(resolve => { resolvePrivatePage = () => resolve(privatePage = new FakePage(true)); });
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], ...(sceneBake ? { bake: sceneBake } : {}) };
class FakePage {
constructor(privateTarget) { this.privateTarget = privateTarget; this.closed = false; }
route() {}
exposeFunction() {}
setDefaultTimeout() {}
setViewportSize(size) { this.viewport = size; viewports.push(size); }
goto() {
if (!this.privateTarget && failFirstGoto) {
failFirstGoto = false;
throw new Error('page.goto: Timeout 15000ms exceeded.');
}
}
waitForFunction() {}
isClosed() { return this.closed; }
context() { return { newCDPSession: async () => ({
send: async () => ({ usedSize: heapSize }), detach: async () => { events.push('detach'); },
}) }; }
async evaluate(callback, argument) {
// The render job disposes its private session with a bare session id instead of a method call.
const { method, input } = typeof argument === 'string' ? { method: 'dispose', input: { sessionId: argument } } : argument;
events.push(`${this.privateTarget ? 'private' : 'source'}:${method}`);
if (!this.privateTarget) sourceCalls.push({ method, input });
if (method === hangMethod && !this.privateTarget) return new Promise(() => {});
if (method === 'create' && this.privateTarget && failPrivateCreate) {
failPrivateCreate = false;
throw new Error(typeof failPrivateCreateMessage === 'string' ? failPrivateCreateMessage : 'Injected private create failure');
}
if (method === 'dispose' && this.privateTarget && disposeLostBridge) throw new TypeError("page.evaluate: TypeError: Cannot read properties of undefined (reading 'dispose')");
if (method === 'dispose' && disposeGate) await disposeGate;
if (method === 'resume' && failResume) throw new Error('Injected resume failure');
if (method === 'create' && this.privateTarget && blockPrivateCreate) return new Promise((resolve, reject) => { this.rejectShot = reject; });
if (method === 'create') return { sessionId: input.sessionId, revision: 0, ...(jobRender && this.privateTarget ? { render: jobRender } : {}) };
if (method === 'inspect' && inspection) return inspection;
if (method === 'exportRecipe') return { recipe: exportedRecipe, revision: 1 };
if (method === 'exportGlb') return { data: Buffer.from('glb bytes').toString('base64') };
if (method === 'snapshot') {
if (input.expectedRevision !== sourceRevision) throw new Error('Stale revision for render snapshot.');
return { sourceRevision, recipe };
}
if (method === 'reviewShot') {
resolveShotStarted();
if (blockShot) return new Promise((resolve, reject) => { this.rejectShot = reject; });
if (input.index === failShot) throw new Error('Injected partial shot failure');
return { label: input.shot.label, motionTime: input.shot.motionTime,
rendererTime: input.shot.rendererTime, graphics: 'SwiftShader', width: 384, height: 384 };
}
if (method === 'look') {
const { width, height } = this.viewport;
return { mimeType: 'image/png', data: Buffer.alloc(Math.round(width * height * lookBytesPerPixel)).toString('base64'), metadata: { width, height } };
}
if (method === 'annotateFrame') return annotateFrameOf(this.viewport, sourceRevision, input.motionTime);
if (method === 'pickMarks') return { revision: sourceRevision, marks: describeMarks(validateMarks(input.marks, input), input.camera, { width: input.width, height: input.height, raycast: hitNearestLamp }) };
if (method === 'reviewResult') return { mimeType: 'image/png',
data: Buffer.alloc(oversize ? 1024 * 1024 + 1 : 16).toString('base64') };
if (method === 'dispose' && failDispose) throw new Error('Injected disposal failure');
if (method === 'resume' && resumeDelayMs) await new Promise(resolve => setTimeout(resolve, resumeDelayMs));
if (method === 'suspend' && suspendDelayMs) await new Promise(resolve => setTimeout(resolve, suspendDelayMs));
if (method === 'apply') { sourceRevision++; return { revision: sourceRevision }; }
return {};
}
async close() {
if (this.closed) return;
this.closed = true;
events.push(`${this.privateTarget ? 'private' : 'source'}:close`);
this.rejectShot?.(new Error('Review page closed'));
}
}
const sourcePage = new FakePage(false);
let pageCount = 0;
let browserConnected = true;
const browser = { isConnected: () => browserConnected,
newPage: async () => {
if (++pageCount === 1) return sourcePage;
resolveAcquisitionStarted();
return stallPrivatePage ? acquiredPage : (privatePage = new FakePage(true));
},
close: async () => { if (hangBrowserClose) { hangBrowserClose = false; return new Promise(() => {}); } await privatePage?.close(); await sourcePage.close(); events.push('browser:close'); },
};
const originalSource = await readFile(new URL('../scripts/agent-runtime.mjs', import.meta.url), 'utf8');
let source = originalSource
.replace(/^import .+;\r?$/gm, '')
.replace('export function validateLaunchPaths', 'function validateLaunchPaths')
.replace('export function createAgentRuntime', 'function createAgentRuntime')
.replaceAll('import.meta.url', JSON.stringify(import.meta.url))
.replace("import('playwright-core')", 'Promise.resolve({ chromium: globalThis.chromium })');
if (closeTimeoutMs) source = source.replace('const BROWSER_CLOSE_TIMEOUT_MS = 5000;', `const BROWSER_CLOSE_TIMEOUT_MS = ${closeTimeoutMs};`);
if (deadlineMs) source = source.replace('const EVALUATION_TIMEOUT_MS = 30000;', `const EVALUATION_TIMEOUT_MS = ${deadlineMs};`);
const context = createContext({ ...(await importedBindings(originalSource)),
packageMetadata: { version: 'test' }, existsSync: () => true, readFile: async () => '',
createRequire: () => ({ resolve: () => { throw new Error('no peer in tests'); } }),
runAnnotateSession: async () => ({ outcome: 'timeout' }), openInDefaultBrowser: async () => {},
createNativeTracerLocator: () => ({ find: async () => ({ reason: 'no native tracer in tests' }) }),
createAgentRenderJobs: async () => ({ list: () => [], close: async () => {} }), resolveJobRoot: path => path,
chromium: { launch: async () => { browserConnected = true; return browser; } },
launchWithShaderCache: async () => { browserConnected = true; return browser; }, URL, Buffer, AbortController, process, performance, clearTimeout, runtimeOptions, ...contextOverrides,
setTimeout: (callback, delay) => {
deadlines.push(delay);
const timer = setTimeout(callback, delay);
sandboxTimers.add(timer);
return timer;
},
});
new Script(`${source}\nglobalThis.runtime = createAgentRuntime({ backend: 'cpu', ...runtimeOptions });`).runInContext(context);
const runtime = context.runtime;
openHarnesses.push({ runtime, sandboxTimers, releasePages: () => { resolvePrivatePage(); privatePage?.rejectShot?.(new Error('Harness cleanup')); } });
const created = await runtime.create({ recipe });
const disconnectBrowser = () => { browserConnected = false; };
return { runtime, sessionId: created.sessionId, disconnectBrowser, deadlines, events, sourceCalls, viewports, shotStarted, acquisitionStarted, resolvePrivatePage };
}
function boundedResult(promise) {
let timer;
return Promise.race([promise.then(() => 'settled', () => 'settled'),
new Promise(resolve => { timer = setTimeout(() => resolve('stalled'), 150); }),
]).finally(() => clearTimeout(timer));
}
runTest('scene_look steps a busy PNG down by 0.75 until it fits the 1 MiB budget and says which size came back (#1197)', async () => {
const busy = await reviewRuntimeHarness({ lookBytesPerPixel: 2 });
const stepped = await busy.runtime.look({ sessionId: busy.sessionId, width: 1024, height: 640 });
assert.deepEqual(busy.viewports.slice(-2).map(size => `${size.width}x${size.height}`), ['1024x640', '768x480']);
assert.equal(stepped.metadata.returnedWidth, 768);
assert.equal(stepped.metadata.returnedHeight, 480);
await busy.runtime.close();
assert.equal(stepped.metadata.requestedWidth, 1024);
assert.match(stepped.metadata.note, /1024x640.*768x480/);
const calm = await reviewRuntimeHarness({ lookBytesPerPixel: 0.5 });
const unchanged = await calm.runtime.look({ sessionId: calm.sessionId, width: 1024, height: 640 });
assert.equal(calm.viewports.length, 1);
assert.equal(unchanged.metadata.note, undefined);
await calm.runtime.close();
});
runTest('scene_look fails only when the fourth step down still does not fit, naming that size (#1197)', async () => {
const hopeless = await reviewRuntimeHarness({ lookBytesPerPixel: 50 });
await assert.rejects(hopeless.runtime.look({ sessionId: hopeless.sessionId, width: 1024, height: 640 }), /even at 324x202/);
assert.equal(hopeless.viewports.length, 5);
await hopeless.runtime.close();
});
runTest('an edit of a scene with a bake, or one that adds a bake, gets the bake deadline; a plain edit keeps 30 s', async () => {
const plain = await reviewRuntimeHarness();
await plain.runtime.apply({ sessionId: plain.sessionId, operations: [{ type: 'set-camera', camera: {} }] });
await plain.runtime.apply({ sessionId: plain.sessionId, operations: [{ type: 'set-bake', bake: { preset: 'draft' } }] });
await plain.runtime.apply({ sessionId: plain.sessionId, operations: [{ type: 'set-camera', camera: {} }] });
await plain.runtime.apply({ sessionId: plain.sessionId, operations: [{ type: 'set-bake', bake: null }] });
await plain.runtime.apply({ sessionId: plain.sessionId, operations: [{ type: 'set-camera', camera: {} }] });
const applyDeadlines = plain.deadlines.slice(-5);
assert.deepEqual(applyDeadlines, [30000, 120000, 120000, 120000, 30000]);
await plain.runtime.close();
const baked = await reviewRuntimeHarness({ sceneBake: { preset: 'draft' } });
assert.equal(baked.deadlines.at(-1), 120000, 'creating a scene with a bake gets the bake deadline');
await baked.runtime.apply({ sessionId: baked.sessionId, operations: [{ type: 'set-node', id: 'a' }] });
assert.equal(baked.deadlines.at(-1), 120000, 'moving a part in a baked scene gets the bake deadline');
await baked.runtime.close();
});
runTest('review deadline rejects stalled page acquisition and disposes a late page', async () => {
const { runtime, sessionId, events, acquisitionStarted, resolvePrivatePage } = await reviewRuntimeHarness({
stallPrivatePage: true, deadlineMs: 40,
});
const pending = runtime.review({ sessionId, expectedRevision: 0, shots: [{}] });
try {
await startedOrFailed(acquisitionStarted, pending);
assert.equal(await boundedResult(pending), 'settled', 'deadline must reject without waiting for newPage');
await assert.rejects(pending, /deadline/);
assert.equal((await runtime.capabilities()).phase, 'ready');
resolvePrivatePage();
await new Promise(resolve => setImmediate(resolve));
assert.ok(events.includes('private:close'));
assert.ok(!events.includes('private:create'));
assert.equal((await runtime.apply({ sessionId })).revision, 1);
} finally {
resolvePrivatePage();
await pending.catch(() => {});
await runtime.close();
}
});
runTest('close interrupts stalled page acquisition and late resolution cannot resurrect the runtime', async () => {
const { runtime, sessionId, events, acquisitionStarted, resolvePrivatePage } = await reviewRuntimeHarness({ stallPrivatePage: true });
const pending = runtime.review({ sessionId, expectedRevision: 0, shots: [{}] });
pending.catch(() => {});
await startedOrFailed(acquisitionStarted, pending);
const closing = runtime.close();
try {
assert.equal(await boundedResult(closing), 'settled', 'close must not wait for newPage');
await closing;
await assert.rejects(pending, /closing|closed/);
assert.ok(events.includes('browser:close'));
resolvePrivatePage();
await new Promise(resolve => setImmediate(resolve));
assert.ok(events.includes('private:close'));
assert.ok(!events.includes('private:create'));
assert.ok(!events.includes('source:resume'));
assert.equal((await runtime.capabilities()).phase, 'closed');
} finally {
resolvePrivatePage();
await pending.catch(() => {});
await closing;
}
});
runTest('review queue releases private renderer before source resume, including partial and size failures', async () => {
for (const options of [{}, { failShot: 1 }, { oversize: true }, { heapSize: 256 * 1024 ** 2 + 1 }]) {
const { runtime, sessionId, events } = await reviewRuntimeHarness(options);
try {
const pending = runtime.review({ sessionId, expectedRevision: 0, shots: [{ motionTime: 1 }, {}] });
if (options.failShot !== undefined || options.oversize || options.heapSize) await assert.rejects(pending, /partial shot|1 MiB|heap guard/);
else {
const result = await pending;
assert.equal(result.metadata.sourceRevision, 0);
assert.equal(result.metadata.shots[1].motionTime, null);
assert.equal(result.metadata.maximumPendingFrames, 1);
}
assert.ok(events.indexOf('private:dispose') < events.indexOf('private:close'));
assert.ok(events.indexOf('private:close') < events.indexOf('source:resume'));
assert.equal(events.filter(event => event === 'source:resume').length, 1);
assert.equal((await runtime.apply({ sessionId })).revision, 1);
} finally { await runtime.close(); }
}
});
runTest('queued review detaches its request before a caller can mutate shot clocks', async () => {
const { runtime, sessionId } = await reviewRuntimeHarness();
try {
const input = { sessionId, expectedRevision: 0, shots: [{ motionTime: 1 }] };
const pending = runtime.review(input);
input.shots[0].motionTime = 99;
input.shots.push({ motionTime: 88 });
const result = await pending;
assert.equal(result.metadata.shots.length, 1);
assert.equal(result.metadata.shots[0].motionTime, 1);
} finally { await runtime.close(); }
});
runTest('successful review elapsed time includes source renderer recovery', async () => {
const { runtime, sessionId } = await reviewRuntimeHarness({ resumeDelayMs: 30 });
try {
const result = await runtime.review({ sessionId, expectedRevision: 0, shots: [{}] });
assert.ok(result.metadata.elapsedSeconds >= 0.02, 'elapsed must include the delayed source resume');
assert.equal((await runtime.capabilities()).phase, 'ready');
} finally { await runtime.close(); }
});
runTest('total review deadline closes private page and restores the usable source', async () => {
const { runtime, sessionId, events } = await reviewRuntimeHarness({ blockShot: true, deadlineMs: 40 });
try {
await assert.rejects(runtime.review({ sessionId, expectedRevision: 0, shots: [{}] }), /total [\d.]+ second deadline after 0 of 1 shots/);
assert.ok(events.includes('private:close'));
assert.ok(events.includes('source:resume'));
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a job cut short by its deadline leaves the runtime usable although the scene page is slow to resume (#1256)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId, events } = await reviewRuntimeHarness({ blockPrivateCreate: true, resumeDelayMs: 100, deadlineMs: 40,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const abortController = new AbortController();
setTimeout(() => abortController.abort(new Error('Render job exceeded its elapsed deadline.')), 20);
await assert.rejects(runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: abortController.signal, progress: async () => {} }), /Review page closed/);
assert.ok(events.includes('source:resume'));
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('scene_render_status of a finished job still answers while a newer job holds the renderer', async () => {
const finishedJobId = randomUUID();
const runningJobId = randomUUID();
const records = [{ jobId: finishedJobId, state: 'completed' }, { jobId: runningJobId, state: 'running' }];
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 } });
assert.equal((await runtime.jobStatus({ jobId: runningJobId })).state, 'running');
assert.equal((await runtime.jobStatus({ jobId: finishedJobId })).state, 'completed');
assert.equal((await runtime.capabilities()).phase, 'rendering', 'the renderer stays leased to the running job');
} 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' }) };
const { runtime, sessionId, viewports } = await reviewRuntimeHarness({ jobRender,
runtimeOptions: { memory, jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', ...requested } });
const outcome = await runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', ...requested }, signal: new AbortController().signal, progress: async () => {} }).then(() => undefined, error => error);
return { outcome, viewports };
} finally { await runtime.close(); }
}
runTest('a job frame over 1920x1080 that --memory shrinks is refused with the memory it needs, a 1080p one is only reduced (#1241)', async () => {
const plan = { width: 1920, height: 1080, samples: 4, hdr: false, bloom: true, depth: false, estimatedBytes: estimateFrameBytes(1920, 1080, 4, 2048, { bloom: true }) };
const oversize = await runOversizeJob({ requested: { width: 2880, height: 1620 }, jobRender: plan, memory: 192 });
assert.match(oversize.outcome.message, /2880x1620 was reduced to 1920x1080 by --memory 192.*Fix: start the server with --memory 257 or more/);
assert.deepEqual(oversize.viewports, [], 'the page is never resized for a refused frame');
const standard = await runOversizeJob({ requested: { width: 1920, height: 1080 }, jobRender: { ...plan, width: 960, height: 540 }, memory: 192 });
assert.doesNotMatch(String(standard.outcome?.message), /was reduced to/);
assert.deepEqual(JSON.parse(JSON.stringify(standard.viewports)), [{ width: 960, height: 540 }]);
});
const NON_INDEXED_INSPECTION = vertices => ({ counts: { parts: 1, vertices, materials: 1 }, nodes: [], look: {} });
async function submitWithInspection(inspection, settings, backend) {
const submitted = [];
const controller = { list: () => [], close: async () => {}, submit: async request => { submitted.push(request); return { jobId: 'job' }; } };
const { runtime, sessionId } = await reviewRuntimeHarness({ inspection,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test'), ...(backend ? { backend } : {}) },
contextOverrides: { createAgentRenderJobs: async () => controller } });
try {
const attempt = await runtime.submitJob({ sessionId, expectedRevision: 0, settings }).then(() => undefined, error => error);
return { attempt, submitted, phase: (await runtime.capabilities()).phase };
} finally { await runtime.close(); }
}
runTest('submitJob refuses a path trace over the cpu triangle cap with the count, creates no job and stays ready (#1325)', async () => {
const rejected = await submitWithInspection(NON_INDEXED_INSPECTION(1700000), { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer' } });
assert.match(rejected.attempt?.message ?? '', /about 850000 triangles and the cpu path tracer takes at most 400000/);
assert.match(rejected.attempt.message, /this runtime has no GPU backend/);
assert.equal(rejected.submitted.length, 0);
assert.equal(rejected.phase, 'ready');
});
runTest('submitJob accepts the same oversized scene as a raster job, with backend gpu, and a non-indexed scene under the cap (#1325)', async () => {
const raster = await submitWithInspection(NON_INDEXED_INSPECTION(1700000), { kind: 'image', width: 64, height: 64 });
assert.equal(raster.attempt, undefined);
assert.equal(raster.submitted.length, 1);
const gpu = await submitWithInspection(NON_INDEXED_INSPECTION(1700000), { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer', backend: 'gpu' } }, 'gpu');
assert.equal(gpu.attempt, undefined);
assert.equal(gpu.submitted.length, 1);
// 1,150,000 vertices without indices are about 383,000 real triangles; the estimate says 575,000, inside the safety margin.
const borderline = await submitWithInspection(NON_INDEXED_INSPECTION(1150000), { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer' } });
assert.equal(borderline.attempt, undefined);
assert.equal(borderline.submitted.length, 1);
});
runTest('submitJob refuses a scene of plain nodes whose exact count is over the cap even inside the safety margin (#1325)', async () => {
// 455,168 listed triangles are exact; the vertex-based estimate (3 vertices each, halved) says 682,752, under the 800,000 margin.
const exactNodes = Array.from({ length: 4 }, (_, index) => ({ id: `node-${index}`, triangles: 113792 }));
const inspection = { counts: { parts: 4, vertices: 455168 * 3, materials: 1 }, nodes: exactNodes, look: {} };
const rejected = await submitWithInspection(inspection, { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer' } });
assert.match(rejected.attempt?.message ?? '', /this scene has 455168 triangles and the cpu path tracer takes at most 400000/);
assert.equal(rejected.submitted.length, 0);
assert.equal(rejected.phase, 'ready');
const underCap = { ...inspection, nodes: exactNodes.map(node => ({ ...node, triangles: 90000 })) };
const accepted = await submitWithInspection(underCap, { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer' } });
assert.equal(accepted.attempt, undefined);
});
runTest('a slow suspend at job start does not fail the runtime (#1256)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId, events } = await reviewRuntimeHarness({ blockPrivateCreate: true, suspendDelayMs: 100, deadlineMs: 40,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const abortController = new AbortController();
setTimeout(() => abortController.abort(new Error('Render job exceeded its elapsed deadline.')), 150);
await assert.rejects(runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: abortController.signal, progress: async () => {} }));
assert.ok(events.includes('source:suspend'));
assert.equal((await runtime.capabilities()).phase, 'ready');
} finally { await runtime.close(); }
});
runTest('a failed runtime starts fresh for the next scene, while other calls still say it is failed (#1256)', async () => {
const { runtime, sessionId, disconnectBrowser } = await reviewRuntimeHarness();
try {
disconnectBrowser();
await assert.rejects(runtime.inspect({ sessionId }), /browser disconnected.*scene_create/s);
assert.equal((await runtime.capabilities()).phase, 'failed');
await assert.rejects(runtime.inspect({ sessionId }), /The agent runtime is failed.*scenes.*lost.*scene_create.*scene_create_asset.*no server restart/s);
const fresh = await runtime.create({ recipe: { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] } });
assert.notEqual(fresh.sessionId, sessionId);
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
await assert.rejects(runtime.apply({ sessionId }), /session|scene/i);
} finally { await runtime.close(); }
});
const FRESH_RECIPE = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] };
runTest('a scene page that times out fails the runtime with the recovery hint, and the next scene starts fresh (#1256)', async () => {
const { runtime, sessionId } = await reviewRuntimeHarness({ hangMethod: 'inspect', deadlineMs: 40 });
try {
await assert.rejects(runtime.inspect({ sessionId }), error => /exceeded.*scene_create.*no server restart/s.test(error.message) && !/must be closed/.test(error.message));
assert.equal((await runtime.capabilities()).phase, 'failed');
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a timed-out preview call names the operation that ran long (#2200)', async () => {
const { runtime, sessionId } = await reviewRuntimeHarness({ hangMethod: 'apply', deadlineMs: 40 });
try {
await assert.rejects(runtime.apply({ sessionId, operations: [{ type: 'add-material', material: { id: 'stone', pattern: 'stone' } }, { type: 'add-material', material: { id: 'tiles', pattern: 'tiles' } }] }),
/operation "apply" \(2 operations: add-material\) exceeded 0\.04 seconds/);
} finally { await runtime.close(); }
});
runTest('the next scene_create after a timeout succeeds first try even when the old browser never finishes closing (#2200)', async () => {
const { runtime, sessionId } = await reviewRuntimeHarness({ hangMethod: 'inspect', deadlineMs: 40, hangBrowserClose: true, closeTimeoutMs: 30 });
try {
await assert.rejects(runtime.inspect({ sessionId }), /operation "inspect" exceeded.*scene_create/s);
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a browser start whose page load times out is retried once on a fresh browser (#2200)', async () => {
const harness = await reviewRuntimeHarness({ failFirstGoto: true });
try {
assert.equal(typeof harness.sessionId, 'string');
} finally { await harness.runtime.close(); }
});
runTest('a job whose page navigates under it fails with the page loss and the budget, then the next scene works (#2198)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const submitted = { kind: 'video', width: 1280, height: 720, fps: 24, duration: 12 };
const settings = { ...submitted, frameCount: 288 };
const { runtime, sessionId } = await reviewRuntimeHarness({ failPrivateCreate: true, disposeLostBridge: true,
failPrivateCreateMessage: 'page.evaluate: Execution context was destroyed, most likely because of a navigation',
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test'), memory: 192 },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: submitted });
const failure = await runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} }, settings,
signal: new AbortController().signal, progress: async () => {} }).then(() => assert.fail('the job must fail'), error => error);
assert.match(failure.message, /preview page navigated or reloaded before the first frame at 1280x720/);
assert.match(failure.message, /raise --memory \(now 192 MiB\)/);
assert.doesNotMatch(failure.message, /reading 'dispose'/);
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a job that fails for its own reason is not masked by a lost page bridge on dispose (#2198)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId } = await reviewRuntimeHarness({ failPrivateCreate: true, disposeLostBridge: true, failPrivateCreateMessage: 'Injected scene problem',
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const failure = await runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: new AbortController().signal, progress: async () => {} }).then(() => assert.fail('the job must fail'), error => error);
assert.match(failure.message, /Injected scene problem/);
} finally { await runtime.close(); }
});
runTest('a failed resume after a render job fails the runtime, and the next scene starts fresh (#1256)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId } = await reviewRuntimeHarness({ failResume: true, failPrivateCreate: true,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
await assert.rejects(runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: new AbortController().signal, progress: async () => {} }), /Preview recovery failed after render job/);
assert.equal((await runtime.capabilities()).phase, 'failed');
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a browser lost under a stills job fails the job with its size and limit, and the runtime recovers (#2018)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const submitted = { kind: 'stills', width: 1920, height: 1080, stillCount: 12, fps: 24, passes: ['depth'] };
const settings = { ...submitted, frameCount: 12 };
const { runtime, sessionId } = await reviewRuntimeHarness({ failPrivateCreate: true, failPrivateCreateMessage: 'Target page, context or browser has been closed', failResume: true,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test'), memory: 1024 },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: submitted });
const failure = await runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} }, settings,
signal: new AbortController().signal, progress: async () => {} }).then(() => assert.fail('the job must fail'), error => error);
assert.match(failure.message, /preview browser crashed before the first frame at 1920x1080 with depth pass/);
assert.match(failure.message, /Lower the size or the frame count, or raise --memory \(now \d+ MiB\)/);
assert.doesNotMatch(failure.message, /Preview recovery failed/);
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('a stills job that fails for another reason keeps its own message (#2018)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const submitted = { kind: 'stills', width: 64, height: 64, stillCount: 2, fps: 24 };
const settings = { ...submitted, frameCount: 2 };
const { runtime, sessionId } = await reviewRuntimeHarness({ failPrivateCreate: true, failPrivateCreateMessage: 'Injected scene problem',
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: submitted });
await assert.rejects(runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} }, settings,
signal: new AbortController().signal, progress: async () => {} }), /^Error: Injected scene problem$/);
} finally { await runtime.close(); }
});
runTest('a job still unwinding when the runtime restarts does not fail the new runtime (#1256)', async () => {
let runJob;
let openGate;
const disposeGate = new Promise(resolve => { openGate = resolve; });
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId, disconnectBrowser, events } = await reviewRuntimeHarness({ failPrivateCreate: true, disposeGate,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const settled = runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: new AbortController().signal, progress: async () => {} }).catch(error => error);
while (!events.includes('private:dispose')) await new Promise(resolve => setImmediate(resolve));
disconnectBrowser();
await assert.rejects(runtime.inspect({ sessionId }), /browser disconnected/);
const fresh = await runtime.create({ recipe: FRESH_RECIPE });
openGate();
assert.match((await settled).message, /Injected private create failure/);
assert.equal((await runtime.capabilities()).phase, 'ready');
assert.equal((await runtime.apply({ sessionId: fresh.sessionId })).revision, 1);
} finally { openGate(); await runtime.close(); }
});
runTest('runJob starts the render clock once, after the page handoff has finished (#1256)', async () => {
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId } = await reviewRuntimeHarness({ suspendDelayMs: 60, failPrivateCreate: true,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } } });
try {
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const startedAt = performance.now();
const clockCalls = [];
await assert.rejects(runJob({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: new AbortController().signal, progress: async () => {},
startRenderClock: () => clockCalls.push(performance.now() - startedAt) }), /Injected private create failure/);
assert.equal(clockCalls.length, 1);
assert.ok(clockCalls[0] >= 55, `the clock started ${clockCalls[0]} ms in, before the 60 ms handoff ended`);
} finally { await runtime.close(); }
});
runTest('private disposal failure still closes its page before restoring source', async () => {
const { runtime, sessionId, events } = await reviewRuntimeHarness({ failDispose: true });
try {
await assert.rejects(runtime.review({ sessionId, expectedRevision: 0, shots: [{}] }), /disposal failure/);
assert.ok(events.indexOf('private:close') < events.indexOf('source:resume'));
assert.equal((await runtime.capabilities()).phase, 'ready');
} finally { await runtime.close(); }
});
runTest('review stale revisions and strict runtime fields reject before leasing source', async () => {
const { runtime, sessionId, events } = await reviewRuntimeHarness();
try {
await assert.rejects(runtime.review({ sessionId, expectedRevision: 1, shots: [{}] }), /Stale/);
await assert.rejects(runtime.review({ sessionId, expectedRevision: 0, shots: [{ url: 'https://example.com' }] }), /Review shot field not accepted: url/);
assert.ok(!events.includes('source:suspend'));
assert.equal((await runtime.apply({ sessionId })).revision, 1);
} finally { await runtime.close(); }
});
runTest('runtime close promptly aborts a pending private review and skips source resume', async () => {
const { runtime, sessionId, events, shotStarted } = await reviewRuntimeHarness({ blockShot: true });
const pending = runtime.review({ sessionId, expectedRevision: 0, shots: [{}] });
const rejected = assert.rejects(pending, /closed/);
await startedOrFailed(shotStarted, pending);
assert.equal((await runtime.capabilities()).phase, 'reviewing');
await runtime.close();
await rejected;
assert.ok(events.includes('private:close'));
assert.ok(events.includes('browser:close'));
assert.ok(!events.includes('source:resume'));
assert.equal((await runtime.capabilities()).phase, 'closed');
});
runTest('invalid preview configuration rejects before any browser or renderer allocation', () => {
assert.throws(() => createAgentRuntime({ backend: 'fake' }), /backend/);
for (const memory of [0, 31, 385, 1024, 64.5, NaN]) {
assert.throws(() => createAgentRuntime({ memory, totalMemoryBytes: 512 * 1024 ** 2 }), /memory/);
}
assert.throws(() => createAgentRuntime({ memory: 2049, totalMemoryBytes: 4 * 1024 ** 3 }), /from 32 to 2048 MiB on this machine/);
assert.throws(() => createAgentRuntime({ browser: 'does-not-exist-browser.exe' }), /browser/);
assert.throws(() => createAgentRuntime({ assets: 'relative-path' }), /absolute/);
});
runTest('requests cannot address an absent session or enter a closing runtime', async () => {
const runtime = createAgentRuntime();
await assert.rejects(runtime.inspect({ sessionId: 'missing' }), /Unknown|No scene is active/);
await assert.rejects(runtime.look({ sessionId: 'missing' }), /Unknown|No scene is active/);
const closing = runtime.close();
await assert.rejects(runtime.checkpoint({ sessionId: 'missing' }), /closing|closed/);
await closing;
});
runTest('runtime close settles a pending scene_ask_user at once and stops its page server (#1246)', async () => {
let sessionSignal;
const waitForSignal = async ({ signal }) => {
sessionSignal = signal;
return new Promise(resolve => signal.addEventListener('abort', () => resolve({ outcome: 'aborted' }), { once: true }));
};
const { runtime, sessionId } = await reviewRuntimeHarness({ contextOverrides: { runAnnotateSession: waitForSignal } });
const asking = runtime.askUser({ sessionId, timeoutSeconds: 600 });
const askingOutcome = asking.then(() => 'resolved', error => error.message);
while (!sessionSignal) await new Promise(resolve => setTimeout(resolve, 5));
const started = performance.now();
await runtime.close();
assert.match(await askingOutcome, /closed|closing/);
assert.ok(sessionSignal.aborted);
assert.ok(performance.now() - started < 3000);
});
runTest('a scene_ask_user fixture answers without a browser, in the same shape as the browser answer, and unset changes nothing (#1956)', async () => {
const fixtureMarks = [{ x: 384, y: 256, note: 'make this red' }, { x: 40, y: 60, note: 'and this' }];
let browserSessions = 0;
const browserAnswer = async () => {
browserSessions++;
return { outcome: 'sent', marks: fixtureMarks, image: ANNOTATE_PNG };
};
const browser = await reviewRuntimeHarness({ contextOverrides: { runAnnotateSession: browserAnswer } });
const fromBrowser = await browser.runtime.askUser({ sessionId: browser.sessionId });
assert.equal(browserSessions, 1, 'without the fixture the browser flow runs');
const fixture = await reviewRuntimeHarness({
runtimeOptions: { askUserFixture: { name: 'pin.json', marks: fixtureMarks } },
contextOverrides: { runAnnotateSession: browserAnswer } });
const fromFixture = await fixture.runtime.askUser({ sessionId: fixture.sessionId });
assert.equal(browserSessions, 1, 'with the fixture no browser session opens');
assert.equal(fromFixture.content.outcome, 'sent');
assert.equal(fromFixture.content.marks[0].note, 'make this red');
assert.equal(fromFixture.content.marks[0].partId, 'lamp');
assert.equal(fromFixture.content.marks[1].partId, null);
assert.equal(typeof fromFixture.image, 'string');
assert.deepEqual(Object.keys(fromFixture), Object.keys(fromBrowser));
// The runtime runs in a vm, so compare the JSON the tool sends, as the MCP server does.
const asSent = answer => JSON.parse(JSON.stringify(answer.content));
assert.deepEqual(asSent(fromFixture), { ...asSent(fromBrowser), sessionId: fixture.sessionId });
const inline = await fixture.runtime.askUser({ sessionId: fixture.sessionId, inline: true });
assert.equal(inline.content.outcome, 'sent', 'an inline ask is answered by the fixture too');
await assert.rejects(fixture.runtime.askUser({ sessionId: fixture.sessionId, maxMarks: 1 }), /at most 1 marks/);
});
runTest('a lasso mark resolves to the parts under its outline, through the same pick as a pin, and a lasso over sky has none (#922)', async () => {
const wholeView = [[0, 0], [768, 0], [768, 512], [0, 512]];
const skyCorner = [[10, 10], [60, 10], [60, 100], [10, 100]];
const fixture = await reviewRuntimeHarness({
runtimeOptions: { askUserFixture: { name: 'lasso.json', marks: [
{ kind: 'lasso', points: wholeView, note: 'make these blue' }, { kind: 'lasso', points: skyCorner, note: 'nothing here' }, { x: 384, y: 256, note: 'a pin' }] } } });
const answer = JSON.parse(JSON.stringify((await fixture.runtime.askUser({ sessionId: fixture.sessionId })).content));
const [whole, corner, pin] = answer.marks;
assert.equal(whole.kind, 'lasso');
assert.deepEqual(whole.points, wholeView);
assert.equal(whole.note, 'make these blue');
assert.equal(whole.partId, 'lamp');
assert.deepEqual(whole.parts.map(part => part.partId), ['lamp']);
assert.ok(whole.parts[0].coverage > 0.5 && whole.parts[0].coverage < 1, 'the left of the view is sky, so the lamp covers only part of the outline');
assert.equal(whole.parts[0].material, 'brass');
assert.equal(corner.partId, null);
assert.deepEqual(corner.parts, []);
assert.equal('kind' in pin, false, 'a pin keeps its old shape');
assert.equal(pin.partId, 'lamp');
const pickCall = fixture.sourceCalls.find(call => call.method === 'pickMarks');
assert.equal(pickCall.input.marks[0].kind, 'lasso', 'the lasso reaches the page as an outline, not as a pixel');
});
runTest('an inline scene_ask_user hands its nonce to the view only and resolves marks once (#923)', async () => {
let browserSessions = 0;
const { runtime, sessionId } = await reviewRuntimeHarness({ contextOverrides: { runAnnotateSession: async () => { browserSessions++; return { outcome: 'timeout' }; } } });
const png = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47]), Buffer.alloc(16)]).toString('base64');
const pending = await runtime.askUser({ sessionId, inline: true, prompt: 'Pin it' });
assert.equal(browserSessions, 0, 'an inline ask opens no browser page');
assert.equal(pending.content.outcome, 'pending');
assert.equal(pending.content.prompt, 'Pin it');
const { nonce } = pending.viewMeta;
assert.match(nonce, /^[a-f0-9]{32}$/);
assert.ok(!JSON.stringify(pending.content).includes(nonce), 'the nonce is not in what the model reads');
assert.deepEqual([pending.content.view.width, pending.content.view.height], [768, 512]);
assert.ok(pending.image);
await assert.rejects(runtime.submitAskUser({ nonce: 'f'.repeat(32), marks: [{ x: 5, y: 5 }], image: png }), /only accepts the marks of an open annotate view/);
await assert.rejects(runtime.submitAskUser({ nonce, marks: [{ x: 5000, y: 5, note: 'outside' }], image: png }), /x must be a pixel from 0 to 768/);
await assert.rejects(runtime.submitAskUser({ nonce, marks: [], image: png }), /at least one pin/);
await assert.rejects(runtime.submitAskUser({ nonce, marks: [{ x: 5, y: 5, note: 'dull' }], image: 'not a png' }), /PNG/);
const sent = await runtime.submitAskUser({ nonce, marks: [{ x: 384, y: 256, note: ' dull ' }], image: png });
assert.equal(sent.content.outcome, 'sent');
assert.equal(sent.content.marks[0].partId, 'lamp');
assert.equal(sent.content.marks[0].note, 'dull');
assert.equal(sent.image, png);
assert.deepEqual(Object.keys(sent.content).sort(), ['marks', 'outcome', 'revision', 'sessionId', 'view']);
await assert.rejects(runtime.submitAskUser({ nonce, marks: [{ x: 5, y: 5 }], image: png }), /only accepts the marks of an open annotate view/);
await runtime.close();
});
runTest('scene_ask_user draws the view at motionTime, names it in the answer and puts the scene back there to pick the marks (#922)', async () => {
const { runtime, sessionId, sourceCalls } = await reviewRuntimeHarness({ contextOverrides: { runAnnotateSession: async () => ({ outcome: 'sent', image: ANNOTATE_PNG, marks: [{ x: 384, y: 256, note: 'too bright now' }] }) } });
const sent = await runtime.askUser({ sessionId, motionTime: 2.5 });
assert.equal(sourceCalls.find(call => call.method === 'annotateFrame').input.motionTime, 2.5);
assert.equal(sourceCalls.find(call => call.method === 'pickMarks').input.motionTime, 2.5);
assert.equal(sent.content.view.motionTime, 2.5);
assert.equal(sent.content.marks[0].partId, 'lamp');
const still = await runtime.askUser({ sessionId });
assert.equal('motionTime' in still.content.view, false, 'a view with no time leaves the field out');
assert.equal('motionTime' in sourceCalls.filter(call => call.method === 'pickMarks').at(-1).input, false);
await runtime.close();
});
runTest('an inline ask times out, and dispose and close forget it (#923)', async () => {
const png = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47]), Buffer.alloc(16)]).toString('base64');
const { runtime, sessionId } = await reviewRuntimeHarness();
const expired = await runtime.askUser({ sessionId, inline: true, timeoutSeconds: 0.05 });
await new Promise(resolve => setTimeout(resolve, 80));
await assert.rejects(runtime.submitAskUser({ nonce: expired.viewMeta.nonce, marks: [{ x: 5, y: 5 }], image: png }), /timed out before the marks were sent/);
const disposed = await runtime.askUser({ sessionId, inline: true });
await runtime.dispose({ sessionId });
await assert.rejects(runtime.submitAskUser({ nonce: disposed.viewMeta.nonce, marks: [{ x: 5, y: 5 }], image: png }), /only accepts the marks of an open annotate view/);
const { runtime: otherRuntime, sessionId: otherSession } = await reviewRuntimeHarness();
const open = await otherRuntime.askUser({ sessionId: otherSession, inline: true });
await otherRuntime.close();
await assert.rejects(otherRuntime.submitAskUser({ nonce: open.viewMeta.nonce, marks: [{ x: 5, y: 5 }], image: png }), /only accepts the marks of an open annotate view/);
await runtime.close();
});
runTest('a failed browser launch leaves the runtime idle so the next call retries (#1246)', async () => {
const runtime = createAgentRuntime({ backend: 'cpu', memory: 64, browser: process.execPath });
after(() => runtime.close());
const first = await runtime.create({ recipe: {} }).then(() => undefined, error => error.message);
assert.ok(first, 'a node executable is not a browser, so the first launch must fail');
assert.equal((await runtime.capabilities()).phase, 'idle');
const second = await runtime.create({ recipe: {} }).then(() => undefined, error => error.message);
assert.ok(second);
assert.doesNotMatch(second, /The agent runtime is failed/);
});
runTest('a recipe over the combined asset limit is refused from file sizes before any grid file is read (#1246)', async () => {
const gridDirectory = await mkdtemp(join(tmpdir(), 'crucible-grid-limit-'));
const previousDirectory = process.env.JS67_GRID_DIRECTORY;
process.env.JS67_GRID_DIRECTORY = gridDirectory;
after(async () => {
if (previousDirectory === undefined) delete process.env.JS67_GRID_DIRECTORY;
else process.env.JS67_GRID_DIRECTORY = previousDirectory;
await rm(gridDirectory, { recursive: true, force: true });
});
const frameBytes = 40 * 1024 * 1024;
for (const name of ['first.67vg', 'second.67vg']) {
await writeFile(join(gridDirectory, name), '');
await truncate(join(gridDirectory, name), frameBytes);
}
let gridReads = 0;
const countingRead = (...argumentsList) => {
gridReads++;
return readVolumeGridFiles(...argumentsList);
};
const { runtime } = await reviewRuntimeHarness({ contextOverrides: { readVolumeGridFiles: countingRead } });
gridReads = 0;
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [],
environment: { localVolumes: [{ shape: 'grid', frames: ['first.67vg', 'second.67vg'] }] } };
await assert.rejects(runtime.create({ recipe }), error => error instanceof RangeError
&& error.message.includes('maxCombinedBytes') && error.message.includes(String(2 * frameBytes)));
assert.equal(gridReads, 0);
});
// A catalog that reports sizes and counts how often a file is read, so a test can prove a call was refused before any read.
function countingCatalog(sizeByAssetId) {
const counts = { sizeCalls: 0, reads: 0 };
const catalog = {
counts,
list: () => ({ assets: [] }),
size: async assetId => {
counts.sizeCalls++;
return sizeByAssetId[assetId];
},
read: async () => {
counts.reads++;
return Buffer.alloc(0);
},
};
return catalog;
}
const catalogAssetIds = ['a', 'b', 'c'].map(letter => letter.repeat(64));
async function catalogLimitHarness(sizeEach, exportedRecipe) {
const catalog = countingCatalog(Object.fromEntries(catalogAssetIds.map(assetId => [assetId, sizeEach])));
const harness = await reviewRuntimeHarness({
exportedRecipe,
runtimeOptions: { assets: join(tmpdir(), 'crucible-counting-catalog') },
contextOverrides: { createAgentAssetCatalog: async () => catalog },
});
catalog.counts.sizeCalls = 0;
return { ...harness, catalog };
}
function refusedAtTotal(total) {
return error => error instanceof RangeError && error.message.includes('maxCombinedBytes') && error.message.includes(String(total));
}
runTest('placed catalog assets over the combined limit are refused from sizes before any read (#1246)', async () => {
const sizeEach = 30 * 1024 * 1024;
const { runtime, catalog } = await catalogLimitHarness(sizeEach);
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [],
nodes: catalogAssetIds.map((assetId, index) => ({ id: `placed-${index}`, asset: { id: assetId } })) };
await assert.rejects(runtime.create({ recipe }), refusedAtTotal(3 * sizeEach));
assert.equal(catalog.counts.sizeCalls, 3);
assert.equal(catalog.counts.reads, 0);
});
runTest('map sequence frames over the combined limit are refused from sizes before any read (#1246)', async () => {
const sizeEach = 40 * 1024 * 1024;
const { runtime, catalog } = await catalogLimitHarness(sizeEach);
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], nodes: [],
materials: [{ id: 'screen', map: { sequence: { frames: catalogAssetIds.slice(0, 2), fps: 24 } } }] };
await assert.rejects(runtime.create({ recipe }), refusedAtTotal(2 * sizeEach));
assert.equal(catalog.counts.reads, 0);
});
runTest('motion source assets count in the sum before a scene_apply reads them (#1246)', async () => {
const sizeEach = 30 * 1024 * 1024;
const { runtime, sessionId, catalog } = await catalogLimitHarness(sizeEach);
const motion = { layers: catalogAssetIds.map(assetId => ({ from: { asset: assetId } })) };
await assert.rejects(runtime.apply({ sessionId, operations: [{ type: 'set-motion', motion }] }), refusedAtTotal(3 * sizeEach));
assert.equal(catalog.counts.reads, 0);
});
// A scene that already holds assets: scene_apply add-node must count them with the new ones, since a render job loads the whole scene at once (#1771).
function sceneHolding(...assetIds) {
return { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [],
nodes: assetIds.map((assetId, index) => ({ id: `held-${index}`, asset: { id: assetId } })) };
}
function addNodes(assetId, count) {
return Array.from({ length: count }, (_, index) => ({ type: 'add-node', node: { id: `added-${index}`, asset: { id: assetId } } }));
}
runTest('scene_apply refuses an add-node that pushes the scene past the combined limit (#1771)', async () => {
const sizeEach = 30 * 1024 * 1024;
const { runtime, sessionId, catalog, events } = await catalogLimitHarness(sizeEach, sceneHolding(catalogAssetIds[0], catalogAssetIds[1]));
await assert.rejects(runtime.apply({ sessionId, operations: addNodes(catalogAssetIds[2], 1) }), error => refusedAtTotal(3 * sizeEach)(error)
&& error.message.includes('scene'));
assert.equal(catalog.counts.reads, 0);
assert.equal(events.includes('source:apply'), false, 'the preview page never receives the refused edit');
});
runTest('scene_apply accepts an add-node while the scene stays under the combined limit (#1771)', async () => {
const sizeEach = 30 * 1024 * 1024;
const { runtime, sessionId, events } = await catalogLimitHarness(sizeEach, sceneHolding(catalogAssetIds[0]));
await runtime.apply({ sessionId, operations: addNodes(catalogAssetIds[1], 1) });
assert.ok(events.includes('source:apply'));
});
runTest('one asset placed many times counts once in the scene total (#1771)', async () => {
const sizeEach = 30 * 1024 * 1024;
const { runtime, sessionId, events } = await catalogLimitHarness(sizeEach, sceneHolding(catalogAssetIds[0], catalogAssetIds[1]));
await runtime.apply({ sessionId, operations: addNodes(catalogAssetIds[0], 7) });
assert.ok(events.includes('source:apply'));
});
runTest('grid files the scene already holds count toward the combined limit in scene_apply (#1848)', async () => {
const gridDirectory = await mkdtemp(join(tmpdir(), 'crucible-scene-grid-'));
const previousDirectory = process.env.JS67_GRID_DIRECTORY;
process.env.JS67_GRID_DIRECTORY = gridDirectory;
after(async () => {
if (previousDirectory === undefined) delete process.env.JS67_GRID_DIRECTORY;
else process.env.JS67_GRID_DIRECTORY = previousDirectory;
await rm(gridDirectory, { recursive: true, force: true });
});
const gridBytes = 40 * 1024 * 1024;
await writeFile(join(gridDirectory, 'held.67vg'), '');
await truncate(join(gridDirectory, 'held.67vg'), gridBytes);
const sceneWithGrid = { ...sceneHolding(), environment: { localVolumes: [{ shape: 'grid', grid: 'held.67vg' }] } };
const sizeEach = 30 * 1024 * 1024;
const { runtime, sessionId, events } = await catalogLimitHarness(sizeEach, sceneWithGrid);
await assert.rejects(runtime.apply({ sessionId, operations: addNodes(catalogAssetIds[0], 1) }), refusedAtTotal(gridBytes + sizeEach));
assert.equal(events.includes('source:apply'), false);
});
// A scene over the cap reaches a render job through an export or an older edit. The job must refuse it before the scene page is
// suspended, because recovery would reload every asset into the page and crash it (#1848).
async function overCapJobHarness() {
const sizeEach = 30 * 1024 * 1024;
const catalog = countingCatalog(Object.fromEntries(catalogAssetIds.map(assetId => [assetId, sizeEach])));
let runJob;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const harness = await reviewRuntimeHarness({
runtimeOptions: { assets: join(tmpdir(), 'crucible-counting-catalog'), jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentAssetCatalog: async () => catalog, createAgentRenderJobs: async ({ run }) => { runJob = run; return controller; } },
});
await harness.runtime.submitJob({ sessionId: harness.sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
const runOverCapJob = () => runJob({ jobId: randomUUID(), sessionId: harness.sessionId, directory: tmpdir(),
snapshot: { recipe: sceneHolding(...catalogAssetIds) }, settings: { kind: 'image', width: 64, height: 64 },
signal: new AbortController().signal, progress: async () => {} });
return { ...harness, catalog, runOverCapJob, sizeEach };
}
runTest('a render job of a scene over the combined limit fails with the cap message and leaves the scene page alone (#1848)', async () => {
const { runtime, events, catalog, runOverCapJob, sizeEach } = await overCapJobHarness();
try {
await assert.rejects(runOverCapJob(), error => refusedAtTotal(3 * sizeEach)(error) && error.message.includes('scene'));
assert.equal(events.includes('source:suspend'), false, 'the scene page keeps its renderer');
assert.equal(events.includes('source:resume'), false, 'no recovery reload of the over-cap scene');
assert.equal(catalog.counts.reads, 0);
assert.equal((await runtime.capabilities()).phase, 'ready');
} finally { await runtime.close(); }
});
// A recipe that names a catalog file instead of its SHA-256 id (#1843): the id changes on every re-export, the name does not.
async function namedAssetHarness(context) {
const directory = await mkdtemp(join(tmpdir(), 'crucible-named-assets-'));
context.after(() => rm(directory, { recursive: true, force: true }));
await cp(new URL('./fixtures/kenney-boat/', import.meta.url), directory, { recursive: true });
await writeFile(join(directory, 'sheep_body.glb'), withDistinctDocument(await readFile(join(directory, 'boat-fishing-small.glb')), 'sheep'));
const realCatalog = await createAgentAssetCatalog(directory);
const sheepId = realCatalog.list().assets.find(asset => asset.name === 'sheep_body.glb').assetId;
const readIds = [];
const recordingCatalog = {
list: () => realCatalog.list(),
size: assetId => realCatalog.size(assetId),
resolveName: name => realCatalog.resolveName(name),
read: assetId => {
readIds.push(assetId);
return realCatalog.read(assetId);
},
};
const harness = await reviewRuntimeHarness({
runtimeOptions: { assets: directory },
contextOverrides: { createAgentAssetCatalog: async () => recordingCatalog },
});
return { ...harness, sheepId, readIds };
}
function recipePlacing(placement) {
return { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [{ id: 'sheep0-body', asset: placement }] };
}
runTest('scene_create places a catalog GLB by file name and keeps only its hash (#1843)', async context => {
const { runtime, sourceCalls, sheepId, readIds } = await namedAssetHarness(context);
await runtime.create({ recipe: recipePlacing({ name: 'sheep_body.glb' }) });
const createCall = sourceCalls.filter(call => call.method === 'create').at(-1);
assert.deepEqual(createCall.input.recipe.nodes[0].asset, { id: sheepId });
assert.deepEqual(readIds, [sheepId]);
});
runTest('scene_apply add-node places a catalog GLB by file name (#1843)', async context => {
const { runtime, sessionId, sourceCalls, sheepId } = await namedAssetHarness(context);
await runtime.apply({ sessionId, operations: [{ type: 'add-node', node: { id: 'sheep1-body', asset: { name: 'sheep_body.glb' } } }] });
const applyCall = sourceCalls.filter(call => call.method === 'apply').at(-1);
assert.deepEqual(applyCall.input.operations[0].node.asset, { id: sheepId });
});
runTest('an unknown asset name is refused with near names and the catalog tool to run (#1843)', async context => {
const { runtime } = await namedAssetHarness(context);
await assert.rejects(runtime.create({ recipe: recipePlacing({ name: 'sheep_body' }) }), /No catalog GLB is named "sheep_body".*"sheep_body\.glb"/);
await assert.rejects(runtime.create({ recipe: recipePlacing({ name: 'wolf.glb' }) }), /Run scene_asset_catalog/);
});
runTest('an asset placement with both id and name is refused (#1843)', async context => {
const { runtime, sheepId } = await namedAssetHarness(context);
await assert.rejects(runtime.create({ recipe: recipePlacing({ id: sheepId, name: 'sheep_body.glb' }) }), /exactly one of id .* or name/);
});
runTest('scene_create_asset opens a catalog GLB by assetName and refuses assetName with assetId (#1843)', async context => {
const { runtime, sourceCalls, sheepId } = await namedAssetHarness(context);
const assetRecipe = { format: 'crucible.asset', schemaVersion: 1 };
await runtime.createAsset({ recipe: { ...assetRecipe, assetName: 'sheep_body.glb' } });
const createCall = sourceCalls.filter(call => call.method === 'createAsset').at(-1);
assert.equal(createCall.input.recipe.assetId, sheepId);
assert.equal(createCall.input.recipe.assetName, undefined);
await assert.rejects(runtime.createAsset({ recipe: { ...assetRecipe, assetId: sheepId, assetName: 'sheep_body.glb' } }), /exactly one of recipe\.assetId/);
});
// Files that arrive or leave the --assets folder after the server started (#2209).
async function rescanHarness(context) {
const directory = await mkdtemp(join(tmpdir(), 'crucible-rescan-assets-'));
context.after(() => rm(directory, { recursive: true, force: true }));
await cp(new URL('./fixtures/kenney-boat/', import.meta.url), directory, { recursive: true });
const boatBytes = await readFile(join(directory, 'boat-fishing-small.glb'));
await rm(join(directory, 'boat-fishing-small.glb'));
await writeFile(join(directory, 'first.glb'), boatBytes);
const harness = await reviewRuntimeHarness({ runtimeOptions: { assets: directory } });
const addGlb = (name, marker) => writeFile(join(directory, name), withDistinctDocument(boatBytes, marker));
return { ...harness, directory, addGlb };
}
function radianceFile() {
return Buffer.concat([Buffer.from('#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 2 +X 4\n'), Buffer.alloc(2 * 4 * 4, 128)]);
}
const listedNames = async runtime => (await runtime.assetCatalog()).assets.map(asset => asset.name);
runTest('a GLB and an HDRI copied into --assets after start are listed by the next catalog call and placed by name (#2209)', async context => {
const { runtime, sessionId, sourceCalls, directory, addGlb } = await rescanHarness(context);
assert.deepEqual(await listedNames(runtime), ['first.glb']);
await addGlb('downloaded.glb', 'downloaded');
await writeFile(join(directory, 'sky.hdr'), radianceFile());
const listing = await runtime.assetCatalog();
assert.deepEqual(listing.assets.map(asset => asset.name).sort(), ['downloaded.glb', 'first.glb', 'sky.hdr']);
const downloadedId = listing.assets.find(asset => asset.name === 'downloaded.glb').assetId;
await runtime.apply({ sessionId, operations: [{ type: 'add-node', node: { id: 'new-boat', asset: { name: 'downloaded.glb' } } }] });
assert.deepEqual(sourceCalls.filter(call => call.method === 'apply').at(-1).input.operations[0].node.asset, { id: downloadedId });
});
runTest('an asset name that appeared since the last catalog call is found without listing the catalog first (#2209)', async context => {
const { runtime, sessionId, sourceCalls, addGlb } = await rescanHarness(context);
await listedNames(runtime);
await addGlb('late.glb', 'late');
await runtime.apply({ sessionId, operations: [{ type: 'add-node', node: { id: 'late-boat', asset: { name: 'late.glb' } } }] });
assert.equal(sourceCalls.filter(call => call.method === 'apply').at(-1).input.operations[0].node.asset.id.length, 64);
});
runTest('a file removed from --assets leaves the catalog and a rewritten file gets its new id (#2209)', async context => {
const { runtime, directory, addGlb } = await rescanHarness(context);
await addGlb('temporary.glb', 'one');
const before = (await runtime.assetCatalog()).assets.find(asset => asset.name === 'temporary.glb').assetId;
await addGlb('temporary.glb', 'two');
const after = (await runtime.assetCatalog()).assets.find(asset => asset.name === 'temporary.glb').assetId;
assert.notEqual(after, before);
await rm(join(directory, 'temporary.glb'));
assert.deepEqual(await listedNames(runtime), ['first.glb']);
});
// The same GLB with one extra field in its JSON chunk, so the catalog gives it another asset id.
function withDistinctDocument(bytes, marker) {
const jsonLength = bytes.readUInt32LE(12);
const document = JSON.parse(bytes.subarray(20, 20 + jsonLength).toString('utf8'));
document.asset = { ...document.asset, extras: { marker } };
const json = Buffer.from(JSON.stringify(document));
const paddedLength = Math.ceil(json.length / 4) * 4;
const binary = bytes.subarray(20 + jsonLength);
const result = Buffer.alloc(20 + paddedLength + binary.length, 32);
bytes.copy(result, 0, 0, 20);
result.writeUInt32LE(result.length, 8);
result.writeUInt32LE(paddedLength, 12);
json.copy(result, 20);
binary.copy(result, 20 + paddedLength);
return result;
}
runTest('two textured GLBs whose embedded images pass the combined limit are refused by the real catalog (#1282)', async () => {
const directory = await mkdtemp(join(tmpdir(), 'crucible-textured-limit-'));
try {
await cp(new URL('./fixtures/kenney-boat/', import.meta.url), directory, { recursive: true });
const boat = await readFile(join(directory, 'boat-fishing-small.glb'));
const secondBoat = withDistinctDocument(boat, 'second');
await writeFile(join(directory, 'boat-second.glb'), secondBoat);
const sharedImageBytes = Buffer.alloc(34 * 1024 * 1024);
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(sharedImageBytes);
await writeFile(join(directory, 'Textures', 'colormap.png'), sharedImageBytes);
const onDiskTotal = boat.length + secondBoat.length + sharedImageBytes.length;
assert.ok(onDiskTotal < AGENT_ASSET_LIMITS.maxCombinedBytes, 'on disk the files fit, so only the embedded sizes can trip the limit');
const realCatalog = await createAgentAssetCatalog(directory);
let reads = 0;
const countingRealCatalog = {
list: () => realCatalog.list(),
size: assetId => realCatalog.size(assetId),
read: assetId => {
reads++;
return realCatalog.read(assetId);
},
};
const { runtime } = await reviewRuntimeHarness({
runtimeOptions: { assets: directory },
contextOverrides: { createAgentAssetCatalog: async () => countingRealCatalog },
});
const assetIds = realCatalog.list().assets.map(asset => asset.assetId);
assert.equal(assetIds.length, 2);
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [],
nodes: assetIds.map((assetId, index) => ({ id: `boat-${index}`, asset: { id: assetId } })) };
await assert.rejects(runtime.create({ recipe }), error => error instanceof RangeError && error.message.includes('maxCombinedBytes'));
assert.equal(reads, 0, 'the refusal comes from size() before any file is read and base64 encoded');
} finally {
await rm(directory, { recursive: true, force: true });
}
});
runTest('the preview server accepts only its own loopback host', () => {
assert.equal(isPreviewHost('127.0.0.1:4100', 4100), true);
assert.equal(isPreviewHost('evil.example:4100', 4100), false);
assert.equal(isPreviewHost('localhost:4100', 4100), false);
assert.equal(isPreviewHost('127.0.0.1:4101', 4100), false);
assert.equal(isPreviewHost(undefined, 4100), false);
});
async function webExportHarness({ exportedRecipe, failCopy = () => false, seedJobsDirectory, extraOverrides = {} } = {}) {
const root = await mkdtemp(join(tmpdir(), 'crucible-web-runtime-'));
const buildDirectory = join(root, 'build');
await mkdir(join(buildDirectory, 'mcp'), { recursive: true });
await writeFile(join(buildDirectory, 'game.js'), 'export {};');
const jobsDirectory = join(root, 'jobs');
await mkdir(jobsDirectory);
await seedJobsDirectory?.(jobsDirectory);
const failingWriteWebBuild = async options => {
if (failCopy()) {
await mkdir(join(options.outputDirectory, 'engine'), { recursive: true });
throw new Error('Injected copy failure');
}
return writeWebBuild(options);
};
const harness = await reviewRuntimeHarness({
exportedRecipe,
runtimeOptions: { jobs: jobsDirectory, previewUrl: pathToFileURL(join(buildDirectory, 'mcp', 'preview.js')) },
contextOverrides: { writeWebBuild: failingWriteWebBuild, ...extraOverrides },
});
const keptBuilds = async () => (await readdir(join(jobsDirectory, EXPORT_DIRECTORY_NAME))).filter(name => name.startsWith('web-'));
after(() => harness.runtime.close());
return { ...harness, keptBuilds };
}
const PLAYABLE_RECIPE = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], game: { player: { node: 'creature' }, physics: false } };
runTest('exportWeb keeps only the newest four builds and returns a real entry page', async () => {
const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });
const entries = [];
for (let index = 0; index < 5; index++) entries.push((await runtime.exportWeb({ sessionId })).entry);
assert.equal((await keptBuilds()).length, 4);
await assert.rejects(stat(entries[0]), { code: 'ENOENT' });
for (const entry of entries.slice(1)) assert.ok((await stat(entry)).isFile());
});
// Files and folders an earlier server run left in the exports folder, oldest first (modified one minute apart).
async function leaveEarlierExports(jobsDirectory, { glbCount, webBuildCount }) {
const exportsDirectory = join(jobsDirectory, EXPORT_DIRECTORY_NAME);
await mkdir(exportsDirectory);
const names = [
...Array.from({ length: glbCount }, () => `${randomUUID()}.glb`),
...Array.from({ length: webBuildCount }, () => `web-${randomUUID()}`),
];
const start = Date.now() / 1000 - 3600;
for (const [index, name] of names.entries()) {
const path = join(exportsDirectory, name);
if (name.startsWith('web-')) await mkdir(path);
else await writeFile(path, 'earlier glb');
await utimes(path, start + index * 60, start + index * 60);
}
return names.map(name => join(exportsDirectory, name));
}
runTest('exports left by an earlier run count toward the newest four web builds and eight GLBs (#1246)', async () => {
let earlier;
const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE,
seedJobsDirectory: async directory => { earlier = await leaveEarlierExports(directory, { glbCount: 8, webBuildCount: 4 }); } });
const glbEarlier = earlier.filter(path => path.endsWith('.glb'));
const webEarlier = earlier.filter(path => !path.endsWith('.glb'));
await runtime.exportWeb({ sessionId });
assert.equal((await keptBuilds()).length, 4);
await assert.rejects(stat(webEarlier[0]), { code: 'ENOENT' });
assert.ok((await stat(webEarlier[1])).isDirectory());
await runtime.exportGlb({ sessionId });
const keptGlbs = (await readdir(join(dirname(webEarlier[0])))).filter(name => name.endsWith('.glb'));
assert.equal(keptGlbs.length, 8);
await assert.rejects(stat(glbEarlier[0]), { code: 'ENOENT' });
assert.ok((await stat(glbEarlier[1])).isFile());
});
runTest('a half-written web export is removed and never evicts or uses up a kept build', async () => {
let breakCopy = false;
const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE, failCopy: () => breakCopy });
const goodEntries = [];
for (let index = 0; index < 4; index++) goodEntries.push((await runtime.exportWeb({ sessionId })).entry);
breakCopy = true;
for (let attempt = 0; attempt < 5; attempt++) await assert.rejects(runtime.exportWeb({ sessionId }), /Injected copy failure/);
assert.equal((await keptBuilds()).length, 4);
for (const entry of goodEntries) assert.ok((await stat(entry)).isFile());
});
runTest('exportWeb refuses a scene without a game or with physics, and earlier builds stay', async () => {
const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });
await runtime.exportWeb({ sessionId });
const refused = [
[{ ...PLAYABLE_RECIPE, game: undefined }, /no game/],
[{ ...PLAYABLE_RECIPE, game: { ...PLAYABLE_RECIPE.game, physics: true } }, /game\.physics is true/],
];
for (const [recipe, message] of refused) {
const refusing = await webExportHarness({ exportedRecipe: recipe });
for (let attempt = 0; attempt < 5; attempt++) await assert.rejects(refusing.runtime.exportWeb({ sessionId: refusing.sessionId }), message);
assert.equal((await refusing.keptBuilds().catch(() => [])).length, 0);
}
assert.equal((await keptBuilds()).length, 1);
});
runTest('exportWeb needs a jobs folder', async () => {
const harness = await reviewRuntimeHarness({ exportedRecipe: PLAYABLE_RECIPE });
after(() => harness.runtime.close());
await assert.rejects(harness.runtime.exportWeb({ sessionId: harness.sessionId }), /--jobs/);
});
// A queue that grants one unit at a time and records every request, grant and release, like a wrapper that never runs light
// beside heavy. The runtime must work with it without ever queueing against itself.
function recordingSerialQueue() {
const log = [];
let tail = Promise.resolve();
return {
log,
run(weight, work, { signal } = {}) {
log.push(`request:${weight}`);
const result = tail.then(async () => {
signal?.throwIfAborted();
log.push(`grant:${weight}`);
try { return await work(); } finally { log.push(`release:${weight}`); }
});
tail = result.catch(() => {});
return result;
},
};
}
const settleQueue = () => new Promise(resolve => setTimeout(resolve, 20));
runTest('look and review take the card as light and give it back; calls that draw nothing never ask the queue', async () => {
const queue = recordingSerialQueue();
const { runtime, sessionId } = await reviewRuntimeHarness({ runtimeOptions: { gpuQueue: queue } });
assert.deepEqual(queue.log, []);
await runtime.look({ sessionId });
await settleQueue();
assert.deepEqual(queue.log, ['request:light', 'grant:light', 'release:light']);
queue.log.length = 0;
await runtime.review({ sessionId, expectedRevision: 0, shots: [{}] });
await settleQueue();
assert.deepEqual(queue.log, ['request:light', 'grant:light', 'release:light']);
queue.log.length = 0;
await runtime.apply({ sessionId });
await runtime.exportRecipe({ sessionId });
await settleQueue();
assert.deepEqual(queue.log, []);
});
runTest('a failed look gives the card back', async () => {
const queue = recordingSerialQueue();
const { runtime } = await reviewRuntimeHarness({ runtimeOptions: { gpuQueue: queue } });
await assert.rejects(runtime.look({ sessionId: randomUUID() }));
await settleQueue();
assert.deepEqual(queue.log, ['request:light', 'grant:light', 'release:light']);
});
runTest('creating a baked scene and editing a baked scene take the card as heavy, other edits do not', async () => {
const queue = recordingSerialQueue();
const { runtime, sessionId } = await reviewRuntimeHarness({ runtimeOptions: { gpuQueue: queue } });
const bakedRecipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], bake: { quality: 'draft' } };
const baked = await runtime.create({ recipe: bakedRecipe });
await settleQueue();
assert.deepEqual(queue.log, ['request:heavy', 'grant:heavy', 'release:heavy']);
queue.log.length = 0;
await runtime.apply({ sessionId: baked.sessionId, operations: [] });
await settleQueue();
assert.deepEqual(queue.log, ['request:heavy', 'grant:heavy', 'release:heavy']);
queue.log.length = 0;
await runtime.apply({ sessionId, operations: [] });
await settleQueue();
assert.deepEqual(queue.log, []);
});
runTest('a look while a render job holds the card joins it: both finish with a strictly serial queue and no wait timeout', async () => {
const queue = recordingSerialQueue();
let jobHooks;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId, events } = await reviewRuntimeHarness({ blockPrivateCreate: true,
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test'), gpuQueue: queue },
contextOverrides: { createAgentRenderJobs: async hooks => { jobHooks = hooks; return controller; } } });
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
assert.equal(typeof jobHooks.acquireGpu, 'function');
const jobAbort = new AbortController();
const releaseCard = await jobHooks.acquireGpu(jobAbort.signal);
const jobRun = jobHooks.run({ jobId: randomUUID(), sessionId, directory: tmpdir(), snapshot: { recipe: {} },
settings: { kind: 'image', width: 64, height: 64 }, signal: jobAbort.signal, progress: async () => {} });
jobRun.catch(() => {});
for (let attempt = 0; attempt < 100 && !events.includes('private:create'); attempt++) await new Promise(resolve => setTimeout(resolve, 5));
const started = Date.now();
await runtime.look({ sessionId });
assert.ok(Date.now() - started < 2000);
assert.deepEqual(queue.log, ['request:heavy', 'grant:heavy']);
jobAbort.abort(new Error('Render job cancelled.'));
await assert.rejects(jobRun, /Review page closed/);
releaseCard();
await settleQueue();
assert.deepEqual(queue.log, ['request:heavy', 'grant:heavy', 'release:heavy']);
});
runTest('without --gpu-queue the job store gets no card hook', async () => {
let jobHooks;
const controller = { list: () => [], close: async () => {}, submit: async () => ({ jobId: 'job' }) };
const { runtime, sessionId } = await reviewRuntimeHarness({
runtimeOptions: { jobs: join(tmpdir(), 'crucible-job-root-test') },
contextOverrides: { createAgentRenderJobs: async hooks => { jobHooks = hooks; return controller; } } });
await runtime.submitJob({ sessionId, expectedRevision: 0, settings: { kind: 'image', width: 64, height: 64 } });
assert.equal(jobHooks.acquireGpu, undefined);
});
runTest('a review page export, marks saved in the page and read back equal the local scene_ask_user answer (#924)', async () => {
const { runtime, sessionId } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });
const exported = await runtime.exportWeb({ sessionId, title: 'Kitchen', review: true });
assert.equal(exported.review, true);
assert.ok((await stat(join(dirname(exported.entry), 'frame.png'))).isFile());
const page = openReviewPage(await readFile(exported.entry, 'utf8'));
page.tap(384, 256);
page.tap(40, 60);
page.write(1, 'brass looks dull');
const reviewFile = page.saveFileText();
const fromReview = await runtime.askUser({ sessionId, reviewFile });
const savedMarks = JSON.parse(reviewFile).marks;
const local = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE,
extraOverrides: { runAnnotateSession: async () => ({ outcome: 'sent', marks: savedMarks, image: ANNOTATE_PNG }) } });
const fromLocal = await local.runtime.askUser({ sessionId: local.sessionId });
assert.equal(fromReview.image, undefined);
assert.equal(fromLocal.content.marks.length, 2);
assert.equal(fromLocal.content.marks[1].partId, null);
// The runtime runs in a vm, so compare the JSON the tool sends, as the MCP server does.
assert.deepEqual(JSON.parse(JSON.stringify(fromReview.content)), JSON.parse(JSON.stringify({ ...fromLocal.content, sessionId })));
});
runTest('a review file is refused when it is forged, for another scene, empty or too long (#924)', async () => {
const { runtime, sessionId } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });
const exported = await runtime.exportWeb({ sessionId, review: true });
const page = openReviewPage(await readFile(exported.entry, 'utf8'));
page.tap(100, 100);
const file = JSON.parse(page.saveFileText());
const forged = JSON.stringify({ ...file, reviewId: 'f'.repeat(32) });
await assert.rejects(runtime.askUser({ sessionId, reviewFile: forged }), /Export the review page again/);
await assert.rejects(runtime.askUser({ sessionId: 'other-scene', reviewFile: JSON.stringify(file) }), /Unknown|other-scene|made for scene/);
await assert.rejects(runtime.askUser({ sessionId, reviewFile: JSON.stringify({ ...file, marks: [] }) }), /no marks/);
await assert.rejects(runtime.askUser({ sessionId, reviewFile: JSON.stringify({ ...file, marks: [{ x: 9999, y: 1, note: '' }] }) }), /mark 1 x/);
await assert.rejects(runtime.askUser({ sessionId, reviewFile: 'x'.repeat(20000) }), /over 16384 bytes/);
});
runTest('a review file is read once, is forgotten when its scene is disposed, and keeps the page limit of 16 marks (#924)', async () => {
const { runtime, sessionId } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });
const exported = await runtime.exportWeb({ sessionId, review: true });
const page = openReviewPage(await readFile(exported.entry, 'utf8'));
page.tap(384, 256);
const reviewFile = page.saveFileText();
const file = JSON.parse(reviewFile);
const seventeenMarks = Array.from({ length: 17 }, (unused, index) => ({ x: 10 + index, y: 10, note: '' }));
await assert.rejects(runtime.askUser({ sessionId, reviewFile: JSON.stringify({ ...file, marks: seventeenMarks }), maxMarks: 32 }), /at most 16 marks/);
const first = await runtime.askUser({ sessionId, reviewFile });
assert.equal(first.content.outcome, 'sent');
await assert.rejects(runtime.askUser({ sessionId, reviewFile }), /already read by an earlier scene_ask_user call/);
const second = await runtime.exportWeb({ sessionId, review: true });
const secondFile = openReviewPage(await readFile(second.entry, 'utf8'));
secondFile.tap(384, 256);
const secondText = secondFile.saveFileText();
await runtime.dispose({ sessionId });
await assert.rejects(runtime.askUser({ sessionId, reviewFile: secondText }), /does not match a review page exported by this server run/);
});
runTest('a review page needs no game and is kept with the newest four web builds (#924)', async () => {
const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] } });
const entries = [];
for (let index = 0; index < 5; index++) entries.push((await runtime.exportWeb({ sessionId, review: true })).entry);
assert.equal((await keptBuilds()).length, 4);
await assert.rejects(stat(entries[0]), { code: 'ENOENT' });
});