3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// A test-only stand-in for the person who answers scene_ask_user (#1956). The agent bench runs the real MCP server through
// `claude -p`, and the browser page waits for Send, so a bench task could never finish. Whoever starts the server may set
// CRUCIBLE_ASK_USER_FIXTURE to an absolute path of a small JSON file; scene_ask_user then answers from its marks instead of opening
// a browser. The variable is read once at start, never appears in a tool schema or the flag list, and no tool call can set it.
import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
import { basename, extname, isAbsolute } from 'node:path';
import { ANNOTATE_LIMITS } from '../src/agent-annotate.js';
export const ASK_USER_FIXTURE_VARIABLE = 'CRUCIBLE_ASK_USER_FIXTURE';
export const ASK_USER_FIXTURE_LIMITS = Object.freeze({ maxBytes: 64 * 1024, maxPixel: 1024, maxMotionTime: 3600 });
function fixtureError(detail) {
return new Error(`${ASK_USER_FIXTURE_VARIABLE} ${detail}`);
}
function readFixtureText(filePath) {
if (!isAbsolute(filePath)) throw fixtureError(`must be an absolute path to a .json file, got "${filePath}". Pass the full path.`);
if (extname(filePath).toLowerCase() !== '.json') throw fixtureError(`must point to a .json file, got "${basename(filePath)}". Rename the file or point to another one.`);
let descriptor;
try {
descriptor = openSync(filePath, 'r');
} catch (error) {
throw fixtureError(`cannot read ${basename(filePath)}: ${error.code ?? error.message}. Point it to an existing file.`);
}
// Size check and read go through one open descriptor, so the file cannot be swapped between them.
try {
const size = fstatSync(descriptor).size;
if (size > ASK_USER_FIXTURE_LIMITS.maxBytes) {
throw fixtureError(`file ${basename(filePath)} is ${size} bytes, over the ${ASK_USER_FIXTURE_LIMITS.maxBytes} byte limit. Keep only the marks.`);
}
const buffer = Buffer.alloc(ASK_USER_FIXTURE_LIMITS.maxBytes + 1);
const bytesRead = readSync(descriptor, buffer, 0, buffer.length, 0);
if (bytesRead > ASK_USER_FIXTURE_LIMITS.maxBytes) {
throw fixtureError(`file ${basename(filePath)} grew past the ${ASK_USER_FIXTURE_LIMITS.maxBytes} byte limit while it was read. Keep only the marks.`);
}
return buffer.toString('utf8', 0, bytesRead);
} finally {
closeSync(descriptor);
}
}
function isPixelPair(value) {
return Array.isArray(value) && value.length === 2
&& value.every(coordinate => Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= ASK_USER_FIXTURE_LIMITS.maxPixel);
}
function validatePixel(pixel, where) {
if (!isPixelPair(pixel)) throw fixtureError(`${where} pixel must be [x, y], two numbers from 0 to ${ASK_USER_FIXTURE_LIMITS.maxPixel}. Or give lasso [[x, y], ...] instead.`);
}
function validateLassoPoints(lasso, where) {
const { minLassoPoints, maxLassoPoints } = ANNOTATE_LIMITS;
if (!Array.isArray(lasso) || lasso.length < minLassoPoints || lasso.length > maxLassoPoints) {
throw fixtureError(`${where} lasso must be an array of ${minLassoPoints} to ${maxLassoPoints} [x, y] points.`);
}
const badIndex = lasso.findIndex(point => !isPixelPair(point));
if (badIndex >= 0) throw fixtureError(`${where} lasso point ${badIndex + 1} must be [x, y], two numbers from 0 to ${ASK_USER_FIXTURE_LIMITS.maxPixel}.`);
}
function validateFixtureMark(mark, index, name) {
const where = `${name} mark ${index + 1}`;
if (!mark || typeof mark !== 'object' || Array.isArray(mark)) throw fixtureError(`${where} must be an object with pixel and note.`);
const { pixel, lasso, note = '', motionTime } = mark;
if (pixel !== undefined && lasso !== undefined) throw fixtureError(`${where} has both pixel and lasso. Keep one of them.`);
if (lasso !== undefined) validateLassoPoints(lasso, where);
else validatePixel(pixel, where);
if (typeof note !== 'string' || note.length > ANNOTATE_LIMITS.maxNoteLength) {
throw fixtureError(`${where} note must be text of at most ${ANNOTATE_LIMITS.maxNoteLength} characters.`);
}
if (motionTime !== undefined && !(Number.isFinite(motionTime) && motionTime >= 0 && motionTime <= ASK_USER_FIXTURE_LIMITS.maxMotionTime)) {
throw fixtureError(`${where} motionTime must be a number of seconds from 0 to ${ASK_USER_FIXTURE_LIMITS.maxMotionTime}.`);
}
// Marks of the browser flow are { x, y, note } or { kind: 'lasso', points, note }; motionTime is checked and then ignored, the
// pick is of the still frame.
return lasso === undefined ? { x: pixel[0], y: pixel[1], note } : { kind: 'lasso', points: lasso, note };
}
/**
* The fixture named by the environment, or undefined when the variable is unset or empty.
* Returns { name, marks } with marks as { x, y, note }, the shape the annotate page sends. Throws an Error that names the variable.
*/
export function loadAskUserFixture(environment = process.env) {
const filePath = environment[ASK_USER_FIXTURE_VARIABLE];
if (filePath === undefined || filePath === '') return undefined;
const name = basename(filePath);
let parsed;
try {
parsed = JSON.parse(readFixtureText(filePath));
} catch (error) {
if (error instanceof SyntaxError) throw fixtureError(`file ${name} is not valid JSON: ${error.message}.`);
throw error;
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray(parsed.marks)) {
throw fixtureError(`file ${name} must be an object like {"marks":[{"pixel":[384,256],"note":"make this red"}]}.`);
}
if (parsed.marks.length < 1 || parsed.marks.length > ANNOTATE_LIMITS.maxMarks) {
throw fixtureError(`file ${name} needs 1 to ${ANNOTATE_LIMITS.maxMarks} marks, got ${parsed.marks.length}.`);
}
return { name, marks: parsed.marks.map((mark, index) => validateFixtureMark(mark, index, name)) };
}
export function describeAskUserFixture(fixture) {
return `Crucible: scene_ask_user answers come from the fixture ${fixture.name}`;
}