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.

37.1 KB
Raw Blame
#!/usr/bin/env node
/**
 * Human and script entry point: render programs, import/export source revisions,
 * or run the optional model-driven generation loop. Rendering a GLB and its views
 * shares one evaluation through the program-aware registry.
 */
import { open, readFile } from 'node:fs/promises';
import { resolve as resolvePath, extname } from 'node:path';

import { writeDestinationAtomic, writeNewDestinationsAtomic } from './cli-output';
import { isDirectEntry } from './direct-entry';
import { createPackagedLocalToolContext, localEvaluatorMode } from './local-runtime';
import { createKilnProgramToolRegistry, type KilnToolContext } from './tools/registry';
import { createKilnSourceDef } from './tools/programs';
import { BACKDROP_IDS, isBackdropId, type BackdropId } from './views/background';
import { resolveRenderMode, buildRenderPort, describeDrawnBy } from './cli-render-mode';
import type { RenderMode } from './cli-render-mode';
import type { ReviewDetail } from './tools/review-detail';
import { localProgramStore } from './program-store-node';
import { retainProgram, programRefPattern } from './program-store';
import { observeWorkspaceOperation } from './tools/workspace';
import { cliWorkspaceSelection, readMaterialDependencies } from './workspace-cli';
import type { WorkspaceSelection } from './workspace';
import { ASSET_USAGE } from './asset-cli';
import { PROJECT_USAGE } from './project-cli';
import { REVIEW_USAGE } from './review-cli';
import { SERVICE_USAGE } from './service-cli';
import { applyJsonOption, JSON_OPTION_MESSAGE } from './cli-json';
import { DISCOVERY_USAGE } from './discovery-cli';
import { ANIMATION_USAGE } from './animation-cli';
import { EDIT_USAGE } from './edit-cli';
import { INSPECT_USAGE } from './inspect-cli';
import { CATEGORY_MIGRATION_MESSAGE, readHostRequirementsFile } from './requirements-file';
import type { RequirementsBinding } from './requirements-store';
import type { RenderResult } from './render';
import { createGenerationCallBudget } from './agent/call-budget';
import { assertNodeRuntime } from './runtime-support.mjs';
import { ENGINE_VERSION } from './engine-identity';

const USAGE = `kiln — vision-in-the-loop 3D asset generation

USAGE
  kiln render <program.js|ref> [options]     execute a Kiln program (offline, no key)
  kiln validate <program.js|ref> [--json]    kiln_validate: syntax and sandbox check, no build
  kiln generate "<prompt>"  [options]    author a program with a model, then render
  kiln source <file.js>                 save a source snapshot and print its programRef
  kiln source <programRef> --out file.js export a revision without model transcription
  kiln source <file.js|ref> --json       the kiln_source result: one page of exact source
  kiln edit <programRef> --edits <json>  anchored source edits; returns a new revision
  kiln discover [options]               ranked helpers, recipes and host capabilities
  kiln migrate intent|manifest <file>   explicit legacy conversion review (see --help)
  kiln animation <program.js|ref> [options]  review sampled motion of an exported clip
  kiln inspect <program.js|ref> [options]    close-up views and surface/anchor measurements
  kiln service status|start|stop|reprobe  the shared GPU render service (see below)
  kiln --version                        print the installed Kiln version

OPTIONS
  --out <path>            GLB output path            (default: out.glb)
  --views <path>          contact sheet PNG path     (default: none)
  --capture <file.json>  camera recipe for --views  (max 1 MiB); output "separate"
                         writes <views stem>.shot-01.png, ... instead of one sheet
  --backdrop <id>         neutral | dark | light     (default: neutral)
  --render <mode>         auto | cpu | gpu           (default: auto)
  --render-port <url>     remote GPU render service
  --model <id>            model id for generate      (default: env KILN_MODEL)
  --max-steps <n>         agent step cap, 0 = off    (default: 0)
  --requirements <json>  explicit host binding (optional; default neutral)
  --project <id>         project configuration and pinned material dependencies
  --project-revision <r> exact project revision (default: current)
  --no-project          standalone authoring, overriding KILN_PROJECT
  --materials <json>    exact material dependency pins, with or without a project
  --json                 render: one JSON receipt, no embedded image or GLB bytes
                         source: kiln_source JSON, first 8000 characters by default;
                         with --out, a receipt naming the written file
                         export, discover, inspect, animation and service
                         status|reprobe print receipts; commands that print
                         JSON already accept it; generate and view refuse it
  --detail <level>       render --json: lean | compact | full QA detail (default: compact)
  --strict-budget        render: exit 1 when a defineBudget tier fails (advisory otherwise)
  --offset <n>           source --json: page start; pass the returned nextOffset
  --limit <n>            source --json: page size in characters (1-16000)
  --query <text>         source --json: find literal text at or after --offset
  -h, --help              this message

EXPORT ENVIRONMENT
  KILN_INDEX_POLICY      indexed (default) | asBuilt (requires optimization off)

EXAMPLES
  kiln render my-asset.kiln.js --out asset.glb --views sheet.png
  kiln generate "a weathered wooden crate" --out crate.glb --views sheet.png
  kiln render my-asset.kiln.js --render cpu --views sheet.png
  kiln render p_RETURNED_HANDLE --capture cameras.json --views chosen.png
  kiln render my-asset.kiln.js --views sheet.png --backdrop light
`;

