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.

14.8 KB
Raw Blame
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();
}