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
/**
* Model construction helpers for the agnostic Kiln agent.
*
* Native Strands providers (Anthropic/OpenAI/Google/Bedrock) are constructed by
* the caller directly from `@strands-agents/sdk/models/*`. OpenRouter has no
* native Strands provider, so we reach it through the Vercel AI SDK bridge
* (`VercelModel`) wrapping a `LanguageModelV3` from `@openrouter/ai-sdk-provider`
* — with {@link ensureStreamStart} restoring the spec-required leading
* `stream-start` part the OpenRouter provider omits (see stream-start.ts).
* Meta Model API is OpenAI-compatible, but stays its own provider family for
* honest provenance and key/pricing separation.
*/
import { CachePointBlock, TextBlock, type Model, type SystemPrompt } from '@strands-agents/sdk';
import type { LanguageModelV3 } from '@ai-sdk/provider';
import { ensureStreamStart } from './stream-start';
import { splitToolResultImages } from './split-tool-result-images';
const promptCacheSupport = new WeakMap<object, boolean>();
function rememberPromptCache<T extends Model>(model: T, supported: boolean): T {
promptCacheSupport.set(model, supported);
return model;
}
/** OpenRouter's unified reasoning control (@openrouter/ai-sdk-provider chat setting):
* an effort keyword or a hard reasoning-token budget. Passed straight through to
* the provider, which translates per upstream vendor (Anthropic adaptive thinking,
* OpenAI reasoning_effort, ...). */
export type OpenRouterReasoning =
| { effort: 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' }
| { max_tokens: number };
const OPENROUTER_EFFORTS = new Set(['xhigh', 'high', 'medium', 'low', 'minimal', 'none']);
/**
* Map the Kiln descriptor `thinking` control onto OpenRouter's reasoning setting.
* Keywords pass through ('max' — an Anthropic-vocabulary level OpenRouter's type
* doesn't carry — maps to 'xhigh'); positive numbers become a reasoning token
* budget (floored to 1024, matching the Anthropic legacy floor). Unset / 0 / ''
* or an unknown keyword → undefined (send nothing; the OpenRouter/upstream
* default applies — which for Claude Opus 4.8 means reasoning OFF, same as the
* native path).
*
* Numeric budgets retain their explicit token-budget normalization below. Effort
* keywords are passed through independently of maxTokens; provider-specific output
* allocation must not silently lower a user's requested reasoning effort.
*/
export function resolveOpenRouterReasoning(
thinking?: string | number,
maxTokens?: number,
): OpenRouterReasoning | undefined {
if (thinking == null || thinking === '' || thinking === 0) return undefined;
const halfBudget =
maxTokens != null && Number.isFinite(maxTokens) && maxTokens > 0
? Math.floor(maxTokens / 2)
: undefined;
if (typeof thinking === 'number') {
if (!Number.isFinite(thinking) || thinking <= 0) return undefined;
const budget = Math.max(1024, Math.floor(thinking));
if (halfBudget === undefined) return { max_tokens: budget };
// A completion budget too small to host even the 1024 reasoning floor at
// ≤50% means reasoning off beats a guaranteed truncated turn.
if (halfBudget < 1024) return undefined;
return { max_tokens: Math.min(budget, halfBudget) };
}
const raw = thinking.trim().toLowerCase();
if (/^\d+$/.test(raw)) return resolveOpenRouterReasoning(Number.parseInt(raw, 10), maxTokens);
const effort = raw === 'max' ? 'xhigh' : raw;
if (!OPENROUTER_EFFORTS.has(effort)) return undefined;
return { effort: effort as Extract<OpenRouterReasoning, { effort: string }>['effort'] };
}
export interface OpenRouterModelOptions {
/** OpenRouter model id, e.g. 'x-ai/grok-4.3'. */
modelId: string;
/** API key. Falls back to OPENROUTER_API_KEY. */
apiKey?: string;
/** Max output tokens. */
maxTokens?: number;
/** Unified reasoning control (effort keyword or token budget). */
reasoning?: OpenRouterReasoning;
/** Move tool-result images to a follow-up user message instead of leaving
* them inline (see split-tool-result-images.ts). Together's hosting of
* Thinking Machines' Inkling rejects images embedded in a `tool` message
* outright; other OpenRouter models don't need this. Model-scoped by the
* caller (see the 'openrouter' case below), default false. */
splitToolResultImages?: boolean;
/** Set OpenRouter's top-level `cache_control: {type:'ephemeral'}` directive,
* which turns on Anthropic AUTOMATIC prompt caching for the request — the
* upstream picks the breakpoints, so the stable tools+system prefix is cached
* without us placing any block. Anthropic-hosted models only (the provider
* documents it as such); harmless-but-pointless elsewhere, so callers gate it
* on the slug's vendor segment (see the 'openrouter' case below).
*
* This is a DIFFERENT mechanism from {@link toCachedSystemPrompt}'s explicit
* `CachePointBlock`, and the two must not be conflated: the Vercel bridge
* drops cache-point blocks outright (@strands-agents/sdk vercel.js), which is
* exactly why the OpenRouter fix lives here in request settings instead. */
promptCache?: boolean;
/** OpenRouter provider routing. `throughput` preserves the requested model and
* all generation parameters while avoiding the router's price-first default,
* which is a poor fit for a serial interactive tool loop. */
providerSort?: 'price' | 'throughput' | 'latency';
}
/**
* Build a Strands `Model` for an OpenRouter model id, with the stream-start fix
* applied so the Strands agent loop completes correctly.
*/
export async function makeOpenRouterModel(opts: OpenRouterModelOptions): Promise<Model> {
const [{ VercelModel }, { createOpenRouter }] = await Promise.all([
import('@strands-agents/sdk/models/vercel'),
import('@openrouter/ai-sdk-provider'),
]);
const openrouter = createOpenRouter({ apiKey: opts.apiKey ?? process.env['OPENROUTER_API_KEY'] });
let provider = ensureStreamStart(
openrouter.chat(opts.modelId, {
...(opts.reasoning ? { reasoning: opts.reasoning } : {}),
...(opts.promptCache ? { cache_control: { type: 'ephemeral' } } : {}),
...(opts.providerSort ? { provider: { sort: opts.providerSort } } : {}),
}) as LanguageModelV3,
);
if (opts.splitToolResultImages) provider = splitToolResultImages(provider);
return rememberPromptCache(
new VercelModel({
provider,
...(opts.maxTokens != null ? { maxTokens: opts.maxTokens } : {}),
}),
false,
);
}
// =============================================================================
// 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'
| 'meta';
/**
* 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/google (Gemini's
* API default is 65,536 — omit to keep it) and to openrouter (where it also
* bounds the reasoning clamp in {@link resolveOpenRouterReasoning}). */
maxTokens?: number;
/**
* Reasoning/thinking control. Honored by the `anthropic` provider (shapes
* below), by `openrouter` (mapped onto OpenRouter's unified `reasoning`
* setting via {@link resolveOpenRouterReasoning} — so OpenRouter-hosted Claude
* twins behave like the native transport), and by `google` (effort keywords
* map to Gemini `thinkingConfig.thinkingLevel`; numbers are ignored). Other
* providers ignore it.
*
* - Effort keyword (`'low' | 'medium' | 'high'`, passed through verbatim) →
* `thinking: {type:'adaptive'}` + `output_config: {effort}` — the
* Fable-5-family shape. These models think adaptively BY DEFAULT (verified
* live: reasoning blocks interleave with kiln tool calls on a plain
* request); the keyword only tunes how hard.
* - Number → legacy `thinking: {type:'enabled', budget_tokens}` plus the
* interleaved-thinking beta, for pre-adaptive Claude models. Fable 5
* REJECTS this shape with a 400 (verified live 2026-06-11).
*
* Unset falls back to the `KILN_THINKING` env (read at call time); 0 / ''
* forces default behavior even when the env is set. Default: send nothing —
* the API default, which on Fable 5 is adaptive thinking at default effort.
*/
thinking?: string | 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?.trim() ? v.trim() : undefined;
};
const META_MODEL_API_BASE_URL = 'https://api.meta.ai/v1';
function metaApiKey(opts: MakeKilnModelOptions): string | undefined {
return (
opts.apiKey ??
trimmedEnv('MODEL_API_KEY') ??
trimmedEnv('META_MODEL_API_KEY') ??
trimmedEnv('META_API_KEY')
);
}
/**
* Resolve the Anthropic thinking control: per-call descriptor wins, else the
* `KILN_THINKING` env. Effort keywords map to the adaptive shape (Fable 5
* family); numbers map to the legacy enabled+budget shape (floored to the API
* minimum of 1024, interleaved beta added). Unset / 0 / '' → undefined, i.e.
* send nothing and take the API default.
*/
function isAnthropicAdaptiveOnlyModel(model: string): boolean {
// Every model that REJECTS the legacy `thinking: {type:'enabled', budget_tokens}`
// shape with a 400: Sonnet 5, Fable 5 / Mythos 5 (thinking always-on; verified
// live 2026-06-11), and Opus 4.7/4.8 (budget_tokens removed — Anthropic migration
// guide). Pre-adaptive models (Sonnet/Haiku 4.5 and older) still take the number.
return /^claude-(sonnet-5|fable-5|mythos-5|opus-4-[78])(?:-|$)/.test(model);
}
/**
* Map the descriptor `thinking` control onto Gemini's `thinkingConfig.thinkingLevel`
* vocabulary ('low' | 'medium' | 'high'). 'xhigh'/'max' collapse to 'high';
* numbers and unknown keywords → undefined (send nothing — Gemini's dynamic
* thinking default applies, which is what every Google row ran before this knob
* existed). Deliberately does NOT read KILN_THINKING: that env is Anthropic
* vocabulary and history — only an explicit per-model config reaches Gemini.
*/
function resolveGoogleThinkingLevel(
fromDesc?: string | number,
): 'low' | 'medium' | 'high' | undefined {
if (fromDesc == null || typeof fromDesc === 'number') return undefined;
const raw = fromDesc.trim().toLowerCase();
if (raw === 'xhigh' || raw === 'max') return 'high';
if (raw === 'low' || raw === 'medium' || raw === 'high') return raw;
return undefined;
}
function resolveAnthropicThinking(
model: string,
fromDesc?: string | number,
): { params: Record<string, unknown>; betas?: string[] } | undefined {
const raw = fromDesc ?? trimmedEnv('KILN_THINKING');
if (raw == null || raw === '' || raw === 0) return undefined;
const asNum =
typeof raw === 'number'
? raw
: /^\d+$/.test(String(raw).trim())
? Number.parseInt(String(raw).trim(), 10)
: undefined;
if (asNum !== undefined) {
if (!Number.isFinite(asNum) || asNum <= 0) return undefined;
// Sonnet 5 has adaptive thinking on by default and rejects manual
// extended-thinking budgets. Do not let a global KILN_THINKING number make
// this model fail before the first tool call.
if (isAnthropicAdaptiveOnlyModel(model)) return undefined;
return {
params: { thinking: { type: 'enabled', budget_tokens: Math.max(1024, Math.floor(asNum)) } },
betas: ['interleaved-thinking-2025-05-14'],
};
}
const effort = String(raw).trim().toLowerCase();
if (!/^[a-z]+$/.test(effort)) return undefined;
return { params: { thinking: { type: 'adaptive' }, output_config: { effort } } };
}
/**
* 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;
* Meta uses Strands' OpenAI-compatible Responses adapter against Meta's base URL;
* OpenRouter goes through the Vercel bridge ({@link makeOpenRouterModel} +
* `ensureStreamStart`).
*/
export async function makeKilnModel(
desc: KilnModelDescriptor,
opts: MakeKilnModelOptions = {},
): Promise<Model> {
const maxTokens = desc.maxTokens;
switch (desc.provider) {
case 'anthropic': {
const { AnthropicModel } = await import('@strands-agents/sdk/models/anthropic');
const thinking = resolveAnthropicThinking(desc.model, desc.thinking);
return rememberPromptCache(
new AnthropicModel({
modelId: desc.model,
...(opts.apiKey ? { apiKey: opts.apiKey } : {}),
...(maxTokens != null ? { maxTokens } : {}),
...(thinking ? { params: thinking.params } : {}),
...(thinking?.betas ? { betas: thinking.betas } : {}),
}),
true,
);
}
case 'openai': {
const { OpenAIModel } = await import('@strands-agents/sdk/models/openai');
return rememberPromptCache(
new OpenAIModel({
api: 'chat',
modelId: desc.model,
...(opts.apiKey ? { apiKey: opts.apiKey } : {}),
...(maxTokens != null ? { maxTokens } : {}),
}),
false,
);
}
case 'google': {
const { GoogleModel } = await import('@strands-agents/sdk/models/google');
// H-43/B1: forward the descriptor budget + thinking level into the Gemini
// generationConfig (GoogleModel spreads `params` into the request config).
// Only descriptor-explicit thinking applies — the KILN_THINKING env stays
// Anthropic-only so a global env flip can't perturb Gemini defaults.
const thinkingLevel = resolveGoogleThinkingLevel(desc.thinking);
const googleParams = {
...(maxTokens != null ? { maxOutputTokens: maxTokens } : {}),
...(thinkingLevel ? { thinkingConfig: { thinkingLevel } } : {}),
};
return rememberPromptCache(
new GoogleModel({
modelId: desc.model,
apiKey: opts.apiKey ?? trimmedEnv('GEMINI_API_KEY'),
...(Object.keys(googleParams).length > 0 ? { params: googleParams } : {}),
}),
false,
);
}
case 'bedrock': {
const { BedrockModel } = await import('@strands-agents/sdk/models/bedrock');
return rememberPromptCache(
new BedrockModel({
modelId: desc.model,
region: opts.region ?? trimmedEnv('AWS_REGION') ?? 'us-west-2',
...(maxTokens != null ? { maxTokens } : {}),
}),
true,
);
}
case 'meta': {
const { OpenAIModel } = await import('@strands-agents/sdk/models/openai');
const apiKey = metaApiKey(opts);
if (!apiKey) {
throw new Error(
'Meta Model API key is required. Set MODEL_API_KEY, META_MODEL_API_KEY, or META_API_KEY.',
);
}
return rememberPromptCache(
new OpenAIModel({
modelId: desc.model,
apiKey,
clientConfig: { baseURL: META_MODEL_API_BASE_URL },
params: {
reasoning: { effort: trimmedEnv('KILN_META_REASONING') ?? 'low' },
parallel_tool_calls: false,
},
...(maxTokens != null ? { maxTokens } : {}),
}),
false,
);
}
case 'openrouter': {
// The same descriptor `thinking` control the anthropic case honors, mapped
// onto OpenRouter's unified reasoning setting — so an OpenRouter-hosted
// Claude (e.g. anthropic/claude-opus-4.8) gets its thinking turned on just
// like the native transport would. maxTokens rides along so reasoning can
// never start with a budget ≥ the completion budget (the cycle-2 step-1
// MaxTokens deaths).
const reasoning = resolveOpenRouterReasoning(desc.thinking, maxTokens);
return await makeOpenRouterModel({
modelId: desc.model,
...(opts.apiKey ? { apiKey: opts.apiKey } : {}),
...(maxTokens != null ? { maxTokens } : {}),
...(reasoning ? { reasoning } : {}),
// OpenRouter's default is price-first routing. Kiln's calls are serial
// and user-facing, so choose the same model's highest-throughput healthy
// endpoint. Reasoning, tools, prompts, and completion limits are unchanged.
providerSort: 'throughput',
// Together's Inkling hosting rejects images embedded in a tool-result
// message (verified live 2026-07-19) — see split-tool-result-images.ts.
...(desc.model === 'thinkingmachines/inkling' ? { splitToolResultImages: true } : {}),
// Anthropic automatic prompt caching. Gating on the slug's vendor segment
// is not a heuristic: it IS OpenRouter's routing key, and the capability
// is vendor-scoped by construction (@openrouter/ai-sdk-provider documents
// cache_control as Anthropic-only). Deliberately NOT a ModelDescriptor
// capability field — that type crosses the AgentCore wire, and this value
// is 100% derivable from a model id the engine already holds.
...(desc.model.startsWith('anthropic/') ? { promptCache: true } : {}),
});
}
default: {
const exhaustive: never = desc.provider;
throw new Error(`Unsupported Kiln agent provider: ${String(exhaustive)}`);
}
}
}
// =============================================================================
// A2 — portable system-prompt cache breakpoint
// =============================================================================
/**
* Whether a Strands model's request adapter CONSUMES a block-array system prompt
* with a cache point (verified against @strands-agents/sdk 1.10.0 dist):
*
* - AnthropicModel: a `cachePointBlock` after a `textBlock` becomes
* `cache_control: {type:'ephemeral'}` on that text block (anthropic.js
* `_formatRequest`) — the explicit prompt-caching breakpoint.
* - BedrockModel: system blocks map through `_formatContentBlock`, emitting the
* converse-API `{cachePoint: {type}}` system entry.
* - GoogleModel joins the text blocks and DROPS cache points (Gemini caching is
* implicit); OpenAI warns-and-ignores them; the Vercel bridge only forwards
* text. Those providers get the plain string so nothing changes for them.
*
* This is a statement about the ADAPTER, not about the upstream vendor, so it
* stays false for OpenRouter-hosted Anthropic even though that upstream does
* support caching: emitting a `CachePointBlock` the Vercel bridge discards
* (vercel.js drops them and logs a warning) would be strictly worse than
* today's silent no-op. OpenRouter gets caching through a different seam —
* {@link OpenRouterModelOptions.promptCache}.
*/
export async function modelConsumesSystemPromptCachePoints(model: unknown): Promise<boolean> {
if (!model || typeof model !== 'object' || !('stream' in model)) return false;
const known = promptCacheSupport.get(model);
if (known !== undefined) return known;
// Hosts may inject a native model they constructed themselves. Check its real
// adapter class, without making either optional provider a required dependency.
const [anthropic, bedrock] = await Promise.allSettled([
import('@strands-agents/sdk/models/anthropic'),
import('@strands-agents/sdk/models/bedrock'),
]);
for (const result of [anthropic, bedrock]) {
if (
result.status === 'rejected' &&
!['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'].includes(result.reason?.code)
)
throw result.reason;
}
const supported =
(anthropic.status === 'fulfilled' && model instanceof anthropic.value.AnthropicModel) ||
(bedrock.status === 'fulfilled' && model instanceof bedrock.value.BedrockModel);
promptCacheSupport.set(model, supported);
return supported;
}
/**
* Shape a system prompt for a model: providers whose adapter consumes cache
* points (Anthropic / Bedrock, see {@link modelConsumesSystemPromptCachePoints})
* get `[TextBlock(text), CachePointBlock]` so the WHOLE system prompt lands in
* the provider's prompt cache; everyone else keeps the plain string. Any
* refine/edit directive must already be prepended to `text` — it rides inside
* the cached block, before the cache point.
*/
export async function toCachedSystemPrompt(text: string, model: unknown): Promise<SystemPrompt> {
if (!(await modelConsumesSystemPromptCachePoints(model))) return text;
return [new TextBlock(text), new CachePointBlock({ cacheType: 'default' })];
}
/**
* 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 }
* meta:muse-spark-1.1 -> { meta, muse-spark-1.1 }
*/
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' ||
prefix === 'meta'
) {
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 };
}
/**
* Translate a HARNESS model id (the `llm.resolveKilnModelRoute` vocabulary the
* single-shot path takes via `KILN_MODEL` / `--model`) into a Strands agent
* model id, or null when the id has no agent-path equivalent.
*
* This explicit bridge exists because the two resolvers use different provider
* vocabularies (harness `gemini` vs Strands `google`; harness routes via the
* AI-SDK, Strands via native providers) — DO NOT merge the resolvers: feeding
* a Strands id like `google:gemini-3.5-flash` through the harness resolver (or
* vice versa) misroutes silently. A null return means "no agent route — let
* the single-shot fallback handle this id".
*/
export function harnessIdToAgentModelId(id: string): string | null {
const trimmed = id.trim();
if (!trimmed) return null;
// Already a Strands-form id (provider:model) — pass through untouched.
if (/^(anthropic|openai|google|bedrock|openrouter|meta):/.test(trimmed)) return trimmed;
// OpenRouter `vendor/model` slashes route the same on both paths.
if (trimmed.includes('/')) return `openrouter:${trimmed}`;
if (trimmed.startsWith('claude-')) return `anthropic:${trimmed}`;
if (trimmed.startsWith('gemini-')) return `google:${trimmed}`;
if (trimmed.startsWith('gpt-') || /^o[34]/.test(trimmed)) return `openai:${trimmed}`;
// Unknown family (imagen, embeddings, harness-only aliases): no agent route.
return null;
}