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
/** 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();
}
}