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.7 KB
Raw Blame
/** Engine-owned bounded second-stage compiler for canonical world integration. */
import {
  Agent,
  ImageBlock,
  JsonBlock,
  type JSONValue,
  type Message,
  type Tool,
  tool,
} from '@strands-agents/sdk';
import { z } from 'zod';
import { type AgentUsage, type KilnAgentEvent, MetricsCollector } from '../../agent/hooks';
import type { GenerationCallBudget, GenerationCallBudgetReceipt } from '../../agent/call-budget';
import { toCachedSystemPrompt } from '../../agent/providers';
import {
  hashWorldDocumentV2,
  PRESENTATION_MAX_TOTAL_PIXELS_V1,
  parseWorldDocumentV2,
  PlacementModel,
  type Placement,
  type SceneRenderFallbackReceipt,
  type SceneRenderReceipt,
  type SceneRenderPort,
  type SceneRenderResult,
  type WorldDocumentV2,
  validatePresentationReceiptV1,
  validateWorldIntegrationV2,
  worldDocumentV2ToSceneModelJSON,
} from '..';
import { WORLD_INTEGRATION_PROMPT_V2 } from './prompt';
import {
  makeWorldIntegrationToolsV2,
  type MakeWorldIntegrationToolsV2Options,
  type WorldIntegrationToolState,
} from './world-tools';

export interface RunKilnWorldIntegrationOptions
  extends Omit<MakeWorldIntegrationToolsV2Options, 'state'> {
  model: unknown;
  prompt: string;
  world: unknown;
  render: SceneRenderPort;
  agentName?: string;
  onEvent?: (event: KilnAgentEvent) => void;
  extraTools?: unknown[];
  /** Explicit integration-only model-call ceiling. Required without a shared budget. */
  maxSteps?: number;
  /** Preferred: the same aggregate allowance used by compose/observer/repair roles. */
  generationCallBudget?: GenerationCallBudget;
}

export interface RunKilnWorldIntegrationResult {
  world: WorldDocumentV2;
  worldHash: `sha256:${string}`;
  placements: Placement[];
  finalized: boolean;
  toolCalls: string[];
  steps: number;
  usage?: AgentUsage;
  callBudget?: GenerationCallBudgetReceipt;
  /** Every successful canonical-world render attempt, in tool-call order. */
  renderEvidence: WorldIntegrationRenderEvidence[];
  /** The model may request commit, but the host remains the final authority. */
  finalizedBy?: 'model' | 'host';
  capped?: boolean;
  lastText?: string;
  error?: string;
}

export interface WorldIntegrationRenderEvidence {
  worldHash: `sha256:${string}`;
  views: number;
  /** Absent only for a legacy host that did not report fallback provenance. */
  degraded?: boolean;
  degradeReason?: string;
  receipt?: SceneRenderReceipt;
  fallbackReceipt?: SceneRenderFallbackReceipt;
}

const empty = z.object({}).strict();
const png = (base64: string): Uint8Array => new Uint8Array(Buffer.from(base64, 'base64'));

function placements(world: WorldDocumentV2): Placement[] {
  return PlacementModel.fromJSON(worldDocumentV2ToSceneModelJSON(world)).placements().placements;
}

function lastMessageText(message: Message | undefined): string | undefined {
  if (!message) return undefined;
  const text = message.content
    .filter((block) => (block as { type?: string }).type === 'textBlock')
    .map((block) => (block as { text?: string }).text ?? '')
    .join('\n')
    .trim();
  return text || undefined;
}

function lifecycleTools(
  state: WorldIntegrationToolState,
  render: SceneRenderPort,
  finalized: { value: boolean },
  renderEvidence: WorldIntegrationRenderEvidence[],
): Tool[] {
  return [
    tool({
      name: 'scene_world_view',
      description: 'Inspect the complete canonical world and authored integration counts.',
      inputSchema: empty,
      callback: async () => {
        const worldHash = await hashWorldDocumentV2(state.world);
        return {
          ok: true,
          worldHash,
          objects: state.world.objects.length,
          zones: state.world.authored.zones.length,
          paths: state.world.authored.paths.length,
          sockets: state.world.authored.sockets.length,
          spawns: state.world.spawns.length,
          terrain: state.world.terrain.kind,
          presentation: state.world.presentation ?? null,
          presentationLimits: {
            maxCameras: 12,
            maxGridColumns: 4,
            maxGridRows: 3,
            maxCellWidth: 4096,
            maxCellHeight: 4096,
            maxTotalPixels: PRESENTATION_MAX_TOTAL_PIXELS_V1,
          },
          presentationBinding: state.world.presentation
            ? { kind: 'world', sha256: worldHash, authoredByModel: false }
            : null,
        } as JSONValue;
      },
    }),
    tool({
      name: 'scene_world_validate',
      description:
        'Check socket compatibility/occupancy and every reserved, portal, and spawn clearance.',
      inputSchema: empty,
      callback: () => {
        const issues = validateWorldIntegrationV2(state.world);
        return { ok: issues.length === 0, issues } as unknown as JSONValue;
      },
    }),
    tool({
      name: 'scene_world_render',
      description:
        'Render the current canonical world with the host inspection profile; inspect before finalizing.',
      inputSchema: empty,
      callback: async () => {
        const attempt = await renderCanonicalWorld(state.world, render);
        if (!attempt.ok) return { ok: false, error: attempt.error } as JSONValue;
        const { evidence, frames } = attempt;
        renderEvidence.push(evidence);
        return [
          ...frames.map(
            (frame) => new ImageBlock({ format: 'png', source: { bytes: png(frame) } }),
          ),
          new JsonBlock({ json: { ok: true, ...evidence } as unknown as JSONValue }),
        ] as unknown as JSONValue;
      },
    }),
    tool({
      name: 'scene_world_finalize',
      description: 'Finalize the validated canonical world after rendering it. Call exactly once.',
      inputSchema: empty,
      callback: async () => {
        const issues = validateWorldIntegrationV2(state.world);
        if (issues.length) return { ok: false, issues } as unknown as JSONValue;
        finalized.value = true;
        return { ok: true, worldHash: await hashWorldDocumentV2(state.world) } as JSONValue;
      },
    }),
  ];
}

