Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(agent): align prompt and vision controls (#23)
Matthew Kissinger87faed67f687
diff --git a/src/__tests__/prompt-api.test.ts b/src/__tests__/prompt-api.test.tsindex 8cb52381..03958f70 100644--- a/src/__tests__/prompt-api.test.ts+++ b/src/__tests__/prompt-api.test.ts@@ -101,6 +101,7 @@ describe('system prompt embeds the generated catalog', () => {'coordinate-contract','api','architecture',+ 'authoring-strategy','quality','attachment-rules','rules',diff --git a/src/__tests__/prompt.test.ts b/src/__tests__/prompt.test.tsindex 34735b05..3af17c25 100644--- a/src/__tests__/prompt.test.ts+++ b/src/__tests__/prompt.test.ts@@ -31,6 +31,9 @@ import {KILN_REFINE_DIRECTIVE_UNIFIED,KILN_EDIT_DIRECTIVE_UNIFIED,KILN_COORDINATE_CONTRACT,+ KILN_AUTHORING_STRATEGY,+ KILN_REFERENCE_IMAGE_DIRECTIVE,+ KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED,} from '../prompt';import { KILN_ASSET_FRAME, createAssetIntentV1 } from '../contracts';@@ -46,6 +49,18 @@ describe('getSystemPrompt', () => {expect(getSystemPrompt('glb')).toBe(KILN_SYSTEM_PROMPT);});+ test('coordinates the new geometry and portable material vocabulary without prescribing every asset', () => {+ expect(KILN_AUTHORING_STRATEGY).toContain('roundedBoxGeo');+ expect(KILN_AUTHORING_STRATEGY).toContain('extrudeProfile');+ expect(KILN_AUTHORING_STRATEGY).toContain('revolveProfile');+ expect(KILN_AUTHORING_STRATEGY).toContain(+ 'proceduralTexture() creates deterministic image data',+ );+ expect(KILN_AUTHORING_STRATEGY).toContain('baked into the GLB');+ expect(KILN_AUTHORING_STRATEGY).toContain('Do not replace a simple primitive');+ expect(getSystemPrompt('glb')).toContain(KILN_AUTHORING_STRATEGY);+ });+test('returns the TSL prompt for mode=tsl', () => {expect(getSystemPrompt('tsl')).toBe(KILN_TSL_SYSTEM_PROMPT);});@@ -391,6 +406,13 @@ describe('unified tool surface prompt', () => {expect(KILN_VISUAL_QA_UNIFIED).toContain('BUILDING');});+ test('the unified vision loop explains bounded captures and object-relative orbit inspection', () => {+ expect(KILN_VISUAL_QA_UNIFIED).toContain('default 3x2 capture');+ expect(KILN_VISUAL_QA_UNIFIED).toContain('bounded custom capture.cells');+ expect(KILN_VISUAL_QA_UNIFIED).toContain('azimuthDeg/elevationDeg');+ expect(KILN_VISUAL_QA_UNIFIED).toContain('object-relative angle');+ });+test('unified takes precedence over apiSurface:trimmed (which points at the removed list tool)', () => {expect(getSystemPrompt('glb', { toolSurface: 'unified', apiSurface: 'trimmed' })).toBe(getSystemPrompt('glb', { toolSurface: 'unified' }),@@ -415,3 +437,22 @@ describe('unified tool surface prompt', () => {expect(KILN_EDIT_DIRECTIVE_UNIFIED).not.toContain('kiln_screenshot');});});++describe('reference-image grounding', () => {+ test('requires comparison-driven iteration in both tool vocabularies', () => {+ for (const directive of [+ KILN_REFERENCE_IMAGE_DIRECTIVE,+ KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED,+ ]) {+ expect(directive).toContain('primary visual evidence');+ expect(directive).toContain('silhouette and proportions');+ expect(directive).toContain('part attachment/contact');+ expect(directive).toContain('material boundaries and surface-detail scale');+ expect(directive).toContain('highest-impact visible mismatch');+ expect(directive).toContain('lighting, backdrop, or camera distortion');+ }+ expect(KILN_REFERENCE_IMAGE_DIRECTIVE).toContain('kiln_screenshot');+ expect(KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED).toContain('kiln_render');+ expect(KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED).toContain('kiln_inspect');+ });+});diff --git a/src/agent/run.ts b/src/agent/run.tsindex 7a2c1de3..2a6f198b 100644--- a/src/agent/run.ts+++ b/src/agent/run.ts@@ -32,6 +32,8 @@ import {KILN_EDIT_DIRECTIVE,KILN_REFINE_DIRECTIVE_UNIFIED,KILN_EDIT_DIRECTIVE_UNIFIED,+ KILN_REFERENCE_IMAGE_DIRECTIVE,+ KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED,} from '../prompt';import type { AssetCategory, AssetStyle } from '../prompt';import type { AssetIntentV1 } from '../contracts';@@ -344,8 +346,11 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAg...(opts.exemplarCode ? { exemplarCode: opts.exemplarCode } : {}),}) +(opts.inputImage- ? '\n\nA reference image of the desired asset is attached. Match its overall form, ' +- 'proportions, and silhouette; treat the text above as the intent and any specific changes.'+ ? `\n\n${+ surface === 'unified'+ ? KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED+ : KILN_REFERENCE_IMAGE_DIRECTIVE+ }`: '') +reviewNote;diff --git a/src/agent/tools-unified.test.ts b/src/agent/tools-unified.test.tsindex f02b596f..9b8785db 100644--- a/src/agent/tools-unified.test.ts+++ b/src/agent/tools-unified.test.ts@@ -187,6 +187,17 @@ describe('makeKilnUnifiedTools', () => {expect('pngBase64' in json).toBe(false);});+ test('kiln_render exposes and honors the bounded capture contract on the working buffer', async () => {+ const sink: UnifiedSink = { edits: [] };+ const tools = makeKilnUnifiedTools({ seedCode: BOX_CODE, sink });+ const render = findTool(tools, 'kiln_render');+ const out = (await render.invoke({ capture: { preset: '1x1' } })) as unknown[];+ const json = (out[1] as JsonBlock).json as {+ capture?: { preset?: string; cols?: number; cells?: number };+ };+ expect(json.capture).toEqual({ preset: '1x1', cols: 1, cells: 1 });+ });+test('kiln_render on a broken buffer is image-free (plain JSON error)', async () => {const sink: UnifiedSink = { edits: [] };const tools = makeKilnUnifiedTools({ seedCode: 'not a kiln program (', sink });@@ -246,6 +257,21 @@ describe('makeKilnUnifiedTools', () => {expect('pngBase64' in json).toBe(false); // image stripped by the media extractor});+ test('kiln_inspect exposes and honors object-relative orbit angles on the working buffer', async () => {+ const sink: UnifiedSink = { edits: [] };+ const tools = makeKilnUnifiedTools({ seedCode: TWO_PART_CODE, sink });+ const inspect = findTool(tools, 'kiln_inspect');+ const out = (await inspect.invoke({+ part: 'head',+ azimuthDeg: 125,+ elevationDeg: -20,+ })) as unknown[];+ const json = (out[1] as JsonBlock).json as Record<string, unknown>;+ expect(json['azimuthDeg']).toBeCloseTo(125, 1);+ expect(json['elevationDeg']).toBeCloseTo(-20, 1);+ expect(json['framed']).toContain('azimuth 125deg');+ });+test('kiln_inspect on an unknown part returns the part list without throwing (image-free)', async () => {const sink: UnifiedSink = { edits: [] };const tools = makeKilnUnifiedTools({ seedCode: TWO_PART_CODE, sink });diff --git a/src/agent/tools.ts b/src/agent/tools.tsindex 7f5d47de..08cf6113 100644--- a/src/agent/tools.ts+++ b/src/agent/tools.ts@@ -26,6 +26,8 @@ import {createKilnRenderViewsDef,createKilnScreenshotAnimationDef,createKilnViewInteriorDef,+ inspectBufferInput,+ renderViewsBufferInput,type KilnToolContext,type KilnToolDef,} from '../tools/registry';@@ -497,32 +499,6 @@ const draftInput = z.object({.describe('The complete Kiln program (defines `meta` + `build()`, optional `animate()`).'),});-/** Schema for the buffer-aware close-up tool (omits `code` — it reads the working buffer). */-const inspectBufferInput = z.object({- part: z- .string()- .optional()- .describe(- 'The part to frame, by node name (case-insensitive; substring match as a fallback). ' +- 'Omit to frame the whole asset.',- ),- view: z- .string()- .optional()- .describe('Camera angle: front, right, back, left, top, or three-quarter (default).'),- zoom: z- .number()- .optional()- .describe('Padding multiplier around the part bounds, clamped to 1-4. Default 1.2.'),- isolate: z- .boolean()- .optional()- .describe(- 'Hide everything except the named part so nothing can occlude it. Needs `part`. ' +- 'Default false.',- ),-});-/*** Build the unified buffer surface over a working buffer seeded with `seedCode`* (empty for generate, the parent's code for refine). The buffer's live edit@@ -614,10 +590,14 @@ export function makeKilnUnifiedTools(const renderTool: Tool = tool({name: 'kiln_render',- description: `${renderViewsDef.description} Operates on your current working buffer (no argument).`,- inputSchema: viewInput,- callback: async () => {- const out = await renderViewsDef.run({ code: buffer.code });+ description: `${renderViewsDef.description} Operates on your current working buffer: omit code; optional capture controls remain available.`,+ inputSchema: renderViewsBufferInput,+ callback: async (input) => {+ const i = input as { capture?: unknown };+ const out = await renderViewsDef.run({+ code: buffer.code,+ ...(i.capture !== undefined ? { capture: i.capture } : {}),+ });// Out-of-band: surface a SUCCESSFUL render as a live candidate (the working// buffer + the six-view image the agent just saw). Best-effort; a build// failure is image-free and not a candidate. Never changes the agent's view.@@ -647,11 +627,20 @@ export function makeKilnUnifiedTools(description: `${inspectDef.description} Operates on your current working buffer (no code argument).`,inputSchema: inspectBufferInput,callback: async (input) => {- const i = input as { part?: string; view?: string; zoom?: number; isolate?: boolean };+ const i = input as {+ part?: string;+ view?: string;+ azimuthDeg?: number;+ elevationDeg?: number;+ zoom?: number;+ isolate?: boolean;+ };const out = await inspectDef.run({code: buffer.code,...(i.part !== undefined ? { part: i.part } : {}),...(i.view !== undefined ? { view: i.view } : {}),+ ...(i.azimuthDeg !== undefined ? { azimuthDeg: i.azimuthDeg } : {}),+ ...(i.elevationDeg !== undefined ? { elevationDeg: i.elevationDeg } : {}),...(i.zoom !== undefined ? { zoom: i.zoom } : {}),...(i.isolate !== undefined ? { isolate: i.isolate } : {}),});diff --git a/src/prompt.ts b/src/prompt.tsindex 28f46dd1..08bff39d 100644--- a/src/prompt.ts+++ b/src/prompt.ts@@ -185,6 +185,31 @@ For animations, track names must use "Joint_" prefix:- createPart("Wheel", ..., {pivot: true}) creates "Joint_Wheel" - animate it</architecture>`;+/** Capability-selection guidance above the generated helper signatures. */+export const KILN_AUTHORING_STRATEGY = `<authoring-strategy>+Model the requested construction, not just its outline:+- For moulded, cast, machined, upholstered, or toy-like hard surfaces, prefer roundedBoxGeo with+ an intentional round/chamfer edge treatment over a perfectly sharp box. Keep truly fabricated+ sheet parts sharp when that is the design.+- Use extrudeProfile for a constant-depth designed section (bracket, sign, trim, plate, opening, or+ custom silhouette), including holes when the reference shows them. Use revolveProfile for a+ rotational body (vessel, knob, wheel rim, turned leg) whose side profile controls the form. These+ helpers are async; await them inside async build(). Do not replace a simple primitive with a sweep+ merely to sound sophisticated.+- Treat attachments and contact as construction: brackets meet hosts, wheels meet hubs and ground,+ handles join at both ends, and layered trim sits visibly proud rather than coplanar.++Author portable material response, not render-only decoration:+- Use gameMaterial for deliberate flat/stylized colour. For metal, wood, stone, bark, cloth, skin,+ glass, paint, or textured-hero requests, follow the resolved portable material recipe guidance.+- proceduralTexture() creates deterministic image data that is baked into the GLB. Build restrained+ albedo/roughness patterns (and normalMapFromHeight when useful), unwrap the geometry, and bind them+ through pbrMaterial. Prefer a few coherent material roles over unique noisy textures per part.+- Surface detail supports form: align grain, wear, seams, and pattern scale with the object's+ construction. Do not fake texture by scattering hundreds of tiny meshes or by inventing filesystem+ paths/resource IDs.+</authoring-strategy>`;+export const KILN_QUALITY = `<quality>- Give your asset personality and character- Use appropriate level of detail for the category@@ -292,7 +317,11 @@ that doesn't exist — fix the joint name. Fix any motion defect and screenshot* kiln_screenshot + kiln_submit.*/export const KILN_VISUAL_QA_UNIFIED = `<visual-qa>-After kiln_render you SEE the six views (metrics ride alongside the image). Before kiln_finalize, check each view deliberately:+Start with kiln_render's default 3x2 capture: it is the comparison baseline and metrics ride alongside+the image. Use a smaller preset (1x1/2x1/2x2) only when a simple or symmetric form repeats the same+evidence; use 3x3 only when six angles leave real ambiguity. For an underside, seam, opening, or joint+the defaults hide, pass bounded custom capture.cells with object-relative azimuth/elevation instead+of spending cells on redundant views. Before kiln_finalize, check each view deliberately:- Front (camera on +X): the nose/muzzle/face should point AT you. If you seea side profile here, the asset is built sideways — rebuild along +X.Wheels/discs read edge-on here and as circles from the side — a circle seen@@ -314,7 +343,9 @@ If any view looks wrong, fix the code (kiln_edit or kiln_draft) and re-render beIf a view reveals a suspect REGION — a floating part, a bad joint, a wrong proportion — callkiln_inspect with that part's name for a single framed close-up before editing; prefer it overre-reading the whole grid for fine detail. An unresolved name returns the list of part names to-retry with. If surrounding geometry blocks the part from every angle, pass isolate:true to hide+retry with. Use azimuthDeg/elevationDeg to orbit to any object-relative angle when a named view is+edge-on or occluded; the reply reports the angles so the next look can step from evidence rather than+guessing. If surrounding geometry blocks the part from every angle, pass isolate:true to hideeverything else.If this is an ANIMATED CHARACTER, also call kiln_screenshot_animation on your key clipsbefore finalizing — at least the walk and the main attack — from the right (side) camera,@@ -493,6 +524,7 @@ export const KILN_SYSTEM_PROMPT_SECTIONS: ReadonlyArray<readonly [string, string['coordinate-contract', KILN_COORDINATE_CONTRACT],['api', KILN_API_SECTION],['architecture', KILN_ARCHITECTURE],+ ['authoring-strategy', KILN_AUTHORING_STRATEGY],['quality', KILN_QUALITY],['attachment-rules', KILN_ATTACHMENT_RULES],['rules', KILN_RULES],@@ -794,6 +826,12 @@ export const KILN_REFINE_DIRECTIVE_UNIFIED = `You are MODIFYING an existing Kilnexport const KILN_EDIT_DIRECTIVE_UNIFIED = `You are EDITING an existing Kiln asset in place, not rebuilding it. Your working buffer is already seeded with the Current Code shown in the user message. Use the kiln_edit tool to make the SMALLEST set of changes that satisfy the Edit Request: replace an exact span (oldString) with newString. Each oldString must match the current buffer verbatim - call kiln_view to read it (the text is raw, with no line-number prefixes). Keep everything the Edit Request does not mention byte-for-byte unchanged. Every successful edit returns a static validation report - fix any errors it lists, re-render the buffer with kiln_render, then call kiln_finalize. If an edit cannot be anchored after a couple of tries, call kiln_draft to rewrite the whole program instead.`;+/** Dynamic reference grounding belongs in the user turn so an attached image+ * does not fork the large cached system prefix. */+export const KILN_REFERENCE_IMAGE_DIRECTIVE = `A reference image of the desired asset is attached. Treat it as primary visual evidence for form while the text remains authoritative for requested changes. After each kiln_screenshot, compare in this order: silhouette and proportions, major openings and part attachment/contact, then material boundaries and surface-detail scale. Fix the highest-impact visible mismatch and screenshot again. Do not add unseen companion objects or scenery, and do not copy lighting, backdrop, or camera distortion into the geometry.`;++export const KILN_REFERENCE_IMAGE_DIRECTIVE_UNIFIED = `A reference image of the desired asset is attached. Treat it as primary visual evidence for form while the text remains authoritative for requested changes. After each kiln_render, compare in this order: silhouette and proportions, major openings and part attachment/contact, then material boundaries and surface-detail scale. Fix the highest-impact visible mismatch and render again. Use kiln_inspect with an object-relative orbit for a reference feature the grid leaves edge-on or occluded. Do not add unseen companion objects or scenery, and do not copy lighting, backdrop, or camera distortion into the geometry.`;+export interface AssetBudget {maxTriangles?: number;maxMaterials?: number;diff --git a/src/tools/registry.ts b/src/tools/registry.tsindex 13a415bc..c379031a 100644--- a/src/tools/registry.ts+++ b/src/tools/registry.ts@@ -199,6 +199,12 @@ const captureInput = zconst renderViewsInput = renderInput.extend({ capture: captureInput });+/** Unified-agent schema: the working buffer supplies `code`, while the model+ * still owns the deliberately bounded camera selection. Keeping this derived+ * from the registry schema prevents the Strands skin from silently lagging the+ * canonical capture contract. */+export const renderViewsBufferInput = renderViewsInput.omit({ code: true });+const screenshotAnimationInput = z.object({code: z.string()@@ -952,6 +958,10 @@ const inspectInput = z.object({),});+/** Unified-agent schema: identical inspection controls, with source supplied+ * by the working buffer instead of the model. */+export const inspectBufferInput = inspectInput.omit({ code: true });+export interface KilnInspectResult {ok: boolean;/** Resolved part name that was framed (absent when the whole asset was framed). */