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.

12.5 KB
Raw Blame
import {
  authoringDiagnosticAdvice,
  EXECUTION_REJECTED_ADVICE,
  type AuthoringDiagnostic,
} from './authoring-diagnostic';
import { spawn, type SpawnOptions } from 'node:child_process';
import { existsSync } from 'node:fs';
import { basename } from 'node:path';
import { solidFailureAdvice, type SolidFailureDetails } from './solid-diagnostic';
import { fileURLToPath } from 'node:url';
import type { RenderGlbOptions, RenderResult } from '../render';
import { AssetQaBlockedError } from '../qa/run';
import { assertNoLegacyRuntimePolicy, resolveRequirementsContext } from '../requirements-context';
import { validateMaterialLibraryPayloadAny } from '../material-library-node';
import {
  decodeEvaluatorResultV2,
  assertEvaluatorResultRequirements,
  assertEvaluatorResultMaterialResources,
  evaluatorOutcomeMessage,
  evaluatorOutputLimitAdvice,
  evaluatorSourceBudgetFailure,
  EVALUATOR_REQUEST_VERSION,
  type EvaluatorOutcomeCode,
  type EvaluatorOutputLimitDetails,
  type EvaluatorRequestV2,
  MAX_EVALUATOR_DEADLINE_MS,
  MAX_EVALUATOR_GLB_BYTES,
  MAX_EVALUATOR_REQUEST_BYTES,
  MAX_EVALUATOR_RESPONSE_BYTES,
} from './protocol';

const DEFAULT_DEADLINE_MS = 60_000;
const DEFAULT_MAX_GLB_BYTES = 16 * 1024 * 1024;
const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
const MAX_STDERR_BYTES = 16 * 1024;

export interface EvaluatorSubprocessControls {
  deadlineMs?: number;
  maxGlbBytes?: number;
  maxResponseBytes?: number;
  /** Host cancellation, never serialized into the generated program. */
  signal?: AbortSignal;
  /** Node V8 old-space heap cap, not a total process/native-memory limit. */
  maxHeapMb?: number;
}

export interface EvaluatorProcessLaunch {
  command: string;
  args: string[];
  env: NodeJS.ProcessEnv;
  detached?: boolean;
  /** The worker the launch runs, checked when it fails so the error can name the rebuild. */
  workerFile?: string;
}

export class EvaluatorSubprocessError extends Error {
  readonly code: EvaluatorOutcomeCode;

  constructor(
    code: EvaluatorOutcomeCode,
    message: string,
    readonly diagnostic?: AuthoringDiagnostic,
    readonly solid?: SolidFailureDetails,
    readonly limit?: EvaluatorOutputLimitDetails,
  ) {
    // As EvaluatorPortError: a closed cause's advice, or the generic advice for a bare
    // EXECUTION_REJECTED (decision 24); the wire message itself never changes.
    super(
      diagnostic
        ? `${message} ${authoringDiagnosticAdvice(diagnostic)}${solidFailureAdvice(solid)}`
        : code === 'EXECUTION_REJECTED'
          ? `${message} ${EXECUTION_REJECTED_ADVICE}`
          : `${message}${evaluatorOutputLimitAdvice(limit)}`,
    );
    this.name = 'EvaluatorSubprocessError';
    this.code = code;
  }
}

export function sanitizedEvaluatorEnv(
  source: Record<string, string | undefined> = process.env,
): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = { NODE_ENV: 'production', NO_COLOR: '1' };
  for (const key of ['PATH', 'Path', 'SystemRoot', 'SYSTEMROOT', 'TEMP', 'TMP', 'TZ']) {
    if (source[key] !== undefined) env[key] = source[key];
  }
  return env;
}

function boundedInteger(value: number | undefined, fallback: number, max: number): number {
  const resolved = value ?? fallback;
  if (!Number.isInteger(resolved) || resolved < 1 || resolved > max) {
    throw new EvaluatorSubprocessError('INPUT_INVALID', 'Evaluator controls are invalid.');
  }
  return resolved;
}

