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
import type { KilnToolContext } from './tools/registry';
import {
DEFAULT_EVALUATOR_MAX_GLB_BYTES,
DEFAULT_EVALUATOR_MAX_RESPONSE_BYTES,
MAX_EVALUATOR_DEADLINE_MS,
MAX_EVALUATOR_GLB_BYTES,
MAX_EVALUATOR_RESPONSE_BYTES,
type EvaluatorPortV2,
} from './evaluator/protocol';
import { renderGLBViaSubprocess } from './evaluator/subprocess';
import { renderGLBViaIsolatedEvaluator } from './evaluator/isolation';
import { renderGLBInProcess, resolveEvaluatorMode, type RenderGlbOptions } from './render';
import { FileProgramStore } from './program-store-node';
import { createCachedEvaluatorPort, MemoryBuildCache } from './build-cache';
import { resolveGltfExporter } from './community-exporter';
import { FileBuildCache } from './build-cache-node';
import { installedRuntimeIdentity } from './runtime-identity';
import { readFile, stat } from 'node:fs/promises';
import { dirname, isAbsolute, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { Console } from 'node:console';
import { MAX_PROGRAM_BYTES } from './program-store';
import { ApprovedTextureResourceCache, approvedTextureCatalogV1 } from './material-resources';
import { FileWorkspace, localWorkspaceRoot } from './workspace-node';
import { FileLiveReview } from './live-review-node';
import { localProgramStoreDirectory } from './workspace-location';
import { exportWorkspaceProjectBundle } from './project-bundle-node';
export interface LocalExecution {
mode: 'in-process' | 'subprocess' | 'isolated';
terminable: boolean;
deadlineMs?: number;
nodeHeapMb?: number;
maxGlbBytes?: number;
maxResponseBytes?: number;
totalMemoryLimited: false;
cacheScope: 'process' | 'disk' | 'disabled';
cacheBytes?: number;
cacheReason?: string;
/** Installed runtime identity: worker bytes, installed dependencies and Node/platform. */
runtimeIdentity?: string;
/** The dist build identity alone; `.kiln/workspace.json` records the same value. */
buildIdentity?: string;
}
let scope = 0;
/**
* Reads a program file named relative to the workspace root, so a code-mode harness can
* hand Kiln a path instead of quoting a program into an argument. Absolute paths and `..`
* are refused with the rule rather than the root (no local path leaves in an error), and
* the size bound is the program store's.
*/
function workspaceSourceReader(root: string): (file: string) => Promise<string> {
return async (file) => {
const segments = file.split(/[\\/]/u);
if (
!file ||
isAbsolute(file) ||
/^[A-Za-z]:/u.test(file) ||
segments.includes('..') ||
segments.includes('')
)
throw new Error(
'file must name a program inside the workspace, relative to its root: no absolute path and no "..". Use a path such as assets/asset.kiln.js, or pass code or programRef.',
);
const path = resolve(root, file);
const info = await stat(path).catch(() => undefined);
if (!info?.isFile())
throw new Error(
`file ${file} was not found inside the workspace. Check the relative path, or pass code or programRef.`,
);
if (info.size > MAX_PROGRAM_BYTES)
throw new Error(
`file ${file} exceeds the ${MAX_PROGRAM_BYTES / (1024 * 1024)} MiB source limit.`,
);
return readFile(path, 'utf8');
};
}
function integer(
env: Record<string, string | undefined>,
name: string,
fallback: number,
min: number,
max: number,
) {
const value = env[name] === undefined ? fallback : Number(env[name]);
if (!Number.isInteger(value) || value < min || value > max)
throw new Error(`${name} requires an integer from ${min} to ${max}.`);
return value;
}
/**
* The evaluator mode a local CLI/MCP host runs in, without building a host context. A cheap
* offline command such as `kiln validate` needs this one fact and none of the rest, so the
* default lives here rather than being spelled a second time at the call site.
*/
export function localEvaluatorMode(
env: Record<string, string | undefined> = process.env,
): LocalExecution['mode'] {
return resolveEvaluatorMode({ KILN_EVALUATOR_MODE: env.KILN_EVALUATOR_MODE ?? 'subprocess' });
}
/** Local CLI/MCP host defaults; library callers retain explicit evaluator choice. */
export function createLocalToolContext(
base: KilnToolContext = {},
env: Record<string, string | undefined> = process.env,
): KilnToolContext & { localExecution: LocalExecution } {
const workspaceRoot = env.KILN_WORKSPACE
? resolve(env.KILN_WORKSPACE)
: base.programStore instanceof FileProgramStore
? dirname(dirname(base.programStore.directory))
: localWorkspaceRoot(env);
const workspace = base.workspace ?? new FileWorkspace(workspaceRoot, env.KILN_PROJECT);
const projectStore =
base.projectStore ?? (workspace instanceof FileWorkspace ? workspace.projects : undefined);
const liveReview =
base.liveReview ??
(env.KILN_LIVE_REVIEW === 'off'
? undefined
: new FileLiveReview(workspaceRoot, {
transport: 'cli',
workId: env.KILN_WORK_ITEM,
}));
const geometryPolicy = base.geometryPolicy ?? env.KILN_GEOMETRY_POLICY ?? 'warn';
const indexPolicy = base.indexPolicy ?? env.KILN_INDEX_POLICY ?? 'indexed';
if (indexPolicy !== 'indexed' && indexPolicy !== 'asBuilt')
throw new Error('KILN_INDEX_POLICY must be indexed or asBuilt.');
if (!['warn', 'strict'].includes(geometryPolicy))
throw new Error('KILN_GEOMETRY_POLICY must be warn or strict.');
const mode = localEvaluatorMode(env);
const deadlineMs = integer(env, 'KILN_EVALUATOR_TIMEOUT_MS', 60000, 1, MAX_EVALUATOR_DEADLINE_MS);
const heapMb = integer(env, 'KILN_EVALUATOR_HEAP_MB', 512, 64, 4096);
if (mode === 'subprocess' && process.versions.bun && env.KILN_EVALUATOR_HEAP_MB !== undefined) {
throw new Error('KILN_EVALUATOR_HEAP_MB requires the packaged Node runtime.');
}
if (mode !== 'in-process' && ['observe', 'off'].includes(env.KILN_QA_MODE ?? '')) {
throw new Error(
'KILN_QA_MODE overrides are not transported to the local worker. Remove the override or explicitly select trusted KILN_EVALUATOR_MODE=in-process.',
);
}
const optimize = ['auto', 'palette', 'full'].includes(env.KILN_BAKE_OPTIMIZE ?? '')
? (env.KILN_BAKE_OPTIMIZE as RenderGlbOptions['optimize'])
: 'off';
const instance = ['off', 'auto', 'on'].includes(env.KILN_BAKE_INSTANCE ?? '')
? (env.KILN_BAKE_INSTANCE as RenderGlbOptions['instance'])
: 'auto';
// Host-only, like the deadline: no tool argument reaches it.
const maxGlbBytes = integer(
env,
'KILN_EVALUATOR_MAX_GLB_BYTES',
DEFAULT_EVALUATOR_MAX_GLB_BYTES,
1,
MAX_EVALUATOR_GLB_BYTES,
);
const gltfExporter = resolveGltfExporter(env.KILN_GLTF_EXPORTER ?? 'legacy');
// Base64 is 4/3 of the GLB; the rest is room for its review data. 16 MiB gives the default 32.
const maxResponseBytes = Math.min(
MAX_EVALUATOR_RESPONSE_BYTES,
Math.max(DEFAULT_EVALUATOR_MAX_RESPONSE_BYTES, Math.ceil(maxGlbBytes * 1.5) + 8 * 1024 * 1024),
);
// Keep authored diagnostics off the CLI JSON and MCP stdio channels. The
// subprocess already isolates stdout; this sink covers trusted local evaluation.
const diagnosticConsole = new Console({ stdout: process.stderr, stderr: process.stderr });
// Worker protocols do not transport parent resolver capabilities. A fresh cache
// describes their embedded resources without inheriting a parent byte resolver.
const workerTextures = mode === 'in-process' ? undefined : new ApprovedTextureResourceCache();
const evaluatorPort: EvaluatorPortV2 = {
async render(code, options = {}, controls = {}) {
if (controls.signal?.aborted) {
const { EvaluatorPortError } = await import('./evaluator/protocol');
throw new EvaluatorPortError('CANCELLED');
}
if (
options.geometryPolicy !== undefined &&
!['warn', 'strict'].includes(options.geometryPolicy)
)
throw new Error('geometryPolicy must be warn or strict');
const resolved: RenderGlbOptions = {
indexPolicy,
gltfExporter,
optimize,
instance,
...options,
...(workspace.current()?.materialResources.records.length
? { materialResources: workspace.current()!.materialResources }
: {}),
geometryPolicy: geometryPolicy === 'strict' ? 'strict' : (options.geometryPolicy ?? 'warn'),
};
if (mode === 'in-process') {
const result = await renderGLBInProcess(code, { ...resolved, diagnosticConsole });
if (controls.signal?.aborted) {
const { EvaluatorPortError } = await import('./evaluator/protocol');
throw new EvaluatorPortError('CANCELLED');
}
return result;
}
const limits = { deadlineMs, maxGlbBytes, maxResponseBytes, ...controls };
try {
if (mode === 'isolated') return await renderGLBViaIsolatedEvaluator(code, resolved, limits);
return await renderGLBViaSubprocess(code, resolved, {
...limits,
...(!process.versions.bun ? { maxHeapMb: heapMb } : {}),
});
} catch (error) {
// The worker returns only a closed cause; the host still has the source.
const { withSourceCheck } = await import('./evaluator/source-check');
throw withSourceCheck(error, code);
}
},
};
const localExecution: LocalExecution = {
mode,
terminable: mode !== 'in-process',
...(mode !== 'in-process' ? { deadlineMs } : {}),
...(mode === 'subprocess' && !process.versions.bun ? { nodeHeapMb: heapMb } : {}),
...(mode !== 'in-process' ? { maxGlbBytes, maxResponseBytes } : {}),
totalMemoryLimited: false,
cacheScope: 'process',
};
return {
...base,
workspace,
projectStore,
projectBundleReader:
base.projectBundleReader ??
(workspace instanceof FileWorkspace && base.assetLibrary
? (projectId, revisionId, profile) =>
exportWorkspaceProjectBundle(workspace, base.assetLibrary!, projectId, {
revisionId,
profile,
})
: undefined),
materialLibrary:
base.materialLibrary ??
(workspace instanceof FileWorkspace ? workspace.materials : undefined),
liveReview,
reviewStore:
base.reviewStore ?? (liveReview instanceof FileLiveReview ? liveReview : undefined),
approvedTextureResources: () => approvedTextureCatalogV1({ cache: workerTextures }),
geometryPolicy: geometryPolicy as 'warn' | 'strict',
indexPolicy,
programStore: base.programStore ?? new FileProgramStore(localProgramStoreDirectory(env)),
readSourceFile: base.readSourceFile ?? workspaceSourceReader(workspaceRoot),
evaluatorPort,
assetBuildOptions: {
gltfExporter,
optimize,
instance,
geometryPolicy,
indexPolicy,
qaMode: env.KILN_QA_MODE ?? 'enforce',
evaluatorMode: mode,
},
buildCache: new MemoryBuildCache(),
evaluatorCacheIdentity: `kiln-local-${process.pid}-${++scope}:${JSON.stringify({ mode, optimize, instance, geometryPolicy, indexPolicy, qa: env.KILN_QA_MODE, deadlineMs, heapMb })}`,
localExecution,
};
}
/** Packaged Node provenance is independent of reuse; non-disk hosts scan on first save. */
export async function createPackagedLocalToolContext(
base: KilnToolContext = {},
env: Record<string, string | undefined> = process.env,
installationRoot = fileURLToPath(new URL('../', import.meta.url)),
): Promise<KilnToolContext & { localExecution: LocalExecution }> {
const context = createLocalToolContext(base, env);
const managed = () => {
const identity = context.evaluatorCacheIdentity;
const cached = createCachedEvaluatorPort(context.evaluatorPort!, {
cache: context.buildCache!,
identity: () => (typeof identity === 'function' ? identity() : identity),
});
// Normalize host defaults before keying, so tools and CLI exports share a build.
context.evaluatorPort = {
render: (code, options, controls) =>
cached.render(
code,
{
...options,
indexPolicy: options?.indexPolicy ?? context.indexPolicy,
...(context.workspace?.current()?.materialResources.records.length
? { materialResources: context.workspace.current()!.materialResources }
: {}),
geometryPolicy:
context.geometryPolicy === 'strict'
? 'strict'
: (options?.geometryPolicy ?? context.geometryPolicy),
},
controls,
),
};
context.evaluatorCacheManaged = true;
return context;
};
const policy = env.KILN_BUILD_CACHE ?? 'disk';
if (!['disk', 'memory', 'off'].includes(policy))
throw new Error('KILN_BUILD_CACHE must be disk, memory, or off.');
const packagedNode =
!process.versions.bun &&
!import.meta.url.endsWith('.ts') &&
context.localExecution.mode === 'subprocess';
let pendingIdentity: ReturnType<typeof installedRuntimeIdentity> | undefined;
const identityForHost = () =>
(pendingIdentity ??= installedRuntimeIdentity(installationRoot).then((identity) => {
if (identity.identity) {
context.localExecution.runtimeIdentity = identity.identity;
context.localExecution.buildIdentity = identity.buildIdentity;
} else context.localExecution.cacheReason = identity.reason;
return identity;
}));
if (packagedNode) {
context.prepareBuildProvenance = async () => {
await identityForHost();
};
}
if (policy === 'off' || base.cacheEvaluations === false) {
context.cacheEvaluations = false;
context.localExecution.cacheScope = 'disabled';
return context;
}
if (policy === 'memory') return managed();
if (!packagedNode) {
context.localExecution.cacheReason =
'Disk reuse requires the packaged Node subprocess evaluator; this host uses process memory.';
return managed();
}
const identity = await identityForHost();
if (!identity.identity) {
context.localExecution.cacheReason = identity.reason;
return managed();
}
const cacheBytes = integer(env, 'KILN_BUILD_CACHE_MB', 128, 0, 1024) * 1024 * 1024;
const store = context.programStore;
const directory = resolve(
env.KILN_BUILD_CACHE_DIR ??
join(
store instanceof FileProgramStore ? dirname(store.directory) : '.kiln',
'cache',
'builds',
),
);
context.buildCache = new FileBuildCache(directory, cacheBytes);
context.evaluatorCacheIdentity = `${identity.identity}:${JSON.stringify({
execution: context.localExecution,
optimize: env.KILN_BAKE_OPTIMIZE ?? 'off',
instance: env.KILN_BAKE_INSTANCE ?? 'auto',
qa: env.KILN_QA_MODE ?? 'enforce',
geometryPolicy: context.geometryPolicy,
indexPolicy: context.indexPolicy,
timezone: env.TZ,
...(env.KILN_GLTF_EXPORTER === 'three' ? { gltfExporter: 'three' } : {}),
})}`;
context.localExecution = {
...context.localExecution,
cacheScope: 'disk',
cacheBytes,
runtimeIdentity: identity.identity,
buildIdentity: identity.buildIdentity,
};
return managed();
}