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(kiln): wire KILN_TOOL_SURFACE into runKilnAgent (flag-gated, default current)

Matt Kissinger277d97f09dea
diff --git a/agent/index.ts b/agent/index.ts
index 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.ts
new file mode 100644
index 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.ts
index 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<RunKilnAg
if (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<RunKilnAg
opts.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<RunKilnAg
const 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<RunKilnAg
if (!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<RunKilnAg
steps: 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.ts
new file mode 100644
index 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);
+}