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.8 KB
Raw Blame
/**
 * Composer agent tools — the scene_* surface driven directly (no live model).
 *
 * Each Strands tool is an InvokableTool, so `.invoke(input)` runs its callback in
 * isolation. We assert the model mutates, the sink autosaves the serialized
 * program + evaluated scene, overlaps are surfaced (never dropped), and the two
 * image tools call the injected render port and return content blocks.
 */
import { describe, expect, test } from 'bun:test';
import { JsonBlock, type Tool } from '@strands-agents/sdk';

import { createGenerationCallBudget } from '../agent/call-budget';

import {
  type CatalogEntry,
  PlacementModel,
  type SceneRenderPort,
  type SceneRenderRequest,
} from '../composer';
import {
  type ComposerSink,
  makeSceneComposerTools,
  type SceneRenderCandidate,
} from '../composer/agent';

const asset = (id: string, w = 2, h = 3, d = 2): CatalogEntry => ({
  generationId: id,
  bbox: { min: [-w / 2, 0, -d / 2], max: [w / 2, h, d / 2] },
  name: id,
});

const PNG_B64 = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]).toString('base64');

function setup() {
  const model = new PlacementModel('Test', {
    seed: 7,
    catalog: [asset('well', 3, 4, 3), asset('crate', 1, 1, 1), asset('column', 1, 5, 1)],
  });
  const sink: ComposerSink = {};
  const candidates: SceneRenderCandidate[] = [];
  const calls: SceneRenderRequest[] = [];
  const render: SceneRenderPort = async (req) => {
    calls.push(req);
    return { ok: true, pngBase64: PNG_B64, tris: 123 };
  };
  const tools = makeSceneComposerTools({
    model,
    render,
    sink,
    onCandidate: (c) => candidates.push(c),
  });
  return { model, sink, candidates, calls, tools };
}

// biome-ignore lint/suspicious/noExplicitAny: tool returns are intentionally untyped here
type AnyResult = any;
interface Invokable {
  name: string;
  invoke: (input: unknown) => Promise<AnyResult>;
}
function call(tools: Tool[], name: string, input: unknown = {}): Promise<AnyResult> {
  const t = tools.find((x) => x.name === name) as unknown as Invokable | undefined;
  if (!t) throw new Error(`no tool "${name}"`);
  return t.invoke(input);
}

describe('surface', () => {
  test('exposes the 17 scene_* tools by name', () => {
    const { tools } = setup();
    const names = tools.map((t) => t.name).sort();
    expect(names).toEqual(
      [
        'scene_list_assets',
        'scene_view',
        'scene_validate',
        'scene_render',
        'scene_screenshot_camera',
        'scene_layout',
        'scene_place',
        'scene_cluster',
        'scene_ring',
        'scene_move',
        'scene_face',
        'scene_group',
        'scene_remove',
        'scene_set_environment',
        'scene_set_backdrop',
        'scene_paint',
        'scene_finalize',
      ].sort(),
    );
  });

  test('scene_set_environment + scene_set_backdrop set scene-level theme on the model', async () => {
    const { model, tools } = setup();
    const env = await call(tools, 'scene_set_environment', { ground: 'edo' });
    expect(env.ok).toBe(true);
    expect(env.environment).toBe('edo');
    expect(model.environment()).toBe('edo');

    const bg = await call(tools, 'scene_set_backdrop', { kind: 'fuji', scale: 2 });
    expect(bg.ok).toBe(true);
    expect(model.sceneBackdrop()).toEqual({ kind: 'fuji', pos: [0, 20, -160], scale: 2 });

    // Both round-trip through the model JSON (so compose.ts reads them off result.scene).
    const json = model.toJSON();
    expect(json.environment).toBe('edo');
    expect(json.backdrop).toEqual({ kind: 'fuji', pos: [0, 20, -160], scale: 2 });
    expect(PlacementModel.fromJSON(json).sceneBackdrop()).toEqual({
      kind: 'fuji',
      pos: [0, 20, -160],
      scale: 2,
    });
  });
});

describe('read tools', () => {
  test('scene_list_assets returns the catalog with footprint sizes', async () => {
    const { tools } = setup();
    const r = await call(tools, 'scene_list_assets');
    expect(r.assets).toHaveLength(3);
    expect(r.assets.map((a: { generationId: string }) => a.generationId)).toContain('well');
    expect(r.assets[0].size).toHaveLength(3);
  });

  test('scene_view reflects the current program + counts', async () => {
    const { tools } = setup();
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0], face: 'center', role: 'hero' });
    const r = await call(tools, 'scene_view');
    expect(r.program).toContain('s.place(');
    expect(r.placementCount).toBe(1);
    expect(r.overlapCount).toBe(0);
    expect(r.aliases).toContain('well');
  });
});