type CanonicalWorldRenderAttempt =
  | { ok: true; frames: string[]; evidence: WorldIntegrationRenderEvidence }
  | { ok: false; error: string };

async function renderCanonicalWorld(
  world: WorldDocumentV2,
  render: SceneRenderPort,
): Promise<CanonicalWorldRenderAttempt> {
  const worldHash = await hashWorldDocumentV2(world);
  const presentation = world.presentation;
  const result = await render({
    placements: placements(world),
    worldDocument: world,
    worldHash,
    ...(presentation
      ? {
          cameras: presentation.cameras.map(({ id: _id, cell: _cell, ...camera }) => camera),
          width: presentation.grid.cellWidth,
          height: presentation.grid.cellHeight,
          lightingPresetId: presentation.lightingPresetId,
        }
      : {}),
  });
  if (!result.ok) return { ok: false, error: result.error ?? 'render failed' };
  if (presentation && result.receipt) {
    const receiptValidation = validatePresentationReceiptV1(
      {
        ...presentation,
        artifactBinding: { kind: 'world', sha256: worldHash },
      },
      result.receipt,
    );
    if (!receiptValidation.ok) {
      return {
        ok: false,
        error: `presentation receipt rejected: ${receiptValidation.reason}`,
      };
    }
  }
  const frames = result.perCameraBase64?.length
    ? result.perCameraBase64
    : result.pngBase64
      ? [result.pngBase64]
      : [];
  return { ok: true, frames, evidence: renderEvidenceOf(worldHash, frames.length, result) };
}

function cloneReceipt(receipt: SceneRenderReceipt): SceneRenderReceipt {
  if (
    receipt.perCameraOutputSha256 !== undefined &&
    receipt.perCameraOutputSha256.length !== receipt.cameras.length
  ) {
    throw new TypeError('render receipt per-camera output hashes must match cameras');
  }
  return {
    ...receipt,
    ...(receipt.perCameraOutputSha256
      ? { perCameraOutputSha256: [...receipt.perCameraOutputSha256] }
      : {}),
    cameras: receipt.cameras.map((camera) => ({
      ...camera,
      position: [...camera.position],
      target: [...camera.target],
      up: [...camera.up],
    })),
  };
}

function renderEvidenceOf(
  worldHash: `sha256:${string}`,
  views: number,
  result: SceneRenderResult,
): WorldIntegrationRenderEvidence {
  if (result.receipt && result.fallbackReceipt) {
    throw new TypeError('render result cannot carry both exact and fallback receipts');
  }
  return {
    worldHash,
    views,
    ...(result.degraded !== undefined ? { degraded: result.degraded } : {}),
    ...(result.degradeReason ? { degradeReason: result.degradeReason } : {}),
    ...(result.receipt ? { receipt: cloneReceipt(result.receipt) } : {}),
    ...(result.fallbackReceipt ? { fallbackReceipt: { ...result.fallbackReceipt } } : {}),
  };
}

function hostFinalizationError(
  world: WorldDocumentV2,
  worldHash: `sha256:${string}`,
  renderEvidence: readonly WorldIntegrationRenderEvidence[],
): string | undefined {
  const issues = validateWorldIntegrationV2(world);
  if (issues.length) {
    return `world integration validation failed: ${issues[0]!.code}`;
  }
  const exactFinalRender = renderEvidence.some(
    (evidence) =>
      evidence.worldHash === worldHash &&
      evidence.views > 0 &&
      evidence.degraded !== true &&
      evidence.receipt?.worldHash === worldHash,
  );
  if (!exactFinalRender) {
    return 'world integration ended before a hash-bound non-degraded render of the final world';
  }
  return undefined;
}