interface Args extends WorkspaceSelection {
  command: string | undefined;
  positional: string[];
  out: string | undefined;
  views: string | undefined;
  capture: string | undefined;
  captureRecipe?: unknown;
  backdrop: BackdropId | undefined;
  render: RenderMode;
  renderPort: string | undefined;
  model: string | undefined;
  maxSteps: number;
  requirementsFile?: string;
  requirements?: RequirementsBinding;
  noProject?: boolean;
  materialsFile?: string;
  /** source --json paging, passed through to the shared kiln_source definition. */
  offset?: string;
  limit?: string;
  query?: string;
  /** render --json: the shared result detail; compact unless asked otherwise. */
  detail?: ReviewDetail;
  /** render: a failing defineBudget tier makes the exit code non-zero. */
  strictBudget?: boolean;
  help: boolean;
  json: boolean;
}

export function parseArgs(argv: readonly string[]): Args {
  let renderOption: RenderMode | undefined;
  const args: Args = {
    command: undefined,
    positional: [],
    out: undefined,
    views: undefined,
    capture: undefined,
    backdrop: undefined,
    render: 'auto',
    renderPort: undefined,
    model: process.env['KILN_MODEL'],
    maxSteps: 0,
    help: false,
    json: false,
  };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i]!;
    const next = (): string => {
      const v = argv[++i];
      if (v === undefined) throw new Error(`${a} requires a value`);
      return v;
    };
    switch (a) {
      case '-h':
      case '--help':
        args.help = true;
        break;
      case '--out':
        args.out = next();
        break;
      case '--strict-budget':
        args.strictBudget = true;
        break;
      case '--json':
        args.json = true;
        break;
      case '--detail': {
        const level = next();
        if (level !== 'lean' && level !== 'compact' && level !== 'full')
          throw new Error(`--detail must be lean, compact or full (got ${level})`);
        args.detail = level;
        break;
      }
      case '--views':
        args.views = next();
        break;
      case '--capture':
        args.capture = next();
        break;
      case '--backdrop': {
        const id = next();
        if (!isBackdropId(id))
          throw new Error(`--backdrop must be one of ${BACKDROP_IDS.join(', ')} (got ${id})`);
        args.backdrop = id;
        break;
      }
      case '--render':
        renderOption = resolveRenderMode(next());
        break;
      case '--render-port':
        args.renderPort = next();
        break;
      case '--model':
        args.model = next();
        break;
      case '--category':
        throw new Error(CATEGORY_MIGRATION_MESSAGE);
      case '--requirements':
        args.requirementsFile = next();
        break;
      case '--project':
        args.projectId = next();
        break;
      case '--project-revision':
        args.projectRevision = next();
        break;
      case '--no-project':
        args.noProject = true;
        break;
      case '--materials':
        args.materialsFile = next();
        break;
      case '--offset':
        args.offset = next();
        break;
      case '--limit':
        args.limit = next();
        break;
      case '--query':
        args.query = next();
        break;
      case '--max-steps': {
        const n = Number(next());
        // Zero is the documented "no cap" value, so it has to be accepted here
        // as well as being the default -- rejecting it would leave a user who
        // read the help text unable to type what it told them.
        if (!Number.isInteger(n) || n < 0)
          throw new Error('--max-steps must be a non-negative integer (0 = no cap)');
        args.maxSteps = n;
        break;
      }
      default:
        if (a.startsWith('--category=')) throw new Error(CATEGORY_MIGRATION_MESSAGE);
        if (a.startsWith('-')) throw new Error(`unknown option: ${a}`);
        if (args.command === undefined) args.command = a;
        else args.positional.push(a);
    }
  }
  args.render = resolveRenderMode(renderOption);
  Object.assign(args, cliWorkspaceSelection(args.projectId, args.projectRevision, args.noProject));
  return args;
}