describe('place / cluster / ring mutate + autosave', () => {
  test('scene_place places one asset and autosaves the program', async () => {
    const { tools, sink } = setup();
    const r = await call(tools, 'scene_place', { asset: 'well', at: [10, -5], face: 'center' });
    expect(r.ok).toBe(true);
    expect(r.placements).toBe(1);
    expect(r.overlaps).toBe(0);
    expect(sink.program).toContain('s.place(');
    expect(sink.placements).toHaveLength(1);
  });

  test('scene_place with an unknown asset returns an in-band error + hint', async () => {
    const { tools } = setup();
    const r = await call(tools, 'scene_place', { asset: 'nope', at: [0, 0] });
    expect(r.ok).toBe(false);
    expect(r.hint).toContain('scene_list_assets');
  });

  test('scene_cluster scatters N overlap-free and serializes as one line', async () => {
    const { tools, sink } = setup();
    const r = await call(tools, 'scene_cluster', {
      asset: 'crate',
      around: [20, 0],
      count: 8,
      spread: 14,
    });
    expect(r.ok).toBe(true);
    expect(r.placements).toBe(8);
    expect(r.overlaps).toBe(0);
    expect(sink.program?.split('\n').filter((l) => l.includes('s.cluster('))).toHaveLength(1);
  });

  test('scene_ring places N on a circle, overlap-free', async () => {
    const { tools } = setup();
    const r = await call(tools, 'scene_ring', {
      asset: 'column',
      center: [0, 0],
      count: 8,
      radius: 16,
      faceOut: false,
    });
    expect(r.placements).toBe(8);
    expect(r.overlaps).toBe(0);
  });
});

describe('layout baseline', () => {
  test('scene_layout lays out the whole catalog overlap-free, returns aliases', async () => {
    const { tools } = setup();
    const r = await call(tools, 'scene_layout', { anchor: 'single' });
    expect(r.ok).toBe(true);
    expect(Array.isArray(r.alias)).toBe(true);
    expect(r.alias).toHaveLength(3);
    expect(r.overlaps).toBe(0);
  });
});

describe('edit ops + overlap surfacing', () => {
  test('an overlap is surfaced on mutation and via scene_validate, and scene_move resolves it', async () => {
    const { tools } = setup();
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0], alias: 'w' });
    const collide = await call(tools, 'scene_place', { asset: 'crate', at: [0, 0], alias: 'c' });
    expect(collide.overlaps).toBeGreaterThan(0);
    expect(collide.hint).toContain('scene_validate');

    const v = await call(tools, 'scene_validate');
    expect(v.ok).toBe(false);
    expect(v.count).toBeGreaterThan(0);
    expect(v.overlaps[0].separation).toHaveLength(3);

    const moved = await call(tools, 'scene_move', { target: 'c', to: [60, 60] });
    expect(moved.ok).toBe(true);
    expect(moved.overlaps).toBe(0);
  });

  test('scene_face re-orients, scene_remove drops, scene_group binds + moves together', async () => {
    const { tools } = setup();
    await call(tools, 'scene_place', { asset: 'crate', at: [0, 0], alias: 'a' });
    await call(tools, 'scene_place', { asset: 'crate', at: [4, 0], alias: 'b' });

    const faced = await call(tools, 'scene_face', { target: 'a', face: 90 });
    expect(faced.ok).toBe(true);

    const grouped = await call(tools, 'scene_group', {
      targets: ['a', 'b'],
      name: 'pile',
      delta: [10, 0],
    });
    expect(grouped.ok).toBe(true);
    expect(grouped.members).toEqual(['a', 'b']);

    const removed = await call(tools, 'scene_remove', { target: 'b' });
    expect(removed.ok).toBe(true);
    expect(removed.placements).toBe(1);
  });

  test('an edit op on a missing target returns ok:false', async () => {
    const { tools } = setup();
    const r = await call(tools, 'scene_move', { target: 'ghost', delta: [1, 0] });
    expect(r.ok).toBe(false);
  });
});