async function establishHostFinalization(
  world: WorldDocumentV2,
  render: SceneRenderPort,
  renderEvidence: WorldIntegrationRenderEvidence[],
): Promise<{ worldHash: `sha256:${string}`; error?: string; renderedByHost: boolean }> {
  const worldHash = await hashWorldDocumentV2(world);
  const validationError = hostFinalizationError(world, worldHash, renderEvidence);
  if (!validationError) return { worldHash, renderedByHost: false };
  if (!validationError.startsWith('world integration ended before')) {
    return { worldHash, error: validationError, renderedByHost: false };
  }
  // A render of this exact world already produced non-committable evidence.
  // Preserve that terminal truth instead of hiding a degraded or malformed
  // receipt behind an unchanged automatic retry.
  if (renderEvidence.some((evidence) => evidence.worldHash === worldHash)) {
    return { worldHash, error: validationError, renderedByHost: false };
  }

  const attempt = await renderCanonicalWorld(world, render);
  if (!attempt.ok) {
    return {
      worldHash,
      error: `final world render failed: ${attempt.error}`,
      renderedByHost: true,
    };
  }
  renderEvidence.push(attempt.evidence);
  return {
    worldHash,
    error: hostFinalizationError(world, worldHash, renderEvidence),
    renderedByHost: true,
  };
}

/**
 * Run the bounded post-compose integration phase over one canonical authority.
 * Fresh flow: compose -> migrate v1 candidate -> run this. Refine flow: compose
 * candidate -> reconcileWorldDocumentV2Candidate(parent,candidate) -> run this.
 * Every placement-affecting world tool mutates the same state rendered/finalized.
 */
export async function runKilnWorldIntegration(
  options: RunKilnWorldIntegrationOptions,
): Promise<RunKilnWorldIntegrationResult> {
  const state: WorldIntegrationToolState = { world: parseWorldDocumentV2(options.world) };
  const finalized = { value: false };
  const renderEvidence: WorldIntegrationRenderEvidence[] = [];
  const maxSteps = options.maxSteps ?? 0;
  const metrics = new MetricsCollector(
    options.onEvent,
    maxSteps,
    options.generationCallBudget,
    'author',
  );
  try {
    if (!options.generationCallBudget && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
      throw new Error(
        'runKilnWorldIntegration requires generationCallBudget or an explicit positive maxSteps',
      );
    }
    const mutationTools = makeWorldIntegrationToolsV2({
      state,
      ...(options.publishHeightfieldArtifact
        ? { publishHeightfieldArtifact: options.publishHeightfieldArtifact }
        : {}),
      ...(options.publishColliderArtifact
        ? { publishColliderArtifact: options.publishColliderArtifact }
        : {}),
      ...(options.resolveAuthoredColliderGeometry
        ? { resolveAuthoredColliderGeometry: options.resolveAuthoredColliderGeometry }
        : {}),
      ...(options.onWorldChanged ? { onWorldChanged: options.onWorldChanged } : {}),
    });
    const tools: unknown[] = [
      ...mutationTools,
      ...lifecycleTools(state, options.render, finalized, renderEvidence),
      ...(options.extraTools ?? []),
    ];
    const agent = new Agent({
      model: options.model as never,
      systemPrompt: await toCachedSystemPrompt(WORLD_INTEGRATION_PROMPT_V2, options.model),
      tools: tools as never,
      name: options.agentName ?? 'kiln-world-integrator',
    });
    metrics.attach(agent);
    const result = await agent.invoke(
      `## World integration task\n${options.prompt.trim()}\n\nInspect the current world, make only bounded integration edits that serve the request, render, validate, then finalize.` as never,
    );
    metrics.recordResultUsage(result.metrics?.latestAgentInvocation?.usage);
    const collected = metrics.readMetrics();
    const finalization = await establishHostFinalization(
      state.world,
      options.render,
      renderEvidence,
    );
    const { worldHash } = finalization;
    const lastText = lastMessageText(result.lastMessage);
    const finalizationError = finalization.error;
    const hostFinalized =
      finalizationError === undefined && (!finalized.value || finalization.renderedByHost);
    return {
      world: state.world,
      worldHash,
      placements: placements(state.world),
      finalized: finalizationError === undefined,
      ...(finalizationError === undefined
        ? { finalizedBy: hostFinalized ? ('host' as const) : ('model' as const) }
        : {}),
      toolCalls: collected.toolCalls,
      steps: collected.steps,
      renderEvidence,
      ...(collected.usage ? { usage: collected.usage } : {}),
      ...(options.generationCallBudget
        ? { callBudget: options.generationCallBudget.receipt() }
        : {}),
      ...(metrics.wasCapped() ? { capped: true } : {}),
      ...(lastText ? { lastText } : {}),
      ...(finalizationError ? { error: finalizationError } : {}),
    };
  } catch (error) {
    const collected = metrics.readMetrics();
    return {
      world: state.world,
      worldHash: await hashWorldDocumentV2(state.world),
      placements: placements(state.world),
      finalized: finalized.value,
      toolCalls: collected.toolCalls,
      steps: collected.steps,
      renderEvidence,
      ...(collected.usage ? { usage: collected.usage } : {}),
      ...(options.generationCallBudget
        ? { callBudget: options.generationCallBudget.receipt() }
        : {}),
      error: error instanceof Error ? error.message : String(error),
    };
  } finally {
    metrics.detach();
  }
}