Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add response_format to the review, render job and capability tools

Nguyen Xuan An4eba74d7575f
diff --git a/changes/656.md b/changes/656.md
new file mode 100644
index 00000000..ed17a398
--- /dev/null
+++ b/changes/656.md
@@ -0,0 +1 @@
+- `scene_review`, `scene_render_status` and `scene_render_result` return only what an agent acts on by default; `response_format: "detailed"` keeps the full diagnostics, digests and metrics, and `scene_capabilities` takes `concise` to drop the field notes of a topic (#656).
diff --git a/changes/656.size.md b/changes/656.size.md
new file mode 100644
index 00000000..cfe79b53
--- /dev/null
+++ b/changes/656.size.md
@@ -0,0 +1,5 @@
+- tool:scene_review: the response_format enum costs 66 bytes
+- tool:scene_render_status: the same enum
+- tool:scene_render_result: the same enum
+- tool:scene_capabilities: the same enum
+- tool-total: four enums. Concise replies measured at 26 percent (review), 17 percent (status) and 55 percent (result, which keeps its resource link) of the detailed bytes.
diff --git a/docs/agent-review.md b/docs/agent-review.md
index 970c5f18..28af3e8b 100644
--- a/docs/agent-review.md
+++ b/docs/agent-review.md
@@ -35,7 +35,7 @@ The tool renders an isolated snapshot. It preserves the source recipe, revision,
```
The response contains one PNG image block, JSON text and structured metadata.
-The grid labels identify shots. Each shot reports its sampled camera, clocks, output dimensions and render resources.
+The grid labels identify shots. Each shot reports its sampled camera, label positions and branch. `response_format: "detailed"` also gives the clocks, output dimensions and render resources (graphics, estimated bytes, buffer counts) and the run's memory peaks.
This tool does not require a configured render job directory or write output files.
## Compare motion
diff --git a/docs/mcp.md b/docs/mcp.md
index e5a5a9b0..1905c1d6 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -133,7 +133,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe
| `mesh_edit` | `sessionId`, `expectedRevision`, `geometry`, `edits`, optional `replace` | Updated revision, render status and the mesh report with per-edit results |
| `mesh_stack` | `sessionId`, `expectedRevision`, `geometry`, optional `stack`, `apply` | Updated revision, render status and the mesh report with per-node results |
| `scene_look` | `sessionId`, optional `width`, `height`, `motionTime`, `labels` | PNG image and metadata |
-| `scene_review` | `sessionId`, `expectedRevision`, `shots` (each with an optional `branch`), optional `width`, `height`, `labels` | Labeled PNG grid and metadata from an isolated snapshot |
+| `scene_review` | `sessionId`, `expectedRevision`, `shots` (each with an optional `branch`), optional `width`, `height`, `labels`, `response_format` | Labeled PNG grid and metadata from an isolated snapshot |
| `scene_checkpoint` | `sessionId` | Checkpoint ID, session ID, and revision |
| `scene_restore` | `sessionId`, `expectedRevision`, and a `checkpointId`, a `revision` or a `branch` | Updated revision and render status |
| `scene_release_checkpoint` | `sessionId`, `checkpointId` | Release confirmation |
@@ -141,9 +141,9 @@ Inspect or export the recipe before retrying. Context loss still permits recipe
| `scene_export_glb` | `sessionId`, optional `clip`, `motionTime`, `maxTextureSize` | A GLB file under `<jobs>/exports/` with a server-chosen name: path, bytes, SHA-256. See [GLB export](export-glb.md) |
| `scene_dispose` | `sessionId` | Disposal confirmation |
| `scene_render_submit` | `sessionId`, `expectedRevision`, `settings` | Snapshot job ID and queued record |
-| `scene_render_status` | `jobId` | State and durable frame progress |
+| `scene_render_status` | `jobId`, optional `response_format` | State and durable frame progress |
| `scene_render_cancel` | `jobId` | Cancellation acknowledgement |
-| `scene_render_result` | `jobId` | Completed output paths, hashes and metrics |
+| `scene_render_result` | `jobId`, optional `response_format` | Completed output paths, hashes and metrics |
| `scene_render_release` | `jobId` | Confirmation that owned job files were removed |
`sessionId` is optional on every tool that lists it: one scene exists at a time, so a call that leaves it out means the active scene. An ID that names another scene (an invented one, or one from a disposed scene) is still rejected with the active ID in the message, because acting on a scene the caller did not name could edit the wrong one.
@@ -169,6 +169,16 @@ Set operations use `set-node`, `set-material`, or `set-camera`, with fields dire
An explicit `null` restores the authored base pose. Release `0.8.0` also supports imported source-node motion.
Imported clip sampling remains available through `set-animation`.
+### Response format
+
+`scene_review`, `scene_render_status`, `scene_render_result` and `scene_capabilities` take `response_format`: `concise` or `detailed`.
+Leave it out for the default: `concise` on the first three, `detailed` on `scene_capabilities`, whose notes are the reason to call it.
+Concise review drops the per-shot resource counters, memory peaks and unset clocks, and keeps each shot's camera, label positions and branch.
+Concise status gives `jobId`, `state`, `frames`, `frameCount`, `reason` and the artifact names.
+Concise result drops the SHA-256 digests and the render's resource counters; its other metrics (passes, depth range, object names, sync) stay.
+Concise `scene_capabilities` drops the one-line notes of a schema topic and keeps field names, types, ranges and enums.
+Pass `detailed` to get the earlier full answer. On a four-shot review the concise text is 657 bytes against 2,534 detailed.
+
`scene_review` compares up to four cameras or motion samples without changing the source recipe, revision or preview pose.
Each shot starts from the authored base pose. The [review guide](agent-review.md) describes separate clocks, dimensions and resource limits.
diff --git a/scripts/mcp-response-format.mjs b/scripts/mcp-response-format.mjs
new file mode 100644
index 00000000..9e03ecad
--- /dev/null
+++ b/scripts/mcp-response-format.mjs
@@ -0,0 +1,90 @@
+// response_format on the review, render-job and capability tools: "concise" leaves out what an agent rarely acts on, and
+// "detailed" is the full answer. The server picks the default per tool (RESPONSE_FORMAT_DEFAULTS).
+import * as z from 'zod/v4';
+
+export const RESPONSE_FORMATS = ['concise', 'detailed'];
+
+/** The same bare enum on every tool that takes the choice: a description would repeat on each tool, and the defaults are in the docs. */
+export const responseFormatField = z.enum(RESPONSE_FORMATS).optional();
+
+// Review and job answers are polled, so they default to the short form. A capability topic exists to be read in full.
+export const RESPONSE_FORMAT_DEFAULTS = {
+ scene_review: 'concise',
+ scene_render_status: 'concise',
+ scene_render_result: 'concise',
+ scene_capabilities: 'detailed',
+};
+
+export function chosenFormat(toolName, requested) {
+ return requested ?? RESPONSE_FORMAT_DEFAULTS[toolName];
+}
+
+function without(record, names) {
+ const kept = { ...record };
+ for (const name of names) delete kept[name];
+ return kept;
+}
+
+// Per-shot render diagnostics: the camera, label positions and branch stay, the resource counters go.
+const SHOT_DIAGNOSTICS = [
+ 'graphics', 'estimatedBytes', 'samples', 'hdr', 'depth', 'geometryBuffers', 'materialTextures', 'skinTextures',
+ 'morphTextures', 'gpuBuffers', 'drawBatches', 'requestedWidth', 'requestedHeight', 'width', 'height',
+];
+const REVIEW_DIAGNOSTICS = ['backend', 'peakNodeBytes', 'peakBrowserHeap', 'maximumPendingFrames', 'elapsedSeconds'];
+
+function conciseShot(shot) {
+ const kept = without(shot, SHOT_DIAGNOSTICS);
+ // An unset clock is the default; only a sampled one tells the agent something.
+ if (kept.animation === null) delete kept.animation;
+ if (kept.motionTime === null) delete kept.motionTime;
+ if (kept.rendererTime === 0) delete kept.rendererTime;
+ return kept;
+}
+
+export function conciseReview(metadata) {
+ return { ...without(metadata, REVIEW_DIAGNOSTICS), shots: metadata.shots.map(conciseShot) };
+}
+
+/** State and progress; the settings the agent submitted are not echoed back. */
+export function conciseJobStatus(record) {
+ const concise = { jobId: record.jobId, state: record.state, frames: record.progress?.frames };
+ if (record.settings?.frameCount !== undefined) concise.frameCount = record.settings.frameCount;
+ if (record.reason !== undefined) concise.reason = record.reason;
+ if (record.artifacts?.length) concise.artifacts = record.artifacts.map(artifact => artifact.filename);
+ return concise;
+}
+
+// Resource counters of the render itself. Every other metric (passes, depth range, object names, sync, path tracer) answers
+// something the agent asked for, so it stays.
+const METRIC_DIAGNOSTICS = [
+ 'graphics', 'estimatedBytes', 'peakNodeBytes', 'peakBrowserHeap', 'maximumPendingFrames', 'requestedWidth',
+ 'requestedHeight', 'elapsedSeconds', 'captureSeconds',
+];
+
+/** Files with their paths and sizes; digests and the render's resource counters stay in the detailed answer. */
+export function conciseJobResult(result) {
+ const concise = {
+ jobId: result.jobId,
+ sourceRevision: result.sourceRevision,
+ artifacts: result.artifacts.map(artifact => without(artifact, ['sha256'])),
+ };
+ if (result.metrics !== undefined) concise.metrics = without(result.metrics, METRIC_DIAGNOSTICS);
+ return concise;
+}
+
+const NOTE_SEPARATOR = ' // ';
+const NOTE_KEY = '_';
+
+/** An outline without its one-line notes: field names, types, ranges and enums only. */
+export function withoutNotes(outline) {
+ if (typeof outline === 'string') return outline.split(NOTE_SEPARATOR)[0];
+ if (Array.isArray(outline)) return outline.map(withoutNotes);
+ if (outline && typeof outline === 'object') {
+ const kept = {};
+ for (const [name, value] of Object.entries(outline)) {
+ if (name !== NOTE_KEY) kept[name] = withoutNotes(value);
+ }
+ return kept;
+ }
+ return outline;
+}
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 06b6b7d5..9a14204b 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -15,6 +15,7 @@ import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, CATALOG_FILE_ID } f
import { MATERIAL_PATTERN_TYPES, MATERIAL_MAPPINGS, LIGHTING_SETUP_NAMES, RENDER_PASS_NAMES, RENDER_OUTPUT_FORMATS, MAXIMUM_JOB_FPS, VIDEO_ENCODERS, MAXIMUM_JOB_SIDE, MAXIMUM_MEMORY_MIB } from '../src/agent-scene-capabilities.js';
import { MATERIAL_LAYER_SCALAR_RANGES, MATERIAL_LAYER_COLOR_RANGES } from '../src/material-layers.js';
import { SUBSURFACE_RANGES } from '../src/subsurface-limits.js';
+import { responseFormatField, chosenFormat, conciseReview, conciseJobStatus, conciseJobResult, withoutNotes } from './mcp-response-format.mjs';
import { createCallLogger, CALL_LOG_ENVIRONMENT_VARIABLE } from './mcp-call-log.mjs';
import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from '../src/light-limits.js';
@@ -804,15 +805,15 @@ 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) {
- const content = [{ type: 'text', text: JSON.stringify(result) }];
+async function renderResultContent(result, shown = result) {
+ const content = [{ type: 'text', text: JSON.stringify(shown) }];
for (const artifact of result.artifacts) {
if (INLINE_IMAGE_TYPES.has(artifact.mimeType) && artifact.bytes <= INLINE_IMAGE_MAXIMUM_BYTES) {
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 });
}
- return { content, structuredContent: result };
+ return { content, structuredContent: shown };
}
// Errors from the preview page arrive as "page.evaluate: RangeError: <message>\n at <bundle url>...": the stack
@@ -890,7 +891,10 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versio
return logCall ? logCall(name, call) : call();
});
}
- register('scene_capabilities', 'Index of supported recipe features and runtime budgets; pass topic for the detail of one. Read it before authoring. Does not launch a browser.', z.strictObject({ topic: z.string().min(1).max(64).optional().describe('A name from the index, or name.branch such as meshEdit.bevel. Leave out for the index.') }), readOnly, async ({ topic }) => jsonResult(answerCapabilities(relations ? await runtime.capabilities() : withoutRelationsAdvice(await runtime.capabilities()), topic, outlineSources)));
+ register('scene_capabilities', 'Index of supported recipe features and runtime budgets; pass topic for the detail of one. Read it before authoring. Does not launch a browser.', z.strictObject({ topic: z.string().min(1).max(64).optional().describe('A name from the index, or name.branch such as meshEdit.bevel. Leave out for the index.'), response_format: responseFormatField }), readOnly, async ({ topic, response_format }) => {
+ const answer = answerCapabilities(relations ? await runtime.capabilities() : withoutRelationsAdvice(await runtime.capabilities()), topic, outlineSources);
+ return jsonResult(chosenFormat('scene_capabilities', response_format) === 'concise' && answer.fields !== undefined ? { ...answer, fields: withoutNotes(answer.fields) } : answer);
+ });
register('scene_create', 'Create the single active render scene from a JSON recipe. Dispose an existing scene first.', z.strictObject({ recipe: relations ? recipe : recipeWithoutRelations }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.create(argumentsValue)));
register('scene_asset_catalog', 'List content-bound GLB and PNG, JPEG or WebP image IDs from the configured local asset directory. No arbitrary paths or downloads.', z.strictObject({}), readOnly, async () => jsonResult(await runtime.assetCatalog()));
register('scene_create_asset', 'Create the active scene from a catalog GLB and editable asset recipe. Preserves supported maps, skins, morphs and clips. Dispose the existing scene first.', z.strictObject({ recipe: assetRecipe }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.createAsset(argumentsValue)));
@@ -909,6 +913,7 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versio
width: z.number().int().min(64).max(480).default(384),
height: z.number().int().min(64).max(480).default(384),
labels: labelsFlag,
+ response_format: responseFormatField,
shots: z.array(z.strictObject({
label: z.string().max(48).optional(),
...reviewBranchField,
@@ -917,9 +922,10 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versio
motionTime: z.number().min(0).max(3600).nullable().optional(),
rendererTime: z.number().min(0).max(3600).optional(),
})).min(1).max(4),
- }), readOnly, async argumentsValue => {
- const { data, mimeType, metadata } = await runtime.review(argumentsValue);
- return { content: [{ type: 'image', data, mimeType }, { type: 'text', text: JSON.stringify(metadata) }], structuredContent: metadata };
+ }), readOnly, async ({ response_format, ...reviewInput }) => {
+ const { data, mimeType, metadata } = await runtime.review(reviewInput);
+ const shown = chosenFormat('scene_review', response_format) === 'concise' ? conciseReview(metadata) : metadata;
+ return { content: [{ type: 'image', data, mimeType }, { type: 'text', text: JSON.stringify(shown) }], structuredContent: shown };
});
register('scene_checkpoint', 'Save a private recipe snapshot. Up to eight checkpoints can be retained per session.', z.strictObject(sessionFields), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.checkpoint(argumentsValue)));
register('scene_restore', 'Restore a checkpoint atomically using the current revision. The checkpoint remains available and revision increments. With revision (last 4 kept), undo with no checkpoint. With branch, keep that branch (one revision) and drop all branches.', z.strictObject({ ...sessionFields, checkpointId: restoreCheckpointId, revision: z.number().int().min(0).optional(), ...restoreBranchField, expectedRevision }), edit, async argumentsValue => jsonResult(await runtime.restore(argumentsValue)));
@@ -928,9 +934,15 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versio
register('scene_export_glb', 'Write the active scene as a GLB file in the configured jobs folder, under a server-chosen name (the result has the path, byte count and SHA-256). Needs --jobs. Exports the current pose with pattern and imported textures, skins, morph weights and IK as posed; motionTime seeks authored motion first. For an imported asset, clip adds that source clip (translation, rotation, scale and morph weight tracks) on the source skeleton, which needs no animation, node overrides or motion in the scene. At most eight files are kept, oldest removed first; the GLB is at most 32 MiB.', z.strictObject({ ...sessionFields, clip: z.number().int().min(0).max(255).optional().describe('Imported assets only: index of the source clip to write.'), motionTime: z.number().min(0).max(3600).optional().describe('Seek authored motion (and IK) to this time before exporting. Leaves the preview there, like scene_look.'), maxTextureSize: z.number().int().min(1).max(4096).optional().describe('Largest texture side in pixels. Defaults to 2048.') }), edit, async argumentsValue => jsonResult(await runtime.exportGlb(argumentsValue)));
register('scene_dispose', 'Dispose the active scene and its checkpoints, releasing renderer resources.', z.strictObject(sessionFields), destroy, async argumentsValue => jsonResult(await runtime.dispose(argumentsValue)));
register('scene_render_submit', 'Start one asynchronous snapshot job in the configured private job store. Requires the current revision. Temporarily leases the preview renderer; does not change source revision or checkpoints.', z.strictObject({ ...sessionFields, expectedRevision, settings: renderSettings }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.submitJob(argumentsValue)));
- register('scene_render_status', 'Read render job state and durable frame progress. Terminal states are completed, cancelled, failed and interrupted.', z.strictObject(jobFields), readOnly, async argumentsValue => jsonResult(await runtime.jobStatus(argumentsValue)));
+ register('scene_render_status', 'Read render job state and durable frame progress. Terminal states are completed, cancelled, failed and interrupted.', z.strictObject({ ...jobFields, response_format: responseFormatField }), readOnly, async ({ response_format, ...jobInput }) => {
+ const record = await runtime.jobStatus(jobInput);
+ return 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), { ...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. Returns a PNG inline and a resource link to each file; video stays on disk.', z.strictObject(jobFields), readOnly, async argumentsValue => renderResultContent(await runtime.jobResult(argumentsValue)));
+ register('scene_render_result', 'Read completed local output paths, MIME types, byte counts, SHA-256 digests and measured render metrics. Returns a PNG inline and a resource link to each file; video stays on disk.', z.strictObject({ ...jobFields, response_format: responseFormatField }), readOnly, async ({ response_format, ...jobInput }) => {
+ const result = await runtime.jobResult(jobInput);
+ return renderResultContent(result, chosenFormat('scene_render_result', response_format) === 'concise' ? conciseJobResult(result) : result);
+ });
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), destroy, async argumentsValue => jsonResult(await runtime.releaseJob(argumentsValue)));
return server;
}
diff --git a/skills/render-67js-media/SKILL.md b/skills/render-67js-media/SKILL.md
index adfd937f..3371a6ca 100644
--- a/skills/render-67js-media/SKILL.md
+++ b/skills/render-67js-media/SKILL.md
@@ -17,9 +17,10 @@ submit call fails: tell the user which launch option is missing.
2. `scene_inspect` for the current `revision`.
3. `scene_render_submit` with `expectedRevision` and `settings`. Start small: one image at 960x540.
4. `scene_render_status` with the `jobId` until the state is terminal (`completed`, `failed`, `cancelled`,
- `interrupted`). Poll about every 5 to 10 seconds, and for video read the durable frame progress. Never loop tightly.
-5. `scene_render_result`: output paths, SHA-256 hashes and metrics. Report the actual `width` and `height`, the backend
- and the seconds; memory limits can lower the size.
+ `interrupted`). Poll about every 5 to 10 seconds, and for video read the 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.
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-response-format.test.js b/tests/mcp-response-format.test.js
new file mode 100644
index 00000000..ddc2a7f1
--- /dev/null
+++ b/tests/mcp-response-format.test.js
@@ -0,0 +1,136 @@
+import './support/load-agent-scene-modules.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Client } from '@modelcontextprotocol/client';
+import { InMemoryTransport } from '@modelcontextprotocol/server';
+import { createAgentMcpServer } from '../scripts/mcp-server.mjs';
+import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';
+import { conciseJobResult, conciseJobStatus, conciseReview, withoutNotes } from '../scripts/mcp-response-format.mjs';
+
+const png = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=';
+const jobId = '0f95a6dd-4128-440e-bc31-8a529180caf2';
+
+const shot = {
+ label: 'Front', camera: { eye: [4, 2, 1], target: [0, 1, 0], up: [0, 1, 0], fov: 36, near: 0.1, far: 40 },
+ animation: null, motionTime: null, rendererTime: 0, requestedWidth: 384, requestedHeight: 384,
+ graphics: 'ANGLE (SwiftShader)', estimatedBytes: 23703276, width: 384, height: 384, samples: 0, hdr: true, depth: true,
+ geometryBuffers: 7, materialTextures: 0, skinTextures: 0, morphTextures: 0, gpuBuffers: 33, drawBatches: 7,
+ labels: [{ id: 'mesh', name: 'mesh', tag: 'surface', faceTags: [], problems: [], x: 10, y: 20 }],
+};
+const reviewMetadata = {
+ sessionId: jobId, sourceRevision: 3, backend: 'cpu', width: 768, height: 384, shots: [shot, { ...shot, label: 'Back', motionTime: 1.5 }],
+ peakNodeBytes: 136802304, peakBrowserHeap: 19285872, maximumPendingFrames: 1, elapsedSeconds: 13.8,
+};
+const jobRecord = {
+ schemaVersion: 1, jobId, sourceRevision: 3, state: 'completed',
+ settings: { kind: 'image', width: 128, height: 128, fps: 24, duration: 1, frameCount: 1, rendererTime: { start: 0, rate: 1 } },
+ progress: { frames: 1, maximumPendingFrames: 1 },
+ artifacts: [{ filename: 'render.mp4', mimeType: 'video/mp4', bytes: 8765, sha256: 'ab'.repeat(32) }],
+ metrics: { backend: 'cpu', width: 128, renderSeconds: 0.36, depthRangeMetres: [1, 9], peakNodeBytes: 146837504, graphics: 'ANGLE (SwiftShader)', estimatedBytes: 17936108 },
+};
+const jobResult = {
+ jobId, sourceRevision: 3, metrics: jobRecord.metrics,
+ artifacts: [{ ...jobRecord.artifacts[0], path: 'jobs/render.mp4' }],
+};
+
+async function connect(context) {
+ const runtime = {
+ async capabilities() { return { scene: AGENT_SCENE_CAPABILITIES, phase: 'idle', availableIn: 'test' }; },
+ async review() { return { data: png, mimeType: 'image/png', metadata: structuredClone(reviewMetadata) }; },
+ async jobStatus() { return structuredClone(jobRecord); },
+ async jobResult() { return structuredClone(jobResult); },
+ async close() {},
+ activeSessionId() { return null; },
+ };
+ const server = createAgentMcpServer(runtime);
+ const client = new Client({ name: '67js-response-format-test', version: '1' });
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ context.after(async () => {
+ await client.close();
+ await server.close();
+ });
+ return client;
+}
+
+const textBytes = result => Buffer.byteLength(result.content.find(block => block.type === 'text').text);
+
+async function rejectsFormat(client, name, argumentsValue) {
+ let result;
+ try {
+ result = await client.callTool({ name, arguments: { ...argumentsValue, response_format: 'verbose' } });
+ } catch (error) {
+ assert.match(error.message, /invalid|response_format|expected/i);
+ return;
+ }
+ assert.equal(result.isError, true, `${name} must reject an unknown response_format`);
+}
+
+test('scene_review defaults to concise and keeps the full metadata as detailed', async context => {
+ const client = await connect(context);
+ const arguments_ = { expectedRevision: 3, shots: [{}, {}] };
+ const fallback = await client.callTool({ name: 'scene_review', arguments: arguments_ });
+ const concise = await client.callTool({ name: 'scene_review', arguments: { ...arguments_, response_format: 'concise' } });
+ const detailed = await client.callTool({ name: 'scene_review', arguments: { ...arguments_, response_format: 'detailed' } });
+ assert.deepEqual(fallback.structuredContent, concise.structuredContent);
+ assert.deepEqual(detailed.structuredContent, reviewMetadata);
+ assert.equal(concise.structuredContent.shots[0].graphics, undefined);
+ assert.equal(concise.structuredContent.peakNodeBytes, undefined);
+ assert.deepEqual(concise.structuredContent.shots[0].camera, shot.camera);
+ assert.deepEqual(concise.structuredContent.shots[0].labels, shot.labels);
+ assert.equal(concise.structuredContent.shots[1].motionTime, 1.5);
+ assert.equal(concise.structuredContent.shots[0].motionTime, undefined);
+ assert.ok(textBytes(concise) * 2 < textBytes(detailed), 'concise review is under half the detailed size');
+ await rejectsFormat(client, 'scene_review', arguments_);
+});
+
+test('scene_render_status defaults to concise and keeps the full record as detailed', async context => {
+ const client = await connect(context);
+ const concise = await client.callTool({ name: 'scene_render_status', arguments: { jobId } });
+ const detailed = await client.callTool({ name: 'scene_render_status', arguments: { jobId, response_format: 'detailed' } });
+ assert.deepEqual(concise.structuredContent, { jobId, state: 'completed', frames: 1, frameCount: 1, artifacts: ['render.mp4'] });
+ assert.deepEqual(detailed.structuredContent, jobRecord);
+ assert.ok(textBytes(concise) * 3 < textBytes(detailed), 'concise status is under a third of the detailed size');
+ await rejectsFormat(client, 'scene_render_status', { jobId });
+});
+
+test('a failed job keeps its reason in the concise status', () => {
+ const concise = conciseJobStatus({ jobId, state: 'failed', progress: { frames: 0 }, reason: 'Out of memory.', artifacts: [], settings: {} });
+ assert.equal(concise.reason, 'Out of memory.');
+ assert.equal(concise.artifacts, undefined);
+});
+
+test('scene_render_result defaults to concise and keeps digests and resource counters as detailed', async context => {
+ const client = await connect(context);
+ const concise = await client.callTool({ name: 'scene_render_result', arguments: { jobId } });
+ const detailed = await client.callTool({ name: 'scene_render_result', arguments: { jobId, response_format: 'detailed' } });
+ assert.deepEqual(concise.structuredContent, {
+ jobId, sourceRevision: 3, metrics: { backend: 'cpu', width: 128, renderSeconds: 0.36, depthRangeMetres: [1, 9] },
+ artifacts: [{ filename: 'render.mp4', mimeType: 'video/mp4', bytes: 8765, path: 'jobs/render.mp4' }],
+ });
+ assert.deepEqual(detailed.structuredContent, jobResult);
+ assert.equal(concise.content.filter(block => block.type === 'resource_link').length, 1);
+ assert.ok(textBytes(concise) < textBytes(detailed));
+ await rejectsFormat(client, 'scene_render_result', { jobId });
+});
+
+test('scene_capabilities defaults to detailed and concise drops the field notes of a topic', async context => {
+ const client = await connect(context);
+ const fallback = await client.callTool({ name: 'scene_capabilities', arguments: { topic: 'materialFields' } });
+ const detailed = await client.callTool({ name: 'scene_capabilities', arguments: { topic: 'materialFields', response_format: 'detailed' } });
+ const concise = await client.callTool({ name: 'scene_capabilities', arguments: { topic: 'materialFields', response_format: 'concise' } });
+ assert.deepEqual(fallback.structuredContent, detailed.structuredContent);
+ assert.ok(textBytes(concise) < textBytes(detailed));
+ assert.deepEqual(Object.keys(concise.structuredContent.fields), Object.keys(detailed.structuredContent.fields).filter(name => name !== '_'));
+ assert.ok(!JSON.stringify(concise.structuredContent.fields).includes(' // '));
+ const index = await client.callTool({ name: 'scene_capabilities', arguments: { response_format: 'concise' } });
+ assert.deepEqual(index.structuredContent, (await client.callTool({ name: 'scene_capabilities', arguments: {} })).structuredContent);
+ await rejectsFormat(client, 'scene_capabilities', {});
+});
+
+test('the helpers leave unknown fields alone', () => {
+ assert.deepEqual(conciseReview({ shots: [{ extra: 1, graphics: 'x' }], backend: 'cpu', other: 2 }), { shots: [{ extra: 1 }], other: 2 });
+ assert.deepEqual(conciseJobResult({ jobId, sourceRevision: 1, artifacts: [{ filename: 'a.png', sha256: 'x' }] }), { jobId, sourceRevision: 1, artifacts: [{ filename: 'a.png' }] });
+ assert.deepEqual(withoutNotes({ _: 'note', 'a?': 'number[0..1] // unit', list: ['x // y'] }), { 'a?': 'number[0..1]', list: ['x'] });
+});