describe('render tools call the port and return content blocks', () => {
  test('scene_render renders the whole scene, emits a candidate, returns [image, json]', async () => {
    const { tools, calls, candidates } = setup();
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const r = await call(tools, 'scene_render');
    expect(Array.isArray(r)).toBe(true);
    expect(r).toHaveLength(2); // 1 ImageBlock + 1 JsonBlock
    expect(calls).toHaveLength(1);
    expect(calls[0]!.placements).toHaveLength(1);
    expect(calls[0]!.cameras).toBeUndefined(); // 3 canonical angles = host default
    expect(candidates).toHaveLength(1);
    expect(candidates[0]!.pngBase64).toBe(PNG_B64);
    expect(candidates[0]!.program).toContain('s.place(');
  });

  test('scene_screenshot_camera passes the requested camera through', async () => {
    const { tools, calls } = setup();
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const r = await call(tools, 'scene_screenshot_camera', {
      position: [30, 20, 30],
      target: [0, 0, 0],
      fovDeg: 45,
    });
    expect(Array.isArray(r)).toBe(true);
    expect(calls[0]!.cameras).toHaveLength(1);
    expect(calls[0]!.cameras![0]).toEqual({
      position: [30, 20, 30],
      target: [0, 0, 0],
      fovDeg: 45,
    });
  });

  test('text-only author gets bounded observer evidence, never image blocks, on the shared budget', async () => {
    const model = new PlacementModel('T', { catalog: [asset('well')] });
    const sink: ComposerSink = {};
    const budget = createGenerationCallBudget(3);
    let observed: unknown;
    const render: SceneRenderPort = async () => ({ ok: true, pngBase64: PNG_B64 });
    const tools = makeSceneComposerTools({
      model,
      render,
      sink,
      generationCallBudget: budget,
      renderObservationPort: async (input) => {
        observed = input;
        expect(input.generationCallBudget).toBe(budget);
        expect(input.generationCallBudget?.tryConsume('observer')).toBe(true);
        return { verdict: 'cohesive', findings: [] };
      },
    });
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const result = await call(tools, 'scene_render');

    expect(result).toHaveLength(1);
    expect(result[0]).toBeInstanceOf(JsonBlock);
    expect(result[0].json.visualObservation).toEqual({
      ok: true,
      value: { verdict: 'cohesive', findings: [] },
    });
    expect(JSON.stringify(result)).not.toContain(PNG_B64);
    expect((observed as { pngs: Uint8Array[] }).pngs[0]).toEqual(
      new Uint8Array(Buffer.from(PNG_B64, 'base64')),
    );
    expect(budget.receipt()).toMatchObject({ consumed: 1, byRole: { observer: 1 } });
  });

  test('observer failure is in-band and still never exposes image blocks', async () => {
    const model = new PlacementModel('T', { catalog: [asset('well')] });
    const sink: ComposerSink = {};
    const render: SceneRenderPort = async () => ({ ok: true, pngBase64: PNG_B64 });
    const tools = makeSceneComposerTools({
      model,
      render,
      sink,
      renderObservationPort: async () => {
        throw new Error('provider detail');
      },
    });
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const result = await call(tools, 'scene_render');
    expect(result).toHaveLength(1);
    expect(result[0]).toBeInstanceOf(JsonBlock);
    expect(result[0].json.visualObservation).toEqual({ ok: false, reason: 'observer-unavailable' });
    expect(JSON.stringify(result)).not.toContain('provider detail');
    expect(JSON.stringify(result)).not.toContain(PNG_B64);
  });

  test('a render failure returns an in-band ok:false (no image)', async () => {
    const model = new PlacementModel('T', { catalog: [asset('well')] });
    const sink: ComposerSink = {};
    const render: SceneRenderPort = async () => ({ ok: false, error: 'boom' });
    const tools = makeSceneComposerTools({ model, render, sink });
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const r = await call(tools, 'scene_render');
    expect(Array.isArray(r)).toBe(false);
    expect(r.ok).toBe(false);
    expect(r.error).toBe('boom');
  });

  test('scene views expose valid derivative fidelity but never exactArtifact', async () => {
    const model = new PlacementModel('T', { catalog: [asset('well')] });
    const sink: ComposerSink = {};
    const hash = `sha256:${'a'.repeat(64)}` as const;
    const render: SceneRenderPort = async () => ({
      ok: true,
      pngBase64: PNG_B64,
      viewFidelity: {
        version: 'kiln.derivative-review-fidelity.v1',
        requested: 'full-preferred',
        delivered: 'full-material',
        materialFaithful: true,
        exactArtifact: false,
        degraded: false,
        receipts: [
          {
            version: 'kiln.view-fidelity.v1',
            derivativeLabel: 'Hero 3/4',
            requested: 'full-preferred',
            delivered: 'full-material',
            materialFaithful: true,
            exactArtifact: false,
            rendererId: 'gpu:composer',
            inputGlbSha256: hash,
            degraded: false,
          },
        ],
      },
    });
    const tools = makeSceneComposerTools({ model, render, sink });
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const result = await call(tools, 'scene_render');
    expect(result[1].json.viewFidelity).toMatchObject({
      materialFaithful: true,
      exactArtifact: false,
      receipts: [{ derivativeLabel: 'Hero 3/4', inputGlbSha256: hash, exactArtifact: false }],
    });
  });

  test('scene views downgrade missing or malformed derivative receipts', async () => {
    const model = new PlacementModel('T', { catalog: [asset('well')] });
    const sink: ComposerSink = {};
    const render: SceneRenderPort = async () => ({ ok: true, pngBase64: PNG_B64 });
    const tools = makeSceneComposerTools({ model, render, sink });
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0] });
    const result = await call(tools, 'scene_render');
    expect(result[1].json.viewFidelity).toEqual({
      version: 'kiln.derivative-review-fidelity.v1',
      requested: 'full-preferred',
      delivered: 'none',
      materialFaithful: false,
      exactArtifact: false,
      degraded: true,
      receipts: [],
      reasonCodes: ['DERIVATIVE_RECEIPT_UNAVAILABLE'],
    });
  });
});

describe('finalize', () => {
  test('scene_finalize flips the sink + returns the final program', async () => {
    const { tools, sink } = setup();
    await call(tools, 'scene_place', { asset: 'well', at: [0, 0], role: 'hero' });
    const r = await call(tools, 'scene_finalize');
    expect(r.ok).toBe(true);
    expect(r.program).toContain('export default s;');
    expect(sink.finalized).toBe(true);
  });
});