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(kiln): wire KILN_TOOL_SURFACE into runKilnAgent (flag-gated, default current)
Matt Kissinger277d97f09dea
diff --git a/agent/index.ts b/agent/index.tsindex 9110ffe0..82995c94 100644--- a/agent/index.ts+++ b/agent/index.ts@@ -20,7 +20,10 @@* - {@link MetricsCollector} — per-loop tool/step/usage metrics via hooks*/export { runKilnAgent } from './run';-export type { RunKilnAgentOptions, RunKilnAgentResult, KilnKnowhow, RefineMode, KilnInputImage } from './run';+export type { RunKilnAgentOptions, RunKilnAgentResult, KilnKnowhow, KilnInputImage } from './run';++export { resolveToolSurface, buildAgentTools } from './surface';+export type { KilnToolSurface, RefineMode } from './surface';export { generateKilnAsset, generateKilnCodeAgent, DEFAULT_KILN_AGENT_MODEL } from './generate';export type { GenerateKilnAssetOptions, GenerateKilnAssetResult } from './generate';diff --git a/agent/run-surface.test.ts b/agent/run-surface.test.tsnew file mode 100644index 00000000..c470eb8a--- /dev/null+++ b/agent/run-surface.test.ts@@ -0,0 +1,89 @@+/**+ * Tool-surface resolution + assembly (the flag-gating seam of runKilnAgent).+ * buildAgentTools is a pure function of (surface, opts), so the exact tool sets+ * each surface exposes are unit-testable without a live model. resolveToolSurface+ * covers the option > env > default('current') precedence.+ *+ * Imports from ./surface (not ./run) on purpose: generate.test.ts mock.modules+ * './run', and these helpers must stay reachable in a shared test process.+ */+import { describe, expect, test } from 'bun:test';++import {+ buildAgentTools,+ resolveToolSurface,+ type ToolBuildOptions,+} from './surface';+import type { SubmitSink, EditSink, UnifiedSink } from './tools';++function freshSinks() {+ return {+ sink: {} as SubmitSink,+ editSink: { edits: [] } as EditSink,+ unifiedSink: { edits: [] } as UnifiedSink,+ };+}++const base: ToolBuildOptions = {};+const names = (tools: ReturnType<typeof buildAgentTools>) => tools.map((t) => t.name);++const UNIFIED = ['kiln_draft', 'kiln_view', 'kiln_edit', 'kiln_validate', 'kiln_render', 'kiln_finalize'];+const CURRENT_GEN = ['kiln_list_primitives', 'kiln_validate', 'kiln_render', 'kiln_screenshot', 'kiln_submit'];+const CURRENT_EDIT = [+ 'kiln_list_primitives',+ 'kiln_view',+ 'kiln_edit',+ 'kiln_validate',+ 'kiln_render',+ 'kiln_screenshot',+ 'kiln_submit',+];++describe('buildAgentTools', () => {+ test('unified surface -> the six buffer tools (fresh generate, empty seed)', () => {+ expect(names(buildAgentTools('unified', base, freshSinks()))).toEqual(UNIFIED);+ });++ test('unified surface -> the same six tools when refining (seeded buffer)', () => {+ const opts = { ...base, existingCode: 'const meta = {};', refineMode: 'edit' as const };+ expect(names(buildAgentTools('unified', opts, freshSinks()))).toEqual(UNIFIED);+ });++ test('current surface, fresh generate -> the five generate tools', () => {+ expect(names(buildAgentTools('current', base, freshSinks()))).toEqual(CURRENT_GEN);+ });++ test('current surface, refine in edit mode -> the seven edit-mode tools', () => {+ const opts = { ...base, existingCode: 'const meta = {};', refineMode: 'edit' as const };+ expect(names(buildAgentTools('current', opts, freshSinks()))).toEqual(CURRENT_EDIT);+ });++ test('current surface, refine in rewrite mode -> the five generate tools (no edit tools)', () => {+ const opts = { ...base, existingCode: 'const meta = {};', refineMode: 'rewrite' as const };+ expect(names(buildAgentTools('current', opts, freshSinks()))).toEqual(CURRENT_GEN);+ });+});++describe('resolveToolSurface', () => {+ test('an explicit option always wins', () => {+ expect(resolveToolSurface('unified')).toBe('unified');+ expect(resolveToolSurface('current')).toBe('current');+ });++ test('falls back to KILN_TOOL_SURFACE env, defaulting to current', () => {+ const prev = process.env.KILN_TOOL_SURFACE;+ try {+ delete process.env.KILN_TOOL_SURFACE;+ expect(resolveToolSurface()).toBe('current');+ process.env.KILN_TOOL_SURFACE = 'unified';+ expect(resolveToolSurface()).toBe('unified');+ process.env.KILN_TOOL_SURFACE = 'current';+ expect(resolveToolSurface()).toBe('current');+ process.env.KILN_TOOL_SURFACE = 'nonsense';+ expect(resolveToolSurface()).toBe('current'); // anything but 'unified' is current+ } finally {+ if (prev === undefined) delete process.env.KILN_TOOL_SURFACE;+ else process.env.KILN_TOOL_SURFACE = prev;+ }+ });+});diff --git a/agent/run.ts b/agent/run.tsindex 9c4b58cc..93b0750b 100644--- a/agent/run.ts+++ b/agent/run.ts@@ -19,17 +19,33 @@import { Agent, TextBlock, ImageBlock, type Plugin, type Tool, type Message } from '@strands-agents/sdk';import { AgentSkills } from '@strands-agents/sdk/vended-plugins/skills';-import { getSystemPrompt, buildUserPrompt, KILN_REFINE_DIRECTIVE, KILN_EDIT_DIRECTIVE } from '../prompt';+import {+ getSystemPrompt,+ buildUserPrompt,+ KILN_REFINE_DIRECTIVE,+ KILN_EDIT_DIRECTIVE,+ KILN_REFINE_DIRECTIVE_UNIFIED,+ KILN_EDIT_DIRECTIVE_UNIFIED,+} from '../prompt';import type { AssetCategory, AssetStyle } from '../prompt';-import { makeKilnTools, makeKilnEditTools, type SubmitSink, type EditSink, type EditRecord } from './tools';+import type { SubmitSink, EditSink, UnifiedSink, EditRecord } from './tools';+import {+ resolveToolSurface,+ buildAgentTools,+ type KilnToolSurface,+ type RefineMode,+} from './surface';import { unifiedDiff } from './diff';import { MetricsCollector, type AgentUsage, type KilnAgentEvent } from './hooks';/** How the agent learns Kiln conventions. */export type KilnKnowhow = 'inline' | 'skill';-/** How a refine applies its change: whole-program re-emission, or surgical edits. */-export type RefineMode = 'rewrite' | 'edit';+// Tool-surface types + helpers live in ./surface so they stay testable without+// the SDK-heavy agent loop (and so generate.test.ts's mock.module('./run') does+// not also stub them). Re-exported here for the package's public agent API.+export { resolveToolSurface, buildAgentTools };+export type { KilnToolSurface, RefineMode };/** A user-supplied reference image fed to the agent as multimodal context.* `base64` is the raw image bytes base64-encoded (JSON/wire-safe); `mime` is the@@ -82,6 +98,11 @@ export interface RunKilnAgentOptions {* kiln_edit/kiln_view tools so the model patches it in place. Only takes effect when* `existingCode` is set (a fresh generation always rewrites). */refineMode?: RefineMode;+ /** Which agent tool surface to use. Resolved at call time: this option, else+ * the KILN_TOOL_SURFACE env, else 'current'. The 'unified' surface is the+ * buffer-based draft/view/edit/validate/render/finalize six (render+screenshot+ * collapsed, no kiln_list_primitives). Flag-gated until a bench A/B clears it. */+ toolSurface?: KilnToolSurface;/** Agent name (for tracing). Default 'kiln-agent'. */agentName?: string;/** Live agent-loop events (tool calls / model calls) for progress UIs.@@ -135,14 +156,16 @@ function lastMessageText(message: Message | undefined): string | undefined {*/export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgentResult> {const metrics = new MetricsCollector(opts.onEvent);- // Edit mode only engages when refining (existingCode set) AND explicitly chosen.- const editMode = Boolean(opts.existingCode) && opts.refineMode === 'edit';+ const surface = resolveToolSurface(opts.toolSurface);+ // Edit mode is a `current`-surface concept (the unified surface always uses the+ // buffer factory, regardless of refineMode). Engages only when refining.+ const editMode =+ surface === 'current' && Boolean(opts.existingCode) && opts.refineMode === 'edit';const sink: SubmitSink = {};const editSink: EditSink = { edits: [] };+ const unifiedSink: UnifiedSink = { edits: [] };try {- const tools: Tool[] = editMode- ? makeKilnEditTools({ seedCode: opts.existingCode!, sink: editSink })- : makeKilnTools(sink);+ const tools: Tool[] = buildAgentTools(surface, opts, { sink, editSink, unifiedSink });const allTools: unknown[] = opts.extraTools ? [...tools, ...opts.extraTools] : tools;const plugins: Plugin[] = [];@@ -150,19 +173,37 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgif (opts.knowhow === 'skill') {if (!opts.skillDir) throw new Error('runKilnAgent: knowhow="skill" requires skillDir');plugins.push(new AgentSkills({ skills: [opts.skillDir] }));+ // NOTE: SKILL.md's working-loop reference still uses the current verbs; only+ // the terminal verb in this top-level instruction is surface-aware (the+ // unified+skill combination is a documented gap, not the prod inline path).+ const finalize =+ surface === 'unified'+ ? 'then call kiln_finalize to lock in your final asset.'+ : 'then call kiln_submit with the final code.';systemPrompt ='You generate exportable 3D game assets as Kiln code. Use the available ' +'skill(s) to learn the Kiln primitives and conventions, write the program, ' +- 'validate and render it with the kiln tools, then call kiln_submit with the ' +- 'final code.';+ 'validate and render it with the kiln tools, ' ++ finalize;} else {- systemPrompt = getSystemPrompt('glb', opts.apiSurface ? { apiSurface: opts.apiSurface } : {});+ systemPrompt = getSystemPrompt('glb', {+ ...(opts.apiSurface ? { apiSurface: opts.apiSurface } : {}),+ ...(surface === 'unified' ? { toolSurface: 'unified' as const } : {}),+ });}// Refine framing: edit an existing asset on top of the unchanged conventions.- // Edit mode swaps in the surgical-edit directive (it supersedes the refine one).+ // The directive variant follows the surface (unified uses the finalize-verb+ // directives) and the refine mechanics (edit vs rewrite emphasis).if (opts.existingCode) {- const directive = editMode ? KILN_EDIT_DIRECTIVE : KILN_REFINE_DIRECTIVE;+ const directive =+ surface === 'unified'+ ? opts.refineMode === 'edit'+ ? KILN_EDIT_DIRECTIVE_UNIFIED+ : KILN_REFINE_DIRECTIVE_UNIFIED+ : editMode+ ? KILN_EDIT_DIRECTIVE+ : KILN_REFINE_DIRECTIVE;systemPrompt = `${directive}\n\n${systemPrompt}`;}@@ -180,11 +221,16 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgopts.prompt?.trim() || (opts.inputImage ? 'Build a 3D game asset that matches the attached reference image.' : opts.prompt);const reviewNote =- '\n\nBefore submitting, call kiln_screenshot once on your final code and check ' +- 'the six views: correct facing in Front, a clean silhouette in Right, symmetry in ' +- 'Top, and no floating or detached parts in the 3/4 view. Fix anything that looks ' +- 'wrong, then call the kiln_submit tool exactly once with your final, complete ' +- 'Kiln program.';+ surface === 'unified'+ ? '\n\nBefore finalizing, call kiln_render once and look at the six views: correct ' ++ 'facing in Front, a clean silhouette in Right, symmetry in Top, and no floating or ' ++ 'detached parts in the 3/4 view. Fix anything that looks wrong (kiln_edit or ' ++ 'kiln_draft), then call kiln_finalize exactly once.'+ : '\n\nBefore submitting, call kiln_screenshot once on your final code and check ' ++ 'the six views: correct facing in Front, a clean silhouette in Right, symmetry in ' ++ 'Top, and no floating or detached parts in the 3/4 view. Fix anything that looks ' ++ 'wrong, then call the kiln_submit tool exactly once with your final, complete ' ++ 'Kiln program.';const userPrompt =buildUserPrompt({@@ -218,7 +264,10 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgconst result = await agent.invoke(invokeArgs as never);metrics.recordResultUsage(result.metrics?.latestAgentInvocation?.usage);- let code = editMode ? editSink.code : sink.code;+ // Capture: the buffer-backed surfaces (unified / edit) hold the program in+ // their sink; the current generate surface captures via kiln_submit. Both+ // fall back to structuredOutput then the last assistant text.+ let code = surface === 'unified' ? unifiedSink.code : editMode ? editSink.code : sink.code;if (!code && result.structuredOutput) {const so = result.structuredOutput as { code?: unknown };if (typeof so.code === 'string') code = so.code;@@ -227,11 +276,14 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgif (!code) code = lastText;const collected = metrics.readMetrics();- // In edit mode, attach the patch the model produced: the applied edits + a- // unified diff from the parent code to the final buffer (robust to a rewrite- // fallback, since it diffs the actual submitted code).+ // Buffer-backed surfaces (unified or edit-mode refine) carry a surgical-edit+ // trace; when refining (existingCode set) also attach a unified diff from the+ // parent to the final code (robust to a draft/rewrite fallback — it diffs the+ // actual captured code, not the edit log).+ const emitEdits = surface === 'unified' || editMode;+ const editsTrace = surface === 'unified' ? unifiedSink.edits : editSink.edits;const diff =- editMode && code && opts.existingCode+ emitEdits && code && opts.existingCode? unifiedDiff(opts.existingCode, code, { fromLabel: 'parent', toLabel: 'refined' }): undefined;return {@@ -240,7 +292,7 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAgsteps: collected.steps,...(collected.usage ? { usage: collected.usage } : {}),...(lastText ? { lastText } : {}),- ...(editMode ? { edits: editSink.edits } : {}),+ ...(emitEdits ? { edits: editsTrace } : {}),...(diff ? { diff } : {}),};} catch (err) {diff --git a/agent/surface.ts b/agent/surface.tsnew file mode 100644index 00000000..d41062f9--- /dev/null+++ b/agent/surface.ts@@ -0,0 +1,70 @@+/**+ * Tool-surface resolution + assembly — the flag-gating seam of the Kiln agent.+ *+ * Split out from run.ts so the pure (surface, opts) -> tools mapping is unit-+ * testable in isolation, and so a test that `mock.module('./run')`s the agent+ * loop (generate.test.ts) does not also stub these helpers.+ */+import type { Tool } from '@strands-agents/sdk';++import {+ makeKilnTools,+ makeKilnEditTools,+ makeKilnUnifiedTools,+ type SubmitSink,+ type EditSink,+ type UnifiedSink,+} from './tools';++/** Which agent tool surface drives the loop. 'current' = today's+ * list/validate/render/screenshot/submit (+ edit tools in edit-mode refine);+ * 'unified' = the buffer-based draft/view/edit/validate/render/finalize six. */+export type KilnToolSurface = 'current' | 'unified';++/** How a refine applies its change: whole-program re-emission, or surgical edits. */+export type RefineMode = 'rewrite' | 'edit';++/** The subset of run options the tool assembly reads. */+export interface ToolBuildOptions {+ existingCode?: string;+ refineMode?: RefineMode;+}++/** Per-run sinks for the three tool factories (only one is read, by surface). */+export interface AgentSinks {+ sink: SubmitSink;+ editSink: EditSink;+ unifiedSink: UnifiedSink;+}++/**+ * Resolve the tool surface at call time: the explicit option wins, else the+ * KILN_TOOL_SURFACE env var ('unified' opts in), else the safe default 'current'.+ */+export function resolveToolSurface(opt?: KilnToolSurface): KilnToolSurface {+ if (opt) return opt;+ return process.env.KILN_TOOL_SURFACE === 'unified' ? 'unified' : 'current';+}++/**+ * Build the base kiln tool list for a run (before extraTools are appended).+ * Pure function of (surface, opts):+ * - unified -> the 6 buffer tools (empty seed for generate, existingCode for refine)+ * - current -> the 5 generate tools, or the 7 edit-mode tools when refining in edit mode+ */+export function buildAgentTools(+ surface: KilnToolSurface,+ opts: ToolBuildOptions,+ sinks: AgentSinks,+): Tool[] {+ if (surface === 'unified') {+ return makeKilnUnifiedTools({+ ...(opts.existingCode ? { seedCode: opts.existingCode } : {}),+ sink: sinks.unifiedSink,+ });+ }+ const editMode = Boolean(opts.existingCode) && opts.refineMode === 'edit';+ return editMode+ ? makeKilnEditTools({ seedCode: opts.existingCode!, sink: sinks.editSink })+ : makeKilnTools(sinks.sink);+}