/** Read a bounded recipe and validate the same capture schema used by MCP. */
async function readCaptureRecipe(args: Args): Promise<unknown> {
  if (!args.views) throw new Error('--capture requires --views <output.png>.');
  if (args.command !== 'render' && args.command !== 'generate')
    throw new Error('--capture is supported by render and generate only.');
  const limit = 1024 * 1024;
  const file = await open(resolvePath(args.capture!), 'r');
  let capture: unknown;
  try {
    const info = await file.stat();
    if (!info.isFile() || info.size > limit)
      throw new Error('--capture requires a JSON file no larger than 1 MiB.');
    const buffer = Buffer.alloc(limit + 1);
    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
    if (bytesRead > limit) throw new Error('--capture JSON exceeds 1 MiB.');
    try {
      capture = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
    } catch {
      throw new Error('--capture requires valid JSON.');
    }
  } finally {
    await file.close();
  }
  const def = createKilnProgramToolRegistry().find((d) => d.name === 'kiln_render');
  if (!def) throw new Error('kiln_render is missing from the MCP tool surface');
  // Schema validation needs a selector but does not resolve or write this placeholder.
  def.inputSchema.parse({ programRef: `sha256:${'0'.repeat(64)}`, capture });
  return capture;
}

/**
 * `--backdrop` is the one capture field worth a flag of its own: it is the
 * question "same sheet, other backdrop", which should not require writing a
 * recipe file. It rides in the same `capture` object every surface takes, so
 * the CLI, MCP and API resolve it through one path, and it overrides a recipe's
 * own `backdrop` so a shared recipe can be re-run on another backdrop unedited.
 */
function applyBackdrop(args: Args): unknown {
  if (args.backdrop === undefined) return args.captureRecipe;
  if (!args.views) throw new Error('--backdrop requires --views <output.png>.');
  if (args.command !== 'render' && args.command !== 'generate')
    throw new Error('--backdrop is supported by render and generate only.');
  const recipe = (args.captureRecipe ?? {}) as Record<string, unknown>;
  return { ...recipe, backdrop: args.backdrop };
}

/**
 * Render one program to GLB bytes plus, optionally, the contact sheet.
 * Shared by both commands so `generate` and `render` cannot diverge in output.
 */
interface RenderCliReceipt extends Record<string, unknown> {
  programRef?: string;
  /** `shot` names the capture shot a separate-output image shows. */
  files: { kind: 'glb' | 'image'; path: string; bytes: number; shot?: string }[];
}

/** Commands of this parser whose --json output includes failures, as `{ ok: false, error, files }`. */
function jsonCommand(command: string | undefined): boolean {
  return command === 'render' || command === 'source' || command === 'validate';
}

function jsonRenderFailure(error: unknown, receipt: RenderCliReceipt = { files: [] }): void {
  console.log(
    JSON.stringify({
      ...receipt,
      ok: false,
      error: (error instanceof Error ? error.message : String(error)).slice(0, 2048),
    }),
  );
}

