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
import { describe, expect, it } from 'bun:test';
import { createKilnProgramToolRegistry, createKilnNativeToolRegistry } from '../tools/registry';
import { createLocalToolContext } from '../local-runtime';
import type { DiscoveryResponse } from '../discovery/service';
import { MemoryProgramStore } from '../program-store';
import { createAssetRequirementsStore } from '../requirements-store';
import { createAssetRequirementsV1, requestedRequirement } from '../contracts/requirements';
import { resolveRequirementsContext } from '../requirements-context';
const discovery = () =>
createKilnProgramToolRegistry().find((tool) => tool.name === 'kiln_discover')!;
type Result = DiscoveryResponse;
describe('progressive capability discovery', () => {
it('shows stability in the compact text used by both agent transports', async () => {
for (const tools of [createKilnNativeToolRegistry({}, {}), createKilnProgramToolRegistry()]) {
const tool = tools.find((entry) => entry.name === 'kiln_discover')!;
for (const [id, stability] of [
['operation:boxGeo', 'stable'],
['operation:implicitSurface', 'experimental'],
['recipe:steerable-wheel-v1', 'experimental'],
]) {
const output = await tool.run({ query: id, limit: 1 });
expect(tool.text!(output)).toContain(`${id} [${stability}]`);
}
}
});
it('reports each selected exporter against actual exported vertex attributes', async () => {
const source = `function build(){const root=createRoot('Attributes');const g=boxGeo(1,1,1);g.setAttribute('color',new THREE.Float32BufferAttribute(new Array(g.getAttribute('position').count).fill([1,0,0]).flat(),3));for(const key of ['uv1','uv2','uv3'])g.setAttribute(key,g.getAttribute('uv').clone());createPart('Body',g,new THREE.MeshStandardMaterial({vertexColors:true}),{parent:root});return root;}`;
for (const exporter of ['legacy', 'three'] as const) {
const context = createLocalToolContext(
{ programStore: new MemoryProgramStore() },
{ KILN_GLTF_EXPORTER: exporter, KILN_EVALUATOR_MODE: 'in-process' },
);
const tool = createKilnProgramToolRegistry(context).find((t) => t.name === 'kiln_discover')!;
const result = (await tool.run({ capabilities: true })) as {
capabilities: { geometry: { exporter: string; attributes: string[] } };
};
expect(result.capabilities.geometry.exporter).toBe(exporter);
expect(context.assetBuildOptions?.gltfExporter).toBe(exporter);
const rendered = await context.evaluatorPort!.render(source);
const bytes = Buffer.from(rendered.glb);
const document = JSON.parse(bytes.subarray(20, 20 + bytes.readUInt32LE(12)).toString());
const attributes = document.meshes[0].primitives[0].attributes;
for (const [sourceKey, gltfKey, both] of [
['color', 'COLOR_0', true],
['uv1', 'TEXCOORD_1', true],
['uv2', 'TEXCOORD_2', false],
['uv3', 'TEXCOORD_3', false],
] as const) {
const reported = result.capabilities.geometry.attributes.includes(sourceKey);
expect(reported).toBe(both || exporter === 'three');
expect(gltfKey in attributes).toBe(reported);
}
}
});
it('does not invent exporter capabilities for an opaque host evaluator', async () => {
const tools = createKilnProgramToolRegistry({
evaluatorPort: {
render: async () => {
throw new Error('Discovery must not evaluate');
},
},
});
const result = (await tools
.find((t) => t.name === 'kiln_discover')!
.run({ capabilities: true })) as {
capabilities: { geometry: { exporter: string; attributes: unknown } };
};
expect(result.capabilities.geometry.exporter).toBe('unspecified-by-host');
expect(result.capabilities.geometry.attributes).toBeNull();
});
it('keeps a local exporter fixed when the ambient environment changes', async () => {
const context = createLocalToolContext(
{ programStore: new MemoryProgramStore() },
{ KILN_GLTF_EXPORTER: 'legacy', KILN_EVALUATOR_MODE: 'in-process' },
);
const previous = process.env.KILN_GLTF_EXPORTER;
process.env.KILN_GLTF_EXPORTER = 'invalid-after-context-construction';
try {
const result = await context.evaluatorPort!.render(
'function build(){const root=createRoot();createPart("Box",boxGeo(1,1,1),gameMaterial(0xffffff),{parent:root});return root;}',
);
expect(result.glb.byteLength).toBeGreaterThan(0);
} finally {
if (previous === undefined) delete process.env.KILN_GLTF_EXPORTER;
else process.env.KILN_GLTF_EXPORTER = previous;
}
});
it('groups exact signatures in requested order and reports every unknown name', async () => {
const tool = discovery();
const result = (await tool.run({
ids: ['createPart', 'loftProfiles', 'boxGeo'],
})) as Result;
expect(result.entries.map((p) => p.name)).toEqual(['createPart', 'loftProfiles', 'boxGeo']);
expect(result.total).toBe(3);
expect(result.nextOffset).toBeNull();
expect(result.entries.every((entry) => 'contract' in entry)).toBe(true);
expect(result.text.length).toBeLessThanOrEqual(16384);
const missing = (await tool.run({
ids: ['boxGeo', 'inventedMesh', 'unknownSurface'],
})) as Result;
expect(missing.error?.message).toContain('inventedMesh');
expect(missing.error?.message).toContain('unknownSurface');
expect(missing.error?.message).not.toContain('boxGeo,');
expect(missing.entries.map((entry) => entry.name)).toEqual(['boxGeo']);
await expect(tool.run({ ids: ['boxGeo'], family: 'geometry' })).rejects.toThrow('alone');
await expect(tool.run({ ids: Array(7).fill('boxGeo') })).rejects.toThrow();
});
it('reports effective host limits and current camera/export support without confusing a cache wrapper for an external evaluator', async () => {
const local = createLocalToolContext({}, { KILN_EVALUATOR_TIMEOUT_MS: '4321' });
const tool = createKilnProgramToolRegistry(local).find((t) => t.name === 'kiln_discover')!;
const result = (await tool.run({ capabilities: true })) as {
capabilities: {
execution: { mode: string; deadlineMs?: number };
camera: { version: string; maxShots: number };
geometry: { materialGroups: boolean; attributes: string[] };
};
text: string;
};
expect(result.capabilities.execution.mode).toBe('subprocess');
expect(result.capabilities.execution.deadlineMs).toBe(4321);
expect(result.capabilities.camera.version).toBe('kiln.capture.v1');
expect(result.capabilities.camera.maxShots).toBe(9);
expect(result.capabilities.geometry.materialGroups).toBe(true);
expect(result.capabilities.geometry.attributes).toContain('uv');
// Capability replies include the configured texture IDs, grouped by slot.
// Keep the measured catalog plus host contracts well below the 16 KiB cap.
expect(result.text.length).toBeLessThan(8000);
const trusted = (await discovery().run({
capabilities: true,
})) as typeof result;
expect(trusted.capabilities.execution.mode).toBe('trusted-local');
expect(trusted.capabilities.execution.deadlineMs).toBeUndefined();
});
it('reports the host-bound requirements and declared validation profile separately from engine advice', async () => {
const profile = {
version: 'kiln.validation-profile.v1' as const,
profileId: 'holodeck.palm',
mode: 'enforce' as const,
checks: [{ id: 'frond', select: { names: ['Mesh_frond_*'] }, primitives: { exactly: 1 } }],
};
const requirements = createAssetRequirementsStore().host.bind(
{ taskId: 'palm', lineageId: 'palm-a' },
createAssetRequirementsV1({ requirements: { validation: requestedRequirement(profile) } }),
{ actor: 'holodeck', reason: 'Destination', source: 'brief' },
);
type Capabilities = {
capabilities: {
requirements: {
bound: boolean;
policyHash: string;
declared: { source: string; validationProfile: unknown } | null;
};
};
};
const bound = (await createKilnProgramToolRegistry({ requirements })
.find((t) => t.name === 'kiln_discover')!
.run({ capabilities: true })) as Capabilities;
expect(bound.capabilities.requirements).toEqual({
bound: true,
policyHash: resolveRequirementsContext(requirements).policyHash,
declared: { source: 'host-binding', validationProfile: profile },
});
const native = (await createKilnNativeToolRegistry({ requirements }, {})
.find((t) => t.name === 'kiln_discover')!
.run({ capabilities: true })) as Capabilities;
expect(native.capabilities.requirements).toEqual(bound.capabilities.requirements);
const neutral = (await discovery().run({ capabilities: true })) as Capabilities;
expect(neutral.capabilities.requirements).toEqual({
bound: false,
policyHash: resolveRequirementsContext().policyHash,
declared: null,
});
});
it('returns a compact complete overview and an exact lookup with a usable example', async () => {
const tool = discovery();
const overview = (await tool.run({})) as Result;
expect(overview.entries).toHaveLength(6);
expect(overview.total).toBeGreaterThan(50);
expect(overview.nextOffset).toBe(6);
expect(JSON.stringify(overview.entries)).not.toContain('contract');
expect(overview.text.length).toBeLessThan(12000);
expect(overview.text).toContain('BufferGeometry');
expect(overview.text).toContain('programRef');
const selected = (await tool.run({ ids: ['boxGeo'] })) as Result;
expect(selected.entries.map((entry) => entry.name)).toEqual(['boxGeo']);
expect(selected.text).toContain('example');
expect(selected.total).toBe(1);
expect(selected.nextOffset).toBeNull();
});
it('publishes every strict procedural texture layer shape instead of hiding parameters', async () => {
const selected = (await discovery().run({
ids: ['proceduralTexture'],
})) as Result;
for (const fragment of [
'solid: { color }',
'checker: { colorA, colorB, squares? }',
'stripes: { colorA, colorB, count?, angleDeg? }',
'gradient: { from, to, angleDeg? }',
'bricks: { brick, mortar, rows?, cols?, mortarWidth?: 0..1',
'stagger?: 0..1',
'noise: { colorA, colorB, scale?, octaves?, seed? }',
]) {
expect(selected.text).toContain(fragment);
}
});
it('searches descriptions and pages results without dropping or repeating entries', async () => {
const tool = discovery();
const first = (await tool.run({
family: 'geometry',
query: 'geo',
limit: 2,
})) as Result;
expect(first.entries).toHaveLength(2);
expect(first.nextOffset).toBe(2);
const second = (await tool.run({
family: 'geometry',
query: 'geo',
limit: 2,
offset: first.nextOffset,
})) as Result;
expect(second.total).toBe(first.total);
expect(second.entries.every((entry) => !first.entries.some((a) => a.name === entry.name))).toBe(
true,
);
const holes = (await tool.run({ query: 'holes', limit: 12 })) as Result;
expect(holes.entries.some((entry) => entry.name === 'extrudeProfile')).toBe(true);
});
it('explains invalid categories and missing names and bounds model-controlled input', async () => {
const tool = discovery();
const invalid = (await tool.run({ family: 'clay' })) as Result;
expect(invalid.error?.code).toBe('UNKNOWN_FILTER');
expect(invalid.text).toContain('overview');
const missing = (await tool.run({ ids: ['inventedMesh'] })) as Result;
expect(missing.error?.message).toContain('inventedMesh');
expect(missing.text).toContain('query');
await expect(tool.run({ limit: 100 })).rejects.toThrow();
await expect(tool.run({ offset: -1 })).rejects.toThrow();
await expect(tool.run({ accidentalField: true })).rejects.toThrow();
});
it('removes the retired callable from both registries and shares the current query contract', async () => {
for (const tools of [createKilnNativeToolRegistry({}, {}), createKilnProgramToolRegistry()]) {
expect(tools.some((tool) => tool.name === 'kiln_list_primitives')).toBe(false);
const tool = tools.find((entry) => entry.name === 'kiln_discover')!;
const result = (await tool.run({ ids: ['boxGeo'] })) as Result;
expect(result.version).toBe('kiln.discovery.v1');
expect(result.entries[0]?.name).toBe('boxGeo');
await expect(tool.run({ name: 'boxGeo' })).rejects.toThrow();
await expect(tool.run({ names: ['boxGeo'] })).rejects.toThrow();
await expect(tool.run({ category: 'geometry' })).rejects.toThrow();
}
});
it('reports the actual revision store usage without exporting stored source', async () => {
const tools = createKilnProgramToolRegistry();
const list = tools.find((t) => t.name === 'kiln_discover')!;
const validate = tools.find((t) => t.name === 'kiln_validate')!;
const source = 'function build(){return createRoot("Usage");}';
await validate.run({ code: source });
await validate.run({ code: source });
const result = (await list.run({ capabilities: true })) as {
capabilities: {
source: {
storage: { entries: number; bytes: number; eviction: string };
};
};
text: string;
};
expect(result.capabilities.source.storage).toMatchObject({
entries: 1,
bytes: Buffer.byteLength(source),
eviction: 'none',
});
expect(result.text).not.toContain(source);
});
it('explains removed helper migrations without returning callable aliases', async () => {
const tool = discovery();
for (const selector of ['panelRemapV', 'operation:panelRemapV']) {
const result = (await tool.run({ ids: ['boxGeo', selector] })) as Result;
expect(result.error?.code).toBe('REMOVED_ID');
expect(result.text).toContain('remapUV');
expect(result.text).toContain('[1, 0.3]');
expect(result.entries).toEqual([]);
}
const advisory = (await tool.run({ ids: ['validateAsset'] })) as Result;
expect(advisory.text).toContain('materialBudgetAdvisory');
expect(advisory.text).toContain('does not validate');
});
});