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): 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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/sdkimport { 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<RunKilnAgmode: '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.tsindex 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,