async function emit(
  code: string,
  args: Args,
  context: KilnToolContext,
  reviewed?: RenderResult,
  receipt: RenderCliReceipt = { files: [] },
): Promise<Record<string, unknown>> {
  let captured: Record<string, unknown> = {};
  const log = (message: string) => {
    if (!args.json) console.log(message);
  };
  context.programStore ??= localProgramStore();
  const programRef = await retainProgram(context.programStore, code);
  receipt.programRef = programRef;
  log(`  programRef ${programRef}`);
  const result =
    reviewed ??
    (await context.evaluatorPort!.render(code, {
      optimize: 'off',
      requirements: context.requirements,
    }));
  try {
    context.liveReview?.artifact(code, result);
  } catch {
    /* Optional observation. */
  }
  const project = context.workspace?.current()?.project;
  Object.assign(receipt, {
    ...(project ? { projectId: project.projectId, projectRevision: project.revisionId } : {}),
    requirements: result.requirements,
    ...(result.buildCache ? { buildCache: result.buildCache } : {}),
    tris: result.tris,
    ...(result.meta.indexBuffers ? { indexBuffers: result.meta.indexBuffers } : {}),
    bounds: result.integrationManifest.bounds,
    ...(result.integrationManifest.levelsOfDetail
      ? { levelsOfDetail: result.integrationManifest.levelsOfDetail }
      : {}),
    ...(result.integrationManifest.hiddenNodes
      ? { hiddenNodes: result.integrationManifest.hiddenNodes }
      : {}),
    ...(result.integrationManifest.vertexAttributes
      ? { vertexAttributes: result.integrationManifest.vertexAttributes }
      : {}),
    budget: result.integrationManifest.budget ?? { status: 'none', tiers: [] },
    ...(result.integrationManifest.materialAdvice
      ? { materialAdvice: result.integrationManifest.materialAdvice }
      : {}),
    ...(result.integrationManifest.palette ? { palette: result.integrationManifest.palette } : {}),
    artifactGlbSha256: result.artifactGlbSha256,
    glbBytes: result.glb.length,
    warnings: result.warnings,
    qaReport: result.meta.qaReport,
  });
  log(
    `  requirements ${result.requirements.policyHash}${result.requirements.binding ? ` (${result.requirements.binding.taskId}/${result.requirements.binding.lineageId}, revision ${result.requirements.binding.revision})` : ' (neutral)'}`,
  );
  const qa = result.meta.qaReport;
  if (qa && typeof qa === 'object' && 'acceptance' in qa) log(`  QA ${qa.acceptance}`);
  if (result.buildCache)
    log(`  build ${result.buildCache.hit ? 'reused' : 'created'} ${result.buildCache.key}`);
  // Only write a GLB when one was asked for, or when it is the sole output —
  // `--views sheet.png` alone should not litter the working directory.
  const out = args.out ?? (args.views ? undefined : 'out.glb');
  if (out) {
    await writeDestinationAtomic(resolvePath(out), result.glb);
    receipt.files.push({ kind: 'glb', path: resolvePath(out), bytes: result.glb.length });
    log(`  ${out}  ${result.tris} tris  ${(result.glb.length / 1024).toFixed(1)} KB`);
  } else {
    log(`  ${result.tris} tris  ${(result.glb.length / 1024).toFixed(1)} KB`);
  }
  const bounds = result.integrationManifest.bounds;
  if (bounds) {
    const size = bounds.size ?? bounds.max;
    if (Array.isArray(size)) {
      log(`  bounds  ${size.map((n) => Number(n).toFixed(2)).join(' x ')} m`);
    }
  }
  // Tris and bounds above are LOD0's; each chain lists every level's count.
  for (const chain of result.integrationManifest.levelsOfDetail ?? []) {
    const coverage = chain.screenCoverage
      ? `  screen coverage ${chain.screenCoverage.join(' / ')}`
      : '';
    log(
      `  LOD ${chain.path}  ${chain.levels.map((level) => level.triangles).join(' / ')} tris${coverage}`,
    );
  }
  // Tris and bounds count what draws; a subtree KHR_node_visibility hides is listed apart.
  for (const node of result.integrationManifest.hiddenNodes ?? [])
    log(`  hidden ${node.path}  ${node.triangles} tris (not drawn, not in the headline)`);
  // A declared budget, tier by tier: advisory unless --strict-budget.
  const budget = result.integrationManifest.budget;
  if (budget) {
    const tiers = budget.tiers
      .map(
        (tier) =>
          `${tier.tier} ${tier.measured.triangles}/${tier.declared.triangles ?? '-'} tris${tier.declared.draws === undefined ? '' : ` ${tier.measured.draws}/${tier.declared.draws} draws`} ${tier.status}`,
      )
      .join('; ');
    const materials = (budget.materials ?? [])
      .map((check) => `${check.limit} ${check.measured}/${check.declared} ${check.status}`)
      .join('; ');
    log(`  budget ${budget.status}  ${[tiers, materials].filter(Boolean).join('; ')}`);
  }
  // Reference-tier material notes: optional advice, never a declared budget.
  for (const note of result.integrationManifest.materialAdvice ?? [])
    log(
      `  material note (advisory, ${note.reference})  ${note.measurement.name} ${note.measurement.actual}; reference ${note.measurement.reference}`,
    );
  // A declared palette: advisory, off-palette materials farthest first.
  const palette = result.integrationManifest.palette;
  if (palette)
    log(
      `  palette ${palette.status}  ${palette.checkedMaterials} material(s), ${palette.offPalette.length} off palette (delta E > ${palette.threshold})`,
    );
  // Custom vertex attributes the GLB preserves, such as baked _EDGE and _CAVITY.
  for (const attribute of result.integrationManifest.vertexAttributes ?? [])
    log(`  attribute ${attribute.name} on ${attribute.meshes.length} mesh(es)`);
  if (result.meta.indexBuffers) {
    const buffers = result.meta.indexBuffers;
    log(
      `  index buffers ${buffers.policy}: ${buffers.bufferBytesBefore} -> ${buffers.bufferBytesAfter} geometry payload bytes; ${buffers.primitivesConverted} primitives indexed`,
    );
  }
  for (const w of result.warnings) log(`  warning: ${w}`);

  if (args.views) {
    // The SAME def the MCP surface serves, so the CLI cannot render views through
    // a path the agent never takes, and `--render-port` fires exactly as it does
    // for a host agent.
    // This call already built the exact source above. Review the same artifact.
    const def = createKilnProgramToolRegistry({
      ...context,
      evaluatorPort: { render: async () => result },
    }).find((d) => d.name === 'kiln_render');
    if (!def) throw new Error('kiln_render is missing from the MCP tool surface');
    const output = await def.run({
      programRef,
      ...(args.captureRecipe === undefined ? {} : { capture: args.captureRecipe }),
      // The receipt reaches a model's context like a tool result: the same
      // compact default, with --detail full for the complete report.
      detail: args.detail ?? 'compact',
    });
    captured = output as Record<string, unknown>;
    const failure = output as { ok?: unknown; error?: unknown } | null;
    if (failure?.ok === false && typeof failure.error === 'string' && failure.error.trim()) {
      throw new Error(failure.error.slice(0, 2048));
    }
    // Report what actually drew the pixels, not what was configured. The engine
    // routes to the port only when the scene needs PBR shading, so a GPU that was
    // available and correctly skipped must not be reported as if it had drawn.
    const drawnBy = describeDrawnBy(output, context);
    // Separate capture output is one image per shot, checked first as MCP does.
    // Each lands beside the --views stem; no composite sheet is written.
    const separate = def.mediaMulti?.(output);
    if (separate) {
      const suffix = extname(args.views);
      const stem = suffix ? args.views.slice(0, -suffix.length) : args.views;
      const shots = (output as { cameraShots?: { name?: unknown }[] }).cameraShots;
      for (const [index, png] of separate.pngs.entries()) {
        const view = `${stem}.shot-${String(index + 1).padStart(2, '0')}.png`;
        const shot = shots?.[index]?.name;
        await writeDestinationAtomic(resolvePath(view), png);
        receipt.files.push({
          kind: 'image',
          path: resolvePath(view),
          bytes: png.length,
          ...(typeof shot === 'string' ? { shot } : {}),
        });
        log(`  ${view}${typeof shot === 'string' ? `  ${shot}` : ''}  (${drawnBy})`);
      }
      Object.assign(receipt, separate.json);
    } else {
      const media = def.media?.(output);
      if (!media) throw new Error('kiln_render returned no image');
      await writeDestinationAtomic(resolvePath(args.views), media.png);
      Object.assign(receipt, media.json);
      receipt.files.push({ kind: 'image', path: resolvePath(args.views), bytes: media.png.length });
      log(`  ${args.views}  (${drawnBy})`);
    }
  }
  if (args.json) console.log(JSON.stringify({ ...receipt, ok: true }));
  return { ...captured, ...receipt, ok: true };
}

