Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 see
a 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 be
If a view reveals a suspect REGION — a floating part, a bad joint, a wrong proportion — call
kiln_inspect with that part's name for a single framed close-up before editing; prefer it over
re-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 hide
everything else.
If this is an ANIMATED CHARACTER, also call kiln_screenshot_animation on your key clips
before 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 Kiln
export 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.ts
index 13a415bc..c379031a 100644
--- a/src/tools/registry.ts
+++ b/src/tools/registry.ts
@@ -199,6 +199,12 @@ const captureInput = z
const 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). */