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): make the Strands agent loop the default codegen path

Matt Kissingerf2b433220c26
diff --git a/__tests__/top-level-generate.test.ts b/__tests__/top-level-generate.test.ts
index 69ca1f86..eb387333 100644
--- a/__tests__/top-level-generate.test.ts
+++ b/__tests__/top-level-generate.test.ts
@@ -7,7 +7,7 @@
* we can drive both branches without an LLM round-trip.
*/
-import { describe, expect, test, mock, beforeEach } from 'bun:test';
+import { describe, expect, test, mock, beforeEach, afterAll } from 'bun:test';
// Per-importer mock pattern, matching companions.test.ts. Each test gets
// a fresh import of `../index` so the module-scoped mock state stays clean.
@@ -35,8 +35,15 @@ function build() {
}
`;
-describe('kiln.generate() top-level pipeline', () => {
+// These tests cover the SINGLE-SHOT fallback path (the Claude Agent SDK query),
+// which kiln.generate() now reaches only via codegen='single-shot' /
+// KILN_CODEGEN=single-shot. The default 'agent' path is covered by the agent
+// engine tests (agent/generate.test.ts) + the live e2e; pin single-shot here so
+// the SDK mock is the one exercised.
+describe('kiln.generate() top-level pipeline (single-shot fallback)', () => {
+ const savedCodegen = process.env['KILN_CODEGEN'];
beforeEach(async () => {
+ process.env['KILN_CODEGEN'] = 'single-shot';
queryImpl = async function* () {
yield {
type: 'result',
@@ -47,6 +54,10 @@ describe('kiln.generate() top-level pipeline', () => {
};
kiln = await freshImport();
});
+ afterAll(() => {
+ if (savedCodegen === undefined) delete process.env['KILN_CODEGEN'];
+ else process.env['KILN_CODEGEN'] = savedCodegen;
+ });
test('returns code + glb + meta + warnings for a valid response', async () => {
const out = await kiln.generate('a small red box');
diff --git a/agent/generate.test.ts b/agent/generate.test.ts
new file mode 100644
index 00000000..d02381ea
--- /dev/null
+++ b/agent/generate.test.ts
@@ -0,0 +1,117 @@
+/**
+ * Wiring tests for `generateKilnAsset` — the agent-loop + render engine.
+ *
+ * Only `./run` (runKilnAgent) is mocked; nothing else in the codebase imports it,
+ * so the module mock is leak-safe. `makeKilnModel` + `resolveKilnAgentModel` +
+ * `renderGLB` all run for real: the mocked agent returns a known-valid Kiln
+ * program, which renderGLB renders to actual GLB bytes. The live e2e
+ * (`pixelforge gen glb`) covers the LLM half.
+ */
+import { test, expect, describe, mock, beforeAll, afterAll } from 'bun:test';
+
+// A real, minimal, valid Kiln program (mirrors render-edges.test.ts). renderGLB
+// executes this for real to prove the engine wires the agent's code into a GLB.
+const CANNED_CODE = `
+const meta = { name: 'TestBox' };
+function build() {
+ const root = createRoot('TestBox');
+ createPart('Body', boxGeo(1, 1, 1), lambertMaterial(0xff00ff), { parent: root });
+ return root;
+}
+`;
+
+// Mutable impl the mocked runKilnAgent delegates to (set per test).
+let runImpl: (opts: Record<string, unknown>) => Promise<Record<string, unknown>>;
+mock.module('./run', () => ({
+ runKilnAgent: (opts: Record<string, unknown>) => runImpl(opts),
+}));
+
+// mock.module must precede the import of the module under test (bun runs it in
+// order; ESM imports would hoist above it, so the dynamic import is required).
+const { generateKilnAsset, DEFAULT_KILN_AGENT_MODEL } = await import('./generate');
+
+describe('generateKilnAsset', () => {
+ const saved: Record<string, string | undefined> = {};
+ const KEYS = ['GEMINI_API_KEY', 'ANTHROPIC_API_KEY', 'KILN_MODEL', 'PIXEL_FORGE_MODEL'];
+ beforeAll(() => {
+ for (const k of KEYS) saved[k] = process.env[k];
+ // Dummy keys so native model construction never touches the network.
+ if (!process.env['GEMINI_API_KEY']) process.env['GEMINI_API_KEY'] = 'test-gemini-key';
+ if (!process.env['ANTHROPIC_API_KEY']) process.env['ANTHROPIC_API_KEY'] = 'test-anthropic-key';
+ // Clear model overrides so the default (gemini) resolves at call time.
+ delete process.env['KILN_MODEL'];
+ delete process.env['PIXEL_FORGE_MODEL'];
+ });
+ afterAll(() => {
+ for (const k of KEYS) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ }
+ });
+
+ test('default model is gemini 3.5 flash (google)', () => {
+ expect(DEFAULT_KILN_AGENT_MODEL).toBe('google:gemini-3.5-flash');
+ });
+
+ test('defaults to gemini, drives runKilnAgent, renders the submitted code to GLB', async () => {
+ let captured: Record<string, unknown> | undefined;
+ runImpl = async (opts) => {
+ captured = opts;
+ return {
+ code: CANNED_CODE,
+ toolCalls: ['kiln_list_primitives', 'kiln_validate', 'kiln_render', 'kiln_submit'],
+ steps: 3,
+ usage: { inputTokens: 100, outputTokens: 200 },
+ };
+ };
+
+ const r = await generateKilnAsset({ prompt: 'a wooden crate' });
+
+ // Default model resolved to the google/gemini descriptor (honest provenance).
+ expect(r.provider).toBe('google');
+ expect(r.model).toBe('gemini-3.5-flash');
+ // Tool-loop metrics passed through.
+ expect(r.toolCalls).toContain('kiln_submit');
+ expect(r.steps).toBe(3);
+ expect(r.usage?.outputTokens).toBe(200);
+ // The agent's code was rendered for real.
+ expect(r.glb).toBeInstanceOf(Buffer);
+ expect(r.glb.byteLength).toBeGreaterThan(500);
+ expect(r.meta.tris ?? 0).toBeGreaterThan(0);
+ // Prompt + category threaded into the agent.
+ expect(captured?.['prompt']).toBe('a wooden crate');
+ expect(captured?.['category']).toBe('prop');
+ });
+
+ test('threads an explicit model + refine fields', async () => {
+ let captured: Record<string, unknown> | undefined;
+ runImpl = async (opts) => {
+ captured = opts;
+ return { code: CANNED_CODE, toolCalls: ['kiln_submit'], steps: 1 };
+ };
+
+ const r = await generateKilnAsset({
+ prompt: 'make it taller',
+ model: 'anthropic:claude-opus-4-8',
+ existingCode: 'const meta={};function build(){return createRoot();}',
+ refineMode: 'edit',
+ originalPrompt: 'a tower',
+ });
+
+ expect(r.provider).toBe('anthropic');
+ expect(r.model).toBe('claude-opus-4-8');
+ expect(captured?.['existingCode']).toBeTruthy();
+ expect(captured?.['refineMode']).toBe('edit');
+ expect(captured?.['originalPrompt']).toBe('a tower');
+ });
+
+ test('throws when the agent returns an error', async () => {
+ runImpl = async () => ({ error: 'stream ended without completing a message', toolCalls: [], steps: 0 });
+ await expect(generateKilnAsset({ prompt: 'x' })).rejects.toThrow(/stream ended/);
+ });
+
+ test('throws when the agent returns no code', async () => {
+ runImpl = async () => ({ toolCalls: ['kiln_validate'], steps: 1 });
+ await expect(generateKilnAsset({ prompt: 'x' })).rejects.toThrow(/no code/);
+ });
+});
diff --git a/agent/generate.ts b/agent/generate.ts
new file mode 100644
index 00000000..02d0d3e6
--- /dev/null
+++ b/agent/generate.ts
@@ -0,0 +1,137 @@
+/**
+ * `generateKilnAsset` — the core-owned "agent loop + render" engine.
+ *
+ * Resolve a model id -> Strands `Model` -> drive the kiln tool loop
+ * (`runKilnAgent`: list_primitives / validate / render / submit, self-correcting
+ * on real render metrics) -> render the submitted program to GLB bytes. This is
+ * the DEFAULT codegen path for `kiln.generate()` (primitives), the CLI / MCP
+ * (runs), and the batch harness — the legacy single-shot paths stay reachable via
+ * `KILN_CODEGEN=single-shot`.
+ *
+ * Promoted from Kiln Studio's in-process generator so CLI / batch / server share
+ * one engine instead of each re-implementing buildModel -> runKilnAgent ->
+ * renderGLB. Lives on the strands-isolated `kiln/agent` subpath; consumers in the
+ * non-agent `kiln` module must import it lazily (dynamic `import()`), so the
+ * `@strands-agents/sdk` dependency never enters the browser/editor bundle graph.
+ */
+import { renderGLB, type KilnCodeMeta } from '../render';
+import type { AssetCategory, AssetStyle } from '../prompt';
+import { runKilnAgent, type RefineMode, type KilnKnowhow } from './run';
+import {
+ makeKilnModel,
+ resolveKilnAgentModel,
+ type KilnAgentProvider,
+ type KilnModelDescriptor,
+} from './providers';
+import type { EditRecord } from './tools';
+import type { AgentUsage } from './hooks';
+
+/**
+ * The hardcoded default Kiln agent model — the verified standout for GLB codegen.
+ * A per-run `model` opt, or `KILN_MODEL` / `PIXEL_FORGE_MODEL` in the env (both
+ * read at call time, not import time), overrides it.
+ */
+export const DEFAULT_KILN_AGENT_MODEL = 'google:gemini-3.5-flash';
+
+export interface GenerateKilnAssetOptions {
+ /** Natural-language description of the asset to build. */
+ prompt: string;
+ /** Model id (registry-style `google:gemini-3.5-flash` or bare). Defaults to {@link DEFAULT_KILN_AGENT_MODEL}. */
+ model?: string;
+ /** BYOK / shared key override; falls back to provider env vars. */
+ apiKey?: string;
+ /** Asset category (drives prompt framing). Default 'prop'. */
+ category?: AssetCategory;
+ /** Optional style template (low-poly / stylized / voxel / detailed / realistic). */
+ style?: AssetStyle;
+ /** Ask the model for an animate() function too. Default false (static). */
+ includeAnimation?: boolean;
+ /** Know-how source: inline system prompt (default) or the kiln-glb skill. */
+ knowhow?: KilnKnowhow;
+ /** Absolute path to a SKILL.md dir, required when knowhow='skill'. */
+ skillDir?: string;
+ /** Refine: existing Kiln program to edit (frames the run as a refine). */
+ existingCode?: string;
+ /** The asset's original generation prompt, surfaced as "## Original Request" when refining. */
+ originalPrompt?: string;
+ /** How a refine applies its change ('rewrite' default, 'edit' surgical). Only with existingCode. */
+ refineMode?: RefineMode;
+ /** Agent name (for tracing). */
+ agentName?: string;
+}
+
+export interface GenerateKilnAssetResult {
+ /** The final Kiln program. */
+ code: string;
+ /** Rendered GLB, ready to write to disk. */
+ glb: Buffer;
+ /** Extracted from the code's `const meta = {...}` block, plus `tris` + `primitiveUsage`. */
+ meta: KilnCodeMeta;
+ /** Non-fatal issues (structural warnings, animation target missing). */
+ warnings: string[];
+ /** Every tool the model called, in order (proof the loop ran). */
+ toolCalls: string[];
+ /** Number of model calls (agent-loop iterations). */
+ steps: number;
+ /** Best-effort token usage. */
+ usage?: AgentUsage;
+ /** Resolved Strands provider (for honest provenance). */
+ provider: KilnAgentProvider;
+ /** Resolved concrete model id (for honest provenance). */
+ model: string;
+ /** Edit-mode refine: the applied surgical edits in order. */
+ edits?: EditRecord[];
+ /** Edit-mode refine: a unified diff from the parent code to the final buffer. */
+ diff?: string;
+}
+
+/**
+ * Run one Kiln agent generation end-to-end: model -> tool loop -> GLB render.
+ * Throws on a hard failure (agent error / no code / render failure); non-fatal
+ * issues surface via `warnings`.
+ */
+export async function generateKilnAsset(
+ opts: GenerateKilnAssetOptions,
+): Promise<GenerateKilnAssetResult> {
+ const modelId =
+ opts.model ??
+ process.env['KILN_MODEL'] ??
+ process.env['PIXEL_FORGE_MODEL'] ??
+ DEFAULT_KILN_AGENT_MODEL;
+ const desc: KilnModelDescriptor = resolveKilnAgentModel(modelId);
+ const model = makeKilnModel(desc, opts.apiKey ? { apiKey: opts.apiKey } : {});
+
+ const agent = await runKilnAgent({
+ model,
+ prompt: opts.prompt,
+ category: opts.category ?? 'prop',
+ knowhow: opts.knowhow ?? 'inline',
+ includeAnimation: opts.includeAnimation ?? false,
+ ...(opts.style ? { style: opts.style } : {}),
+ ...(opts.skillDir ? { skillDir: opts.skillDir } : {}),
+ ...(opts.existingCode ? { existingCode: opts.existingCode } : {}),
+ ...(opts.originalPrompt ? { originalPrompt: opts.originalPrompt } : {}),
+ ...(opts.existingCode && opts.refineMode ? { refineMode: opts.refineMode } : {}),
+ ...(opts.agentName ? { agentName: opts.agentName } : {}),
+ });
+
+ if (agent.error || !agent.code) {
+ throw new Error(`Kiln agent generation failed: ${agent.error ?? 'agent produced no code'}`);
+ }
+
+ const render = await renderGLB(agent.code);
+
+ return {
+ code: agent.code,
+ glb: render.glb,
+ meta: render.meta,
+ warnings: [...(render.warnings ?? [])],
+ toolCalls: agent.toolCalls,
+ steps: agent.steps,
+ ...(agent.usage ? { usage: agent.usage } : {}),
+ provider: desc.provider,
+ model: desc.model,
+ ...(agent.edits ? { edits: agent.edits } : {}),
+ ...(agent.diff ? { diff: agent.diff } : {}),
+ };
+}
diff --git a/agent/index.ts b/agent/index.ts
index c789bfa8..f1086938 100644
--- a/agent/index.ts
+++ b/agent/index.ts
@@ -8,6 +8,9 @@
* from `@pixel-forge/core/kiln/agent` only when you want the agent loop.
*
* - {@link runKilnAgent} — drive any Strands Model through the kiln tool loop
+ * - {@link generateKilnAsset} — model id -> tool loop -> rendered GLB (the default codegen engine)
+ * - {@link makeKilnModel} — agnostic Strands model factory (native + OpenRouter)
+ * - {@link resolveKilnAgentModel} — model-id string -> Strands provider descriptor
* - {@link makeKilnTools} — in-process tool skin over the shared registry
* - {@link makeKilnEditTools} — surgical edit-tool skin for refining an existing asset
* - {@link unifiedDiff} — dependency-free unified diff (the refine patch artifact)
@@ -18,6 +21,9 @@
export { runKilnAgent } from './run';
export type { RunKilnAgentOptions, RunKilnAgentResult, KilnKnowhow, RefineMode } from './run';
+export { generateKilnAsset, DEFAULT_KILN_AGENT_MODEL } from './generate';
+export type { GenerateKilnAssetOptions, GenerateKilnAssetResult } from './generate';
+
export { makeKilnTools, makeKilnEditTools, KilnEditBuffer, KILN_SUBMIT_TOOL_NAME } from './tools';
export type { SubmitSink, EditSink, EditRecord, EditResult } from './tools';
@@ -26,8 +32,13 @@ export type { UnifiedDiffOptions } from './diff';
export { ensureStreamStart } from './stream-start';
-export { makeOpenRouterModel } from './providers';
-export type { OpenRouterModelOptions } from './providers';
+export { makeOpenRouterModel, makeKilnModel, resolveKilnAgentModel } from './providers';
+export type {
+ OpenRouterModelOptions,
+ KilnAgentProvider,
+ KilnModelDescriptor,
+ MakeKilnModelOptions,
+} from './providers';
export { MetricsCollector } from './hooks';
export type { CollectedMetrics, AgentUsage } from './hooks';
diff --git a/agent/providers.test.ts b/agent/providers.test.ts
new file mode 100644
index 00000000..62c7656f
--- /dev/null
+++ b/agent/providers.test.ts
@@ -0,0 +1,82 @@
+/**
+ * Unit tests for the agnostic Kiln model factory + the agent-vocab resolver.
+ *
+ * `resolveKilnAgentModel` is the bug-prone piece: the single-shot harness vocab
+ * (`gemini`/`fal`, no `google:`/`bedrock:`) would route `google:gemini-3.5-flash`
+ * to anthropic, so the agent path owns its own resolver. These tests pin that.
+ * `makeKilnModel` is checked for the correct Strands class per provider (dummy
+ * keys so native construction never touches the network).
+ */
+import { test, expect, describe, beforeAll, afterAll } from 'bun:test';
+import { resolveKilnAgentModel, makeKilnModel } from './providers';
+
+describe('resolveKilnAgentModel', () => {
+ test('explicit provider prefixes win and keep the model id intact', () => {
+ expect(resolveKilnAgentModel('google:gemini-3.5-flash')).toEqual({ provider: 'google', model: 'gemini-3.5-flash' });
+ expect(resolveKilnAgentModel('anthropic:claude-opus-4-8')).toEqual({ provider: 'anthropic', model: 'claude-opus-4-8' });
+ expect(resolveKilnAgentModel('openai:gpt-5.5')).toEqual({ provider: 'openai', model: 'gpt-5.5' });
+ expect(resolveKilnAgentModel('bedrock:global.anthropic.claude-opus-4-8')).toEqual({
+ provider: 'bedrock',
+ model: 'global.anthropic.claude-opus-4-8',
+ });
+ expect(resolveKilnAgentModel('openrouter:anthropic/claude-opus-4.8')).toEqual({
+ provider: 'openrouter',
+ model: 'anthropic/claude-opus-4.8',
+ });
+ });
+
+ test('a bare vendor/model slash id is OpenRouter', () => {
+ expect(resolveKilnAgentModel('x-ai/grok-4.3')).toEqual({ provider: 'openrouter', model: 'x-ai/grok-4.3' });
+ });
+
+ test('bare gemini-* resolves to google (the regression the harness vocab gets wrong)', () => {
+ expect(resolveKilnAgentModel('gemini-3.5-flash')).toEqual({ provider: 'google', model: 'gemini-3.5-flash' });
+ expect(resolveKilnAgentModel('imagen-4')).toEqual({ provider: 'google', model: 'imagen-4' });
+ });
+
+ test('bare gpt-* / o3 / o4 resolve to openai', () => {
+ expect(resolveKilnAgentModel('gpt-5.5').provider).toBe('openai');
+ expect(resolveKilnAgentModel('o3-mini').provider).toBe('openai');
+ expect(resolveKilnAgentModel('o4').provider).toBe('openai');
+ });
+
+ test('bare claude-* and unknown ids default to anthropic', () => {
+ expect(resolveKilnAgentModel('claude-opus-4-8')).toEqual({ provider: 'anthropic', model: 'claude-opus-4-8' });
+ expect(resolveKilnAgentModel('some-future-model').provider).toBe('anthropic');
+ });
+
+ test('trims surrounding whitespace', () => {
+ expect(resolveKilnAgentModel(' google:gemini-3.5-flash ')).toEqual({ provider: 'google', model: 'gemini-3.5-flash' });
+ });
+});
+
+describe('makeKilnModel', () => {
+ const saved: Record<string, string | undefined> = {};
+ const KEYS = ['GEMINI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY'];
+
+ beforeAll(() => {
+ for (const k of KEYS) {
+ saved[k] = process.env[k];
+ if (!process.env[k]) process.env[k] = `test-${k.toLowerCase()}`;
+ }
+ });
+ afterAll(() => {
+ for (const k of KEYS) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ }
+ });
+
+ test('constructs the right Strands model class per provider', () => {
+ expect(makeKilnModel({ provider: 'google', model: 'gemini-3.5-flash' }).constructor.name).toBe('GoogleModel');
+ expect(makeKilnModel({ provider: 'anthropic', model: 'claude-opus-4-8', maxTokens: 16000 }).constructor.name).toBe('AnthropicModel');
+ expect(makeKilnModel({ provider: 'openai', model: 'gpt-5.5', maxTokens: 16000 }).constructor.name).toBe('OpenAIModel');
+ expect(makeKilnModel({ provider: 'bedrock', model: 'global.anthropic.claude-opus-4-8', maxTokens: 16000 }).constructor.name).toBe('BedrockModel');
+ expect(makeKilnModel({ provider: 'openrouter', model: 'x-ai/grok-4.3' }).constructor.name).toBe('VercelModel');
+ });
+
+ test('accepts a BYOK apiKey override for the google path', () => {
+ const m = makeKilnModel({ provider: 'google', model: 'gemini-3.5-flash' }, { apiKey: 'byok-override' });
+ expect(m).toBeTruthy();
+ });
+});
diff --git a/agent/providers.ts b/agent/providers.ts
index cbf1b086..062a9559 100644
--- a/agent/providers.ts
+++ b/agent/providers.ts
@@ -9,6 +9,10 @@
* `stream-start` part the OpenRouter provider omits (see stream-start.ts).
*/
import { VercelModel } from '@strands-agents/sdk/models/vercel';
+import { AnthropicModel } from '@strands-agents/sdk/models/anthropic';
+import { OpenAIModel } from '@strands-agents/sdk/models/openai';
+import { GoogleModel } from '@strands-agents/sdk/models/google';
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
import type { Model } from '@strands-agents/sdk';
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import type { LanguageModelV3 } from '@ai-sdk/provider';
@@ -36,3 +40,114 @@ export function makeOpenRouterModel(opts: OpenRouterModelOptions): Model {
...(opts.maxTokens != null ? { maxTokens: opts.maxTokens } : {}),
});
}
+
+// =============================================================================
+// Agnostic model factory — the core-owned successor to Kiln Studio's
+// agent-runtime model-factory. Every Kiln agent consumer (CLI, batch, server,
+// studio) builds its Strands `Model` here, so native-provider construction lives
+// in exactly one place.
+// =============================================================================
+
+/** Strands-native provider vocabulary for the Kiln agent loop. */
+export type KilnAgentProvider = 'anthropic' | 'openai' | 'google' | 'bedrock' | 'openrouter';
+
+/**
+ * Minimal model descriptor `makeKilnModel` needs. Structurally compatible with
+ * the Kiln Studio `ModelDescriptor` (which carries extra `tier`) and with the
+ * output of {@link resolveKilnAgentModel}.
+ */
+export interface KilnModelDescriptor {
+ provider: KilnAgentProvider;
+ /** Concrete model id passed to the underlying SDK (e.g. 'gemini-3.5-flash'). */
+ model: string;
+ /** Output-token budget; applied to anthropic/openai/bedrock (GoogleModel uses its own default). */
+ maxTokens?: number;
+}
+
+export interface MakeKilnModelOptions {
+ /** BYOK / shared key override. Falls back to provider env vars when omitted. */
+ apiKey?: string;
+ /** AWS region for Bedrock. Defaults to AWS_REGION / us-west-2. */
+ region?: string;
+}
+
+const trimmedEnv = (k: string): string | undefined => {
+ const v = process.env[k];
+ return v && v.trim() ? v.trim() : undefined;
+};
+
+/**
+ * Construct a Strands `Model` from a provider+model descriptor — the agnostic
+ * factory the whole Kiln agent path builds on. Native providers (Anthropic /
+ * OpenAI / Google / Bedrock) construct directly from their model subpath;
+ * OpenRouter goes through the Vercel bridge ({@link makeOpenRouterModel} +
+ * `ensureStreamStart`).
+ */
+export function makeKilnModel(desc: KilnModelDescriptor, opts: MakeKilnModelOptions = {}): Model {
+ const maxTokens = desc.maxTokens;
+ switch (desc.provider) {
+ case 'anthropic':
+ return new AnthropicModel({ modelId: desc.model, ...(maxTokens != null ? { maxTokens } : {}) });
+ case 'openai':
+ return new OpenAIModel({ api: 'chat', modelId: desc.model, ...(maxTokens != null ? { maxTokens } : {}) });
+ case 'google':
+ return new GoogleModel({ modelId: desc.model, apiKey: opts.apiKey ?? trimmedEnv('GEMINI_API_KEY') });
+ case 'bedrock':
+ return new BedrockModel({
+ modelId: desc.model,
+ region: opts.region ?? trimmedEnv('AWS_REGION') ?? 'us-west-2',
+ ...(maxTokens != null ? { maxTokens } : {}),
+ });
+ case 'openrouter':
+ return makeOpenRouterModel({
+ modelId: desc.model,
+ ...(opts.apiKey ? { apiKey: opts.apiKey } : {}),
+ ...(maxTokens != null ? { maxTokens } : {}),
+ });
+ default: {
+ const exhaustive: never = desc.provider;
+ throw new Error(`Unsupported Kiln agent provider: ${String(exhaustive)}`);
+ }
+ }
+}
+
+/**
+ * Parse a model-id string into a Strands provider descriptor — the CLI / batch
+ * entry, where only a string is available.
+ *
+ * NOTE: this is deliberately NOT `resolveKilnModelRoute` from `../../llm`. That
+ * resolver speaks the single-shot harness vocabulary (`gemini`/`fal`, no
+ * `google:`/`bedrock:` prefixes) and would route `google:gemini-3.5-flash` to
+ * `anthropic`. The agent path speaks the Strands vocabulary, so it owns its own
+ * tiny resolver.
+ *
+ * google:gemini-3.5-flash -> { google, gemini-3.5-flash }
+ * openrouter:anthropic/claude-x -> { openrouter, anthropic/claude-x }
+ * gemini-3.5-flash -> { google, gemini-3.5-flash }
+ * claude-opus-4-8 -> { anthropic, claude-opus-4-8 }
+ * gpt-5.5 -> { openai, gpt-5.5 }
+ * x-ai/grok-4.3 -> { openrouter, x-ai/grok-4.3 }
+ */
+export function resolveKilnAgentModel(modelId: string): KilnModelDescriptor {
+ const id = modelId.trim();
+ const colon = id.indexOf(':');
+ if (colon > 0) {
+ const prefix = id.slice(0, colon);
+ const rest = id.slice(colon + 1);
+ if (
+ prefix === 'anthropic' ||
+ prefix === 'openai' ||
+ prefix === 'google' ||
+ prefix === 'bedrock' ||
+ prefix === 'openrouter'
+ ) {
+ return { provider: prefix, model: rest };
+ }
+ }
+ // A slash with no explicit prefix is an OpenRouter `vendor/model` id.
+ if (id.includes('/')) return { provider: 'openrouter', model: id };
+ if (id.startsWith('gemini-') || id.startsWith('imagen-')) return { provider: 'google', model: id };
+ if (id.startsWith('gpt-') || id.startsWith('o3') || id.startsWith('o4')) return { provider: 'openai', model: id };
+ // Default: Anthropic (claude-*).
+ return { provider: 'anthropic', model: id };
+}
diff --git a/agent/run.ts b/agent/run.ts
index f284e106..517325b4 100644
--- a/agent/run.ts
+++ b/agent/run.ts
@@ -20,7 +20,7 @@ import { Agent, 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 type { AssetCategory } from '../prompt';
+import type { AssetCategory, AssetStyle } from '../prompt';
import { makeKilnTools, makeKilnEditTools, type SubmitSink, type EditSink, type EditRecord } from './tools';
import { unifiedDiff } from './diff';
import { MetricsCollector, type AgentUsage } from './hooks';
@@ -38,6 +38,8 @@ export interface RunKilnAgentOptions {
prompt: string;
/** Asset category (drives prompt framing). Default 'prop'. */
category?: AssetCategory;
+ /** Optional style template (low-poly / stylized / voxel / detailed / realistic) injected into the user prompt. */
+ style?: AssetStyle;
/** Know-how source: inline system prompt (default) or the kiln-glb skill. */
knowhow?: KilnKnowhow;
/** Absolute path to a SKILL.md dir, required when knowhow='skill'. */
@@ -146,6 +148,7 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAg
mode: 'glb',
category: opts.category ?? 'prop',
includeAnimation: opts.includeAnimation ?? false,
+ ...(opts.style ? { style: opts.style } : {}),
...(opts.existingCode ? { existingCode: opts.existingCode } : {}),
...(opts.originalPrompt ? { originalPrompt: opts.originalPrompt } : {}),
}) +
diff --git a/index.ts b/index.ts
index ad7bc8f5..43ed6e91 100644
--- a/index.ts
+++ b/index.ts
@@ -287,12 +287,24 @@ export interface KilnGenerateOptions {
*/
includeAnimation?: boolean;
/**
- * Abort milliseconds for the underlying SDK query. Defaults to 720_000
- * (12 min) to fit Opus variance on coordinate-heavy prompts.
+ * Abort milliseconds for the underlying single-shot SDK query. Defaults to
+ * 720_000 (12 min). Ignored by the default 'agent' path (the tool loop manages
+ * its own timeouts).
*/
timeoutMs?: number;
- /** Override the Claude model id used for generation. */
+ /**
+ * Override the code model. In the default 'agent' path this is a Strands model
+ * id (e.g. 'google:gemini-3.5-flash', 'anthropic:claude-opus-4-8'); in the
+ * 'single-shot' fallback it is the Claude/harness model id.
+ */
model?: string;
+ /**
+ * Codegen mechanism. 'agent' (default) drives the Strands tool loop
+ * (list -> validate -> render -> submit, Gemini 3.5 Flash default, self-
+ * correcting on render metrics); 'single-shot' uses the legacy emit-and-render
+ * path. Falls back to the `KILN_CODEGEN` env var, then 'agent'.
+ */
+ codegen?: 'agent' | 'single-shot';
}
export interface KilnGenerateOutput {
@@ -304,13 +316,31 @@ export interface KilnGenerateOutput {
meta: KilnCodeMeta;
/** Non-fatal issues (e.g. animation target missing). */
warnings: string[];
+ /** Resolved Strands provider (agent path only) - for honest provenance. */
+ provider?: string;
+ /** Resolved concrete model id (agent path only) - for honest provenance. */
+ model?: string;
+ /** Tools the agent called, in order (agent path only). */
+ toolCalls?: string[];
+ /** Number of agent-loop iterations (agent path only). */
+ steps?: number;
+}
+
+/** Resolve the codegen mechanism: explicit opt > `KILN_CODEGEN` env > 'agent'. */
+function resolveCodegenMode(explicit?: 'agent' | 'single-shot'): 'agent' | 'single-shot' {
+ if (explicit) return explicit;
+ const env = process.env['KILN_CODEGEN']?.trim().toLowerCase();
+ if (env === 'single-shot' || env === 'singleshot' || env === 'single') return 'single-shot';
+ return 'agent';
}
/**
- * End-to-end Kiln generation: call Claude, validate the code, render GLB.
+ * End-to-end Kiln generation: prompt -> code -> rendered GLB.
*
- * Throws on any hard failure (LLM error, invalid code, render failure).
- * Non-fatal issues surface via `warnings`.
+ * Default path is the Strands agent tool loop (Gemini 3.5 Flash); set
+ * `codegen: 'single-shot'` or `KILN_CODEGEN=single-shot` for the legacy
+ * emit-and-render fallback. Throws on any hard failure (LLM error, invalid code,
+ * render failure); non-fatal issues surface via `warnings`.
*/
export async function generate(
prompt: string,
@@ -318,6 +348,30 @@ export async function generate(
): Promise<KilnGenerateOutput> {
const category = opts.category ?? 'prop';
+ // Default: the Strands agent tool loop. Imported lazily so @strands-agents/sdk
+ // never enters the non-agent core module graph (browser/editor bundle safety).
+ if (resolveCodegenMode(opts.codegen) === 'agent') {
+ const { generateKilnAsset } = await import('./agent/generate');
+ const r = await generateKilnAsset({
+ prompt,
+ category,
+ includeAnimation: opts.includeAnimation ?? true,
+ ...(opts.style ? { style: opts.style } : {}),
+ ...(opts.model ? { model: opts.model } : {}),
+ });
+ return {
+ code: r.code,
+ glb: r.glb,
+ meta: r.meta,
+ warnings: r.warnings,
+ provider: r.provider,
+ model: r.model,
+ toolCalls: r.toolCalls,
+ steps: r.steps,
+ };
+ }
+
+ // Fallback (KILN_CODEGEN=single-shot): legacy emit-and-render.
const genResult = await generateKilnCode(
{
prompt,