async function cmdRender(args: Args): Promise<number> {
  const file = args.positional[0] ?? undefined;
  if (!file) {
    if (args.json) jsonRenderFailure('render requires a program path or reference');
    else {
      console.error('render requires a program path\n');
      console.error(USAGE);
    }
    return 2;
  }
  const receipt: RenderCliReceipt = { files: [] };
  let context: KilnToolContext | undefined;
  try {
    const code =
      file.startsWith('sha256:') || programRefPattern.test(file)
        ? await localProgramStore().get(file)
        : await readFile(resolvePath(file), 'utf8');
    context = await createPackagedLocalToolContext({
      ...(await buildRenderPort(args.render, args.renderPort)),
      requirements: args.requirements,
    });
    if (!args.json) console.log(`rendering ${file}`);
    const callContext = context;
    await observeWorkspaceOperation(
      callContext,
      'kiln_render',
      {
        code,
        projectId: args.projectId,
        projectRevision: args.projectRevision,
        materialDependencies: args.materialDependencies,
      },
      () => emit(code, args, callContext, undefined, receipt),
    );
    const budget = (receipt as { budget?: { status?: string } }).budget;
    if (args.strictBudget && budget?.status === 'fail') {
      console.error('render: a defineBudget tier failed (--strict-budget).');
      return 1;
    }
    return 0;
  } catch (error) {
    if (!args.json) throw error;
    jsonRenderFailure(error, receipt);
    return 1;
  } finally {
    try {
      await context?.liveReview?.flush?.();
    } catch {
      /* Observation cannot fail a build. */
    }
  }
}