function terminateProcess(child: ReturnType<typeof spawn>, detached: boolean): void {
  if (!child.pid || child.killed) return;
  try {
    if (detached && process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL');
    else child.kill('SIGKILL');
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
  }
}

export async function renderGLBViaProcessLaunch(
  code: string,
  options: RenderGlbOptions = {},
  controls: EvaluatorSubprocessControls = {},
  launch?: EvaluatorProcessLaunch,
): Promise<RenderResult> {
  if (controls.signal?.aborted) {
    throw new EvaluatorSubprocessError('CANCELLED', 'Evaluator request was cancelled.');
  }
  assertNoLegacyRuntimePolicy(options);
  const requirements = resolveRequirementsContext(options.requirements);
  if (options.textureResolver) {
    throw new EvaluatorSubprocessError(
      'INPUT_INVALID',
      'Subprocess evaluation does not accept host resolver capabilities.',
    );
  }
  // Named before any worker launch: the host still has the source, and the worker's own
  // decode reports an oversize request as a malformed one (#299).
  const oversizeSource = evaluatorSourceBudgetFailure(code);
  if (oversizeSource) throw new EvaluatorSubprocessError('INPUT_INVALID', oversizeSource);
  const deadlineMs = boundedInteger(
    controls.deadlineMs,
    DEFAULT_DEADLINE_MS,
    MAX_EVALUATOR_DEADLINE_MS,
  );
  const maxGlbBytes = boundedInteger(
    controls.maxGlbBytes,
    DEFAULT_MAX_GLB_BYTES,
    MAX_EVALUATOR_GLB_BYTES,
  );
  const maxResponseBytes = boundedInteger(
    controls.maxResponseBytes,
    DEFAULT_MAX_RESPONSE_BYTES,
    MAX_EVALUATOR_RESPONSE_BYTES,
  );
  if (options.materialResources !== undefined)
    validateMaterialLibraryPayloadAny(options.materialResources);
  const request: EvaluatorRequestV2 = {
    version: EVALUATOR_REQUEST_VERSION,
    requestId: 'render-1',
    operation: 'execute-export-glb',
    code,
    options,
    limits: { maxGlbBytes },
  };
  const requestJson = JSON.stringify(request);
  if (Buffer.byteLength(requestJson, 'utf8') > MAX_EVALUATOR_REQUEST_BYTES) {
    throw new EvaluatorSubprocessError(
      'INPUT_INVALID',
      'Evaluator request exceeds its size limit.',
    );
  }

  const sourceModule = import.meta.url.endsWith('.ts');
  const sdkModule = import.meta.url.endsWith('/subprocess.js');
  const workerPath = fileURLToPath(
    new URL(
      process.versions.bun && sourceModule
        ? './worker.ts'
        : sourceModule || sdkModule
          ? '../../dist/evaluator-worker.mjs'
          : './evaluator-worker.mjs',
      import.meta.url,
    ),
  );
  const maxHeapMb = boundedInteger(controls.maxHeapMb, 512, 4096);
  if (maxHeapMb < 64 || (process.versions.bun && controls.maxHeapMb !== undefined)) {
    throw new EvaluatorSubprocessError(
      'INPUT_INVALID',
      'Heap limits require a Node worker and 64–4096 MiB.',
    );
  }
  const defaultLaunch: EvaluatorProcessLaunch = {
    command: process.execPath,
    args: process.versions.bun ? [workerPath] : [`--max-old-space-size=${maxHeapMb}`, workerPath],
    env: sanitizedEvaluatorEnv(),
    workerFile: workerPath,
  };
  const resolvedLaunch = launch ?? defaultLaunch;
  // A worker that dies at once fails differently by request size and platform; a missing file is
  // the one cause with a known next step, so every failure path asks about it.
  const workerFailure = (message: string) =>
    new EvaluatorSubprocessError(
      'WORKER_FAILED',
      resolvedLaunch.workerFile && !existsSync(resolvedLaunch.workerFile)
        ? `Evaluator worker failed: ${basename(resolvedLaunch.workerFile)} is missing beside the engine. Reinstall Kiln (bun install, then bun run build:runtime), run kiln-init . --repair in the workspace, and restart the MCP session.`
        : message,
    );
  const detached = resolvedLaunch.detached === true;

  return await new Promise<RenderResult>((resolve, reject) => {
    const spawnOptions: SpawnOptions = {
      env: resolvedLaunch.env,
      windowsHide: true,
      stdio: ['pipe', 'ignore', 'pipe', 'pipe'],
      ...(detached ? { detached: true } : {}),
    };
    const child = spawn(resolvedLaunch.command, resolvedLaunch.args, spawnOptions);
    const protocol = child.stdio[3];
    if (!protocol) {
      terminateProcess(child, detached);
      reject(workerFailure('Evaluator worker did not start.'));
      return;
    }
    const chunks: Buffer[] = [];
    let responseBytes = 0;
    let stderrBytes = 0;
    let settled = false;
    const finish = (error?: Error, result?: RenderResult) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      controls.signal?.removeEventListener('abort', abort);
      if (error) reject(error);
      else resolve(result as RenderResult);
    };
    const timer = setTimeout(() => {
      finish(new EvaluatorSubprocessError('DEADLINE_EXCEEDED', 'Evaluator deadline exceeded.'));
      terminateProcess(child, detached);
    }, deadlineMs);
    const abort = () => {
      // Windows/Bun may emit a child error synchronously while killing it.
      // Settle the host outcome first so that event cannot replace cancellation.
      finish(new EvaluatorSubprocessError('CANCELLED', 'Evaluator request was cancelled.'));
      terminateProcess(child, detached);
    };
    const pipeFailed = (error: NodeJS.ErrnoException) => {
      // Killing a worker while stdin is opening can emit EPIPE after cancellation.
      // Always consume pipe errors; only an active request becomes a worker error.
      if (settled) return;
      // Windows/Bun can report a closed input/stderr/protocol pipe before the
      // process close event drains its complete fd3 envelope, and Windows/Node
      // reports writing to a worker that already exited as EOF. Keep the host
      // deadline and cancellation armed, then require exit 0 plus strict decode.
      if (
        [
          'EOF',
          'EPIPE',
          'ECONNRESET',
          'ERR_STREAM_DESTROYED',
          'ERR_STREAM_PREMATURE_CLOSE',
        ].includes(error.code ?? '')
      )
        return;
      finish(workerFailure('Evaluator worker pipe failed.'));
      terminateProcess(child, detached);
    };
    child.stdin?.on('error', pipeFailed);
    protocol.on('error', (error: NodeJS.ErrnoException) => {
      // Bun on Windows can report EBADF on fd3 after delivering its complete
      // reply, before a normal process close. Only that proved case is deferred;
      // close still requires exit 0 and a strictly decoded, complete envelope.
      if (process.platform === 'win32' && process.versions.bun && error.code === 'EBADF') return;
      pipeFailed(error);
    });
    child.stderr?.on('error', pipeFailed);
    controls.signal?.addEventListener('abort', abort, { once: true });
    if (controls.signal?.aborted) abort();

    protocol.on('data', (chunk: Buffer) => {
      responseBytes += chunk.byteLength;
      if (responseBytes > maxResponseBytes) {
        finish(
          new EvaluatorSubprocessError(
            'OUTPUT_LIMIT_EXCEEDED',
            'Evaluator output limit exceeded.',
            undefined,
            undefined,
            {
              stage: 'response',
              limitBytes: maxResponseBytes,
              observedBytes: responseBytes,
              atLeast: true,
            },
          ),
        );
        terminateProcess(child, detached);
        return;
      }
      chunks.push(Buffer.from(chunk));
    });
    child.stderr?.on('data', (chunk: Buffer) => {
      stderrBytes = Math.min(MAX_STDERR_BYTES, stderrBytes + chunk.byteLength);
    });
    child.on('error', () => {
      finish(workerFailure('Evaluator worker failed to start.'));
    });
    child.on('close', (exitCode) => {
      if (settled) return;
      if (exitCode !== 0 || chunks.length === 0) {
        finish(workerFailure('Evaluator worker failed.'));
        return;
      }
      try {
        const result = decodeEvaluatorResultV2(
          Buffer.concat(chunks).toString('utf8'),
          maxGlbBytes,
          request.requestId,
        );
        assertEvaluatorResultRequirements(result, requirements);
        assertEvaluatorResultMaterialResources(result, request.options.materialResources);
        if (!result.ok) {
          if (result.error.code === 'QA_BLOCKED' && result.error.qa) {
            finish(
              new AssetQaBlockedError(
                result.error.qa.report,
                result.error.qa.stage,
                result.error.qa.gltfValidation,
              ),
            );
            return;
          }
          finish(
            new EvaluatorSubprocessError(
              result.error.code,
              evaluatorOutcomeMessage(result.error.code),
              result.error.diagnostic,
              result.error.solid,
              result.error.limit,
            ),
          );
          return;
        }
        finish(undefined, result.render);
      } catch {
        finish(new EvaluatorSubprocessError('PROTOCOL_ERROR', 'Evaluator returned invalid data.'));
      }
    });
    if (!settled) child.stdin?.end(requestJson);
  });
}

export async function renderGLBViaSubprocess(
  code: string,
  options: RenderGlbOptions = {},
  controls: EvaluatorSubprocessControls = {},
): Promise<RenderResult> {
  return renderGLBViaProcessLaunch(code, options, controls);
}