3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Return paths, not pictures, for a render result of more than 8 files (#2316)
Nguyen Xuan Anbb0f7911a2e9
diff --git a/changes/2316.md b/changes/2316.mdnew file mode 100644index 00000000..27ac2f9b--- /dev/null+++ b/changes/2316.md@@ -0,0 +1 @@+- `scene_render_result` attaches no pictures for a job of more than 8 files and returns paths and byte counts; `images` also takes up to 8 artifact indexes to attach chosen frames (#2316).diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.mdindex 5d918837..90097178 100644--- a/docs/agent-render-jobs.md+++ b/docs/agent-render-jobs.md@@ -9,7 +9,7 @@ Release `0.6.0` includes five MCP tools for asynchronous image and video renderi3. Create a scene and inspect its current revision.4. Submit `scene_render_submit` with the session ID, current revision and render settings.5. Poll `scene_render_status` until the job reaches a terminal state. The job tools take `jobId` alone; a `sessionId` is refused with that hint. A path traced job on the default cpu backend whose scene is estimated above twice 400000 triangles (the estimate can run 1.5 times high on non-indexed geometry) is refused at submit with the count, instead of failing after it started; a scene between the cap and that margin is checked exactly when the trace starts.-6. Read `scene_render_result` after completion to obtain output paths, and SHA-256 hashes with `response_format: "detailed"`. The answer attaches every PNG of the job (up to 1 MiB each) as an image, whatever `response_format` is, and adds a resource link to each file; a harness that keeps the transcript pays for those pictures on every later turn, so pass `images: false` to get the paths, sizes and metrics only. Video is never attached.+6. Read `scene_render_result` after completion to obtain output paths, and SHA-256 hashes with `response_format: "detailed"`. The answer attaches the PNGs of a job of up to 8 files (up to 1 MiB each) as images, whatever `response_format` is, and adds a resource link to each file; a job of more than 8 files attaches none, because a harness that keeps the transcript pays for every picture on each later turn. Pass `images: false` to get the paths, sizes and metrics only, or `images` as a list of up to 8 artifact indexes (counted from 0) to attach just those frames of a large job. Video is never attached.7. Release unwanted outputs with `scene_render_release`.For MP4 jobs, FFmpeg must be on PATH or configured with `--ffmpeg` and an absolute executable path.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 79aac447..54be4ae8 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -886,7 +886,11 @@ const checkpointFields = { ...sessionFields, checkpointId: z.uuid().describe('Chconst expectedRevision = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).describe('Current revision returned by create, inspect, apply or restore. Stale edits fail atomically.');const jobFields = { jobId: z.uuid().describe('Render job UUID returned by scene_render_submit or capabilities jobs.records.') };const jobWithFormatFields = { ...jobFields, response_format: responseFormatField };-const jobResultFields = { ...jobWithFormatFields, images: z.boolean().optional() };+const INLINE_IMAGE_LIMIT = 8;+const jobResultFields = {+ ...jobWithFormatFields,+ images: z.union([z.boolean(), z.array(z.number().int().min(0)).max(INLINE_IMAGE_LIMIT)]).optional().describe('false: paths only. Artifact indexes: attach only those. Default: attach all PNGs of a job of up to 8.'),+};// Job tools take jobId alone; an agent that carries sessionId over from the scene tools gets told to drop it.function jobKeysHint(toolName, acceptedKeys) {const accepted = acceptedKeys.length > 1 ? `${acceptedKeys[0]} (and ${acceptedKeys.slice(1).join(', ')})` : acceptedKeys[0];@@ -954,10 +958,28 @@ const OUTPUT_SCHEMAS = {const INLINE_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);const INLINE_IMAGE_MAXIMUM_BYTES = 1024 * 1024;-async function renderResultContent(result, shown = result, { attachImages = true } = {}) {+function isAttachableImage(artifact) {+ return INLINE_IMAGE_TYPES.has(artifact.mimeType) && artifact.bytes <= INLINE_IMAGE_MAXIMUM_BYTES;+}++// images: undefined or true attaches every PNG of a small job and none of a larger one (a 96-frame job would put+// ~100 MB in the transcript); false attaches none; an array of artifact indexes attaches exactly those.+function indexesToAttach(artifacts, images) {+ if (Array.isArray(images)) {+ const outOfRange = images.filter(index => index >= artifacts.length);+ if (outOfRange.length > 0) throw new RangeError(`images index ${outOfRange[0]} is past the last artifact (${artifacts.length - 1}). Pass indexes from 0 to ${artifacts.length - 1} of the artifacts list, or images: false for paths only.`);+ return new Set(images);+ }+ if (images === false) return new Set();+ const imageIndexes = artifacts.flatMap((artifact, index) => (isAttachableImage(artifact) ? [index] : []));+ return new Set(imageIndexes.length <= INLINE_IMAGE_LIMIT ? imageIndexes : []);+}++async function renderResultContent(result, shown = result, { images } = {}) {const content = [{ type: 'text', text: JSON.stringify(shown) }];- for (const artifact of result.artifacts) {- if (attachImages && INLINE_IMAGE_TYPES.has(artifact.mimeType) && artifact.bytes <= INLINE_IMAGE_MAXIMUM_BYTES) {+ const attachIndexes = indexesToAttach(result.artifacts, images);+ for (const [index, artifact] of result.artifacts.entries()) {+ if (attachIndexes.has(index) && isAttachableImage(artifact)) {content.push({ type: 'image', data: (await readFile(artifact.path)).toString('base64'), mimeType: artifact.mimeType });}content.push({ type: 'resource_link', uri: pathToFileURL(artifact.path).href, name: artifact.filename, mimeType: artifact.mimeType, size: artifact.bytes });@@ -1136,9 +1158,9 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versioreturn jsonResult(chosenFormat('scene_render_status', response_format) === 'concise' ? conciseJobStatus(record) : record);});register('scene_render_cancel', 'Request cancellation of one job. Poll status until terminal before using the preview again.', z.strictObject(jobFields, { error: jobKeysHint('scene_render_cancel', Object.keys(jobFields)) }), { ...edit, idempotentHint: true }, async argumentsValue => jsonResult(await runtime.cancelJob(argumentsValue)));- register('scene_render_result', 'Read completed local output paths, MIME types, byte counts, SHA-256 digests and measured render metrics. Attaches each PNG (images: false for paths only) and a resource link per file; video stays on disk.', z.strictObject(jobResultFields, { error: jobKeysHint('scene_render_result', Object.keys(jobResultFields)) }), readOnly, async ({ response_format, images, ...jobInput }) => {+ register('scene_render_result', 'Read completed local output paths, MIME types, byte counts, SHA-256 digests and measured render metrics. Attaches the PNGs of a job of up to 8 (images: false for paths only, or artifact indexes to pick frames of a larger job) and a resource link per file; video stays on disk.', z.strictObject(jobResultFields, { error: jobKeysHint('scene_render_result', Object.keys(jobResultFields)) }), readOnly, async ({ response_format, images, ...jobInput }) => {const result = await runtime.jobResult(jobInput);- return renderResultContent(result, chosenFormat('scene_render_result', response_format) === 'concise' ? conciseJobResult(result) : result, { attachImages: images !== false });+ return renderResultContent(result, chosenFormat('scene_render_result', response_format) === 'concise' ? conciseJobResult(result) : result, { images });});register('scene_render_release', 'Delete the owned files and record for a terminal job, freeing store quota. Active jobs must be cancelled first.', z.strictObject(jobFields, { error: jobKeysHint('scene_render_release', Object.keys(jobFields)) }), destroy, async argumentsValue => jsonResult(await runtime.releaseJob(argumentsValue)));return server;diff --git a/skills/render-crucible-media/SKILL.md b/skills/render-crucible-media/SKILL.mdindex 4f267b40..e479b0b1 100644--- a/skills/render-crucible-media/SKILL.md+++ b/skills/render-crucible-media/SKILL.md@@ -22,7 +22,7 @@ submit call fails: tell the user which launch option is missing.durable frame progress. Never loop tightly. Status and result answer in a short `concise` form by default; pass`response_format: "detailed"` for the full record.5. `scene_render_result`: output paths, sizes and metrics. Report the actual `width` and `height`, the backend- and the seconds; memory limits can lower the size. `detailed` adds SHA-256 hashes and resource counters. The answer attaches every PNG as an image; pass `images: false` when the paths are enough (a `stills` job is 8 pictures).+ and the seconds; memory limits can lower the size. `detailed` adds SHA-256 hashes and resource counters. The answer attaches the PNGs of a job of up to 8 files; pass `images: false` when the paths are enough, or `images: [0, 95]` (artifact indexes) to see chosen frames of a larger job.`metrics.report.fallbacks` lists everything that ran differently from the request: read it.6. Keep what you need, then `scene_render_release` to remove the job's files.7. `scene_render_cancel` stops a job; poll `scene_render_status` until it is `cancelled` before editing again.diff --git a/tests/mcp-render-result-images.test.js b/tests/mcp-render-result-images.test.jsindex 59484b4c..f8c575e8 100644--- a/tests/mcp-render-result-images.test.js+++ b/tests/mcp-render-result-images.test.js@@ -11,11 +11,11 @@ import { createAgentMcpServer } from '../scripts/mcp-server.mjs';const ONE_PIXEL_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=', 'base64');const jobId = randomUUID();-async function connectWithStills(context) {+async function connectWithStills(context, stillCount = 3) {const directory = await mkdtemp(join(tmpdir(), 'crucible-render-result-images-'));context.after(() => rm(directory, { recursive: true, force: true }));const artifacts = [];- for (const index of [1, 2, 3]) {+ for (let index = 1; index <= stillCount; index++) {const path = join(directory, `still-${index}.png`);await writeFile(path, ONE_PIXEL_PNG);artifacts.push({ filename: `still-${index}.png`, mimeType: 'image/png', bytes: ONE_PIXEL_PNG.length, path, sha256: 'a'.repeat(64) });@@ -55,6 +55,32 @@ test('scene_render_result says in its description that PNGs are attached and howconst client = await connectWithStills(context);const { tools } = await client.listTools();const tool = tools.find(candidate => candidate.name === 'scene_render_result');- assert.ok(tool.description.includes("Attaches each PNG (images: false for paths only)"));+ assert.ok(tool.description.includes('images: false for paths only'));assert.ok(tool.inputSchema.properties.images);});++test('a job of more than 8 stills returns paths and byte counts, not every picture (#2316)', async context => {+ const client = await connectWithStills(context, 96);+ const result = await client.callTool({ name: 'scene_render_result', arguments: { jobId } });+ assert.equal(countOf(result, 'image'), 0, 'no inline picture for a 96-frame job');+ assert.equal(result.structuredContent.artifacts.length, 96);+ assert.ok(result.structuredContent.artifacts.every(artifact => artifact.path && artifact.bytes > 0));+ assert.ok(JSON.stringify(result).length < 100_000, 'the whole answer stays small');+});++test('images with artifact indexes attaches only those frames of a large job (#2316)', async context => {+ const client = await connectWithStills(context, 96);+ const chosen = await client.callTool({ name: 'scene_render_result', arguments: { jobId, images: [0, 95] } });+ assert.equal(countOf(chosen, 'image'), 2);+ const tooMany = await client.callTool({ name: 'scene_render_result', arguments: { jobId, images: [0, 1, 2, 3, 4, 5, 6, 7, 8] } });+ assert.equal(tooMany.isError, true, 'more than 8 indexes is refused');+ const pastEnd = await client.callTool({ name: 'scene_render_result', arguments: { jobId, images: [96] } });+ assert.equal(pastEnd.isError, true);+ assert.match(pastEnd.content[0].text, /past the last artifact/);+});++test('a job of exactly 8 stills keeps every picture attached (#2316)', async context => {+ const client = await connectWithStills(context, 8);+ const result = await client.callTool({ name: 'scene_render_result', arguments: { jobId } });+ assert.equal(countOf(result, 'image'), 8);+});