/** The same kiln_validate definition MCP serves; the source is retained so its ref prints. */
async function cmdValidate(args: Args): Promise<number> {
  const input = args.positional[0];
  if (!input || args.positional.length !== 1) {
    const message = 'validate requires a program path or reference';
    if (args.json) jsonRenderFailure(message);
    else console.error(`${message}\n\n${USAGE}`);
    return 2;
  }
  const store = localProgramStore();
  const isRef = input.startsWith('sha256:') || programRefPattern.test(input);
  // A syntax check builds no host context, but a source finding needs one host fact:
  // whether a render will carry this source to a worker (#299).
  const def = createKilnProgramToolRegistry({
    programStore: store,
    evaluatorTransportsSource: localEvaluatorMode() !== 'in-process',
  }).find((d) => d.name === 'kiln_validate');
  if (!def) throw new Error('kiln_validate is missing from the MCP tool surface');
  const result = (await def.run(
    isRef ? { programRef: input } : { code: await readFile(resolvePath(input), 'utf8') },
  )) as {
    valid: boolean;
    programRef?: string;
    errors: string[];
    warnings: string[];
    issues: { code: string; message: string; fixHint?: string; line?: number }[];
  };
  if (args.json) console.log(JSON.stringify(result));
  else {
    console.log(`${result.valid ? 'valid' : 'invalid'} ${result.programRef ?? input}`);
    const described = new Set<string>();
    for (const issue of result.issues) {
      described.add(issue.message);
      const where = issue.line === undefined ? '' : ` (line ${issue.line})`;
      const hint = issue.fixHint ? ` ${issue.fixHint}` : '';
      console.log(`  error: ${issue.code}${where}: ${issue.message}${hint}`);
    }
    for (const error of result.errors) if (!described.has(error)) console.log(`  error: ${error}`);
    for (const warning of result.warnings) console.log(`  warning: ${warning}`);
  }
  return result.valid ? 0 : 1;
}

async function cmdGenerate(args: Args): Promise<number> {
  assertNodeRuntime('agent');
  const prompt = args.positional.join(' ').trim();
  if (!prompt) {
    console.error('generate requires a prompt\n');
    console.error(USAGE);
    return 2;
  }
  if (!args.model) {
    console.error('no model selected: pass --model <id> or set KILN_MODEL');
    return 2;
  }

  // Imported lazily so `kiln render` never pulls the agent stack (an optional
  // peer) into the process. A missing @strands-agents/sdk must not break the
  // offline path, which is the one the quickstart promises works everywhere.
  // Nonliteral imports keep optional model SDKs outside the offline Node bundle.
  const modules = import.meta.url.endsWith('.ts')
    ? ['./agent/run.ts', './agent/providers.ts']
    : ['./agent-run.mjs', './agent-providers.mjs'];
  let generation: [typeof import('./agent/run'), typeof import('./agent/providers')];
  try {
    generation = await Promise.all([import(modules[0]!), import(modules[1]!)]);
  } catch (error) {
    throw new Error(
      'The optional generation adapter could not load. Use your connected agent with MCP, or install the agent/provider dependencies for kiln generate.',
      { cause: error },
    );
  }
  const [{ runKilnAgent }, { makeKilnModel, resolveKilnAgentModel }] = generation;

  const context = await createPackagedLocalToolContext({
    ...(await buildRenderPort(args.render, args.renderPort)),
    requirements: args.requirements,
  });
  const modelId = args.model;
  const generate = async () => {
    const descriptor = resolveKilnAgentModel(modelId);
    const model = await makeKilnModel(descriptor);

    console.log(`generating "${prompt}"`);
    console.log(`  model ${args.model}  max-steps ${args.maxSteps}  render ${args.render}`);

    const run = await runKilnAgent({
      model,
      prompt,
      ...context,
      generationCallBudget: createGenerationCallBudget(args.maxSteps),
    });

    if (!run.code || !run.artifact) {
      console.error(run.error ?? 'the agent stopped without a reviewed artifact');
      if (run.lastText) console.error(`  last message: ${run.lastText.slice(0, 400)}`);
      return 1;
    }
    console.log(`  ${run.steps} steps, ${run.toolCalls.length} tool calls`);
    // `generate` always writes the GLB: producing an asset is the point of the
    // command, unlike `render`, where `--views` alone is a legitimate request.
    const requestedPath = args.out ?? 'out.glb';
    const partial = run.completion !== 'finished';
    const outPath = partial ? requestedPath.replace(/(?:\.glb)?$/i, '.partial.glb') : requestedPath;
    if (partial) console.error(`partial result: ${run.error ?? 'kiln_finish was not called'}`);
    const views =
      partial && args.views
        ? args.views.slice(0, args.views.length - extname(args.views).length) +
          '.partial' +
          (extname(args.views) || '.png')
        : args.views;
    await emit(run.code, { ...args, out: outPath, views }, context, run.artifact.rendered);

    const source = /\.glb$/i.test(outPath)
      ? outPath.replace(/\.glb$/i, '.kiln.js')
      : `${outPath}.kiln.js`;
    await writeDestinationAtomic(resolvePath(source), run.code);
    console.log(`  ${source}  (the program — edit and re-render it)`);
    return partial ? 2 : 0;
  };
  try {
    return context.workspace
      ? await context.workspace.run(
          {
            projectId: args.projectId,
            projectRevision: args.projectRevision,
            materialDependencies: args.materialDependencies,
          },
          generate,
        )
      : await generate();
  } finally {
    try {
      await context.liveReview?.flush?.();
    } catch {
      /* Optional observation. */
    }
  }
}

function integerOption(name: string, value: string | undefined): number | undefined {
  if (value === undefined) return undefined;
  if (!/^\d+$/.test(value))
    throw new Error(`${name} must be a non-negative integer (got ${value})`);
  return Number(value);
}

async function cmdSource(args: Args): Promise<number> {
  const input = args.positional[0];
  if (!input || args.positional.length !== 1)
    throw new Error('source requires one file path or programRef.');
  const store = localProgramStore();
  const isRef = input.startsWith('sha256:') || programRefPattern.test(input);
  if (args.out && !isRef)
    throw new Error('Use source <programRef> --out <new-file.js> to export a saved revision.');
  if (args.out && (args.offset ?? args.limit ?? args.query) !== undefined)
    throw new Error('--offset, --limit and --query page source --json output, not --out exports.');
  if (isRef && args.out) {
    const code = await store.get(input);
    const path = resolvePath(args.out);
    await writeNewDestinationsAtomic([{ path, data: code }]);
    if (!args.json) console.log(`Saved ${input} to ${args.out}`);
    else
      console.log(
        JSON.stringify({
          ok: true,
          programRef: input,
          files: [{ kind: 'source', path, bytes: Buffer.byteLength(code, 'utf8') }],
        }),
      );
    return 0;
  }
  if (!args.json) {
    if (isRef) process.stdout.write(await store.get(input));
    else console.log(await retainProgram(store, await readFile(resolvePath(input), 'utf8')));
    return 0;
  }
  // A file is saved first, then read back like any retained revision. The output is
  // exactly what kiln_source returns over MCP: one bounded page, continued by nextOffset.
  const programRef = isRef
    ? input
    : await retainProgram(store, await readFile(resolvePath(input), 'utf8'));
  const offset = integerOption('--offset', args.offset);
  const limit = integerOption('--limit', args.limit);
  const result = await createKilnSourceDef(store).run({
    programRef,
    ...(offset === undefined ? {} : { offset }),
    ...(limit === undefined ? {} : { limit }),
    ...(args.query === undefined ? {} : { query: args.query }),
  });
  console.log(JSON.stringify(result));
  return 0;
}

/**
 * Hold the process open until `run()` settles.
 *
 * Every CLI entry awaits `main()` and then sets `process.exitCode`, which assumes
 * the runtime keeps the process alive while that promise is pending. It does not.
 * The loop can go idle while the command is still running: `beforeExit` fires and
 * the process exits 0 having written nothing. Bun reaches that state under load --
 * concurrent `kiln save` runs exit 0 with empty stdout, no stderr and no
 * rejection, which is why it read as a flaky test rather than a broken command. A
 * ref'd timer far in the future costs no wakeups and closes the hole for every
 * runtime and every entry, the generated workspace launcher included, because it
 * wraps `main` itself rather than one call site.
 */
export async function withProcessAlive<T>(run: () => Promise<T>): Promise<T> {
  const held = setInterval(() => undefined, 1 << 30);
  try {
    return await run();
  } finally {
    clearInterval(held);
  }
}

/** Managed renderer processes have their own idle lifetime and detached handles. */
export function main(argv: readonly string[]): Promise<number> {
  return withProcessAlive(() => runMain(argv));
}

async function runMain(argv: readonly string[]): Promise<number> {
  // Before the runtime check, so an unsupported Node can still say which Kiln it found (#202).
  if (argv.length === 1 && argv[0] === '--version') {
    console.log(ENGINE_VERSION);
    return 0;
  }
  try {
    assertNodeRuntime();
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    return 1;
  }
  try {
    argv = applyJsonOption(argv);
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    return 2;
  }
  if (argv[0] === 'edit') return (await import('./edit-cli')).editMain(argv.slice(1));
  if (argv[0] === 'migrate') return (await import('./migration-cli')).migrationMain(argv.slice(1));
  if (argv[0] === 'animation')
    return (await import('./animation-cli')).animationMain(argv.slice(1));
  if (argv[0] === 'inspect') return (await import('./inspect-cli')).inspectMain(argv.slice(1));
  if (argv[0] === 'discover') return (await import('./discovery-cli')).discoveryMain(argv.slice(1));
  if (argv[0] === 'service') return (await import('./service-cli')).serviceMain(argv.slice(1));
  if (argv[0] === 'review') {
    try {
      return await (await import('./review-cli')).reviewMain(argv.slice(1));
    } catch (error) {
      console.error(error instanceof Error ? error.message : String(error));
      return 1;
    }
  }
  if (argv[0] === 'project' || argv[0] === 'material') {
    try {
      return await (await import('./project-cli')).projectMain(argv);
    } catch (error) {
      console.error(error instanceof Error ? error.message : String(error));
      return 1;
    }
  }
  if (
    ['save', 'collections', 'assets', 'asset', 'export', 'textures', 'import', 'view'].includes(
      argv[0] ?? '',
    )
  ) {
    try {
      return await (await import('./asset-cli')).assetMain(argv);
    } catch (error) {
      console.error(error instanceof Error ? error.message : String(error));
      return 1;
    }
  }
  let args: Args;
  try {
    args = parseArgs(argv);
  } catch (err) {
    if (jsonCommand(argv[0]) && argv.includes('--json')) jsonRenderFailure(err);
    else console.error(err instanceof Error ? err.message : String(err));
    return 2;
  }
  if (args.help || !args.command) {
    console.log(
      USAGE +
        DISCOVERY_USAGE +
        EDIT_USAGE +
        ANIMATION_USAGE +
        INSPECT_USAGE +
        ASSET_USAGE +
        PROJECT_USAGE +
        REVIEW_USAGE +
        SERVICE_USAGE,
    );
    return args.help ? 0 : 2;
  }
  try {
    if (
      (args.projectId !== undefined ||
        args.projectRevision !== undefined ||
        args.noProject ||
        args.materialsFile !== undefined) &&
      args.command !== 'render' &&
      args.command !== 'generate'
    )
      throw new Error(
        '--project, --project-revision, --no-project and --materials are supported by render and generate only.',
      );
    if (args.json && !jsonCommand(args.command)) throw new Error(JSON_OPTION_MESSAGE);
    if (
      (args.offset !== undefined || args.limit !== undefined || args.query !== undefined) &&
      !(args.command === 'source' && args.json)
    )
      throw new Error('--offset, --limit and --query are supported by source --json only.');
    if (args.requirementsFile !== undefined) {
      if (args.command !== 'render' && args.command !== 'generate')
        throw new Error('--requirements is supported by render and generate only.');
      args.requirements = await readHostRequirementsFile(args.requirementsFile);
    }
    if (args.capture !== undefined) args.captureRecipe = await readCaptureRecipe(args);
    if (args.materialsFile !== undefined) {
      if (args.command !== 'render' && args.command !== 'generate')
        throw new Error('--materials is supported by render and generate only.');
      args.materialDependencies = await readMaterialDependencies(args.materialsFile);
    }
    args.captureRecipe = applyBackdrop(args);
    switch (args.command) {
      case 'source':
        return await cmdSource(args);
      case 'render':
        return await cmdRender(args);
      case 'validate':
        return await cmdValidate(args);
      case 'generate':
        return await cmdGenerate(args);
      default:
        console.error(`unknown command: ${args.command}\n`);
        console.error(USAGE);
        return 2;
    }
  } catch (err) {
    if (args.json && jsonCommand(args.command)) {
      jsonRenderFailure(err);
      return 1;
    }
    // Expected operator errors — an unreachable GPU, an unreadable program — are
    // messages, not stack traces. KILN_DEBUG=1 restores the trace for real bugs.
    if (process.env['KILN_DEBUG'] && err instanceof Error && err.stack) {
      console.error(err.stack);
    } else {
      console.error(err instanceof Error ? err.message : String(err));
    }
    return 1;
  }
}

if (isDirectEntry(import.meta.url)) {
  main(process.argv.slice(2))
    .then((code) => {
      process.exitCode = code;
    })
    .catch((err: unknown) => {
      console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
      process.exitCode = 1;
    });
}