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.

32.0 KB
Raw Blame
/**
 * Scene-composer tool skin for the Strands agent loop — the `scene_*` surface.
 *
 * Sibling to the asset-gen `kiln_*` tools (../../agent/tools), but the unit of
 * work is a SCENE, not a single asset. Every tool mutates ONE structured
 * `PlacementModel` (the source of truth); after each successful mutation the
 * model is re-evaluated + re-serialized into a `ComposerSink` (continuous
 * autosave — a step-capped run still captures its work). The two image tools
 * (`scene_render` / `scene_screenshot_camera`) call the host `SceneRenderPort`
 * and return `[ImageBlock…, JsonBlock]` so the model literally SEES the scene.
 *
 * Pure orchestration over the composer core (model / dsl / overlap) + the SDK's
 * `tool()`. No THREE — rendering is the injected host port. Errors are in-band
 * `{ ok:false, error, hint }` (tools never throw at the model).
 *
 * Surface (17): read — scene_list_assets, scene_view, scene_validate,
 * scene_render, scene_screenshot_camera · mutate — scene_layout, scene_place,
 * scene_cluster, scene_ring, scene_move, scene_face, scene_group, scene_remove ·
 * theme — scene_set_environment, scene_set_backdrop, scene_paint · commit — scene_finalize.
 * (Extends the design doc's 12 with scene_cluster / scene_ring so the agent can
 * author the grouping primitives the program already serializes.)
 */
import { ImageBlock, JsonBlock, type JSONValue, type Tool, tool } from '@strands-agents/sdk';
import { z } from 'zod';

import { serialize } from '../dsl';
import type {
  EvalResult,
  Placement,
  PlacementModel,
  PlacementProvenance,
  ScenePaintZoneSpec,
} from '../model';
import type { OverlapViolation } from '../overlap';
import type {
  DerivativeReviewFidelityV1,
  SceneRenderObservationPort,
  SceneRenderPort,
  SceneRenderResult,
} from '../render-port';
import type { GenerationCallBudget } from '../../agent/call-budget';
import { ViewEvidenceHistoryStore } from '../../views/evidence-history';

/**
 * A mutable sink the composer tools write into. Create one per run; after every
 * successful mutation it holds the latest serialized program + evaluated scene
 * (so an un-finalized / step-capped run still captures the work). `.finalized`
 * flips when `scene_finalize` fires.
 */
export interface ComposerSink {
  program?: string;
  placements?: Placement[];
  provenance?: Record<string, PlacementProvenance>;
  overlaps?: OverlapViolation[];
  finalized?: boolean;
}

/**
 * A live render candidate surfaced out-of-band from `scene_render`: the
 * serialized program at this render plus the grid PNG (base64) the agent saw.
 * Lets the host stream a filmstrip of intermediate scenes + "pick a version".
 * Emitted in addition to — never instead of — what the agent sees.
 */
export interface SceneRenderCandidate {
  program: string;
  pngBase64: string;
  tris?: number;
}

// ── shared zod fragments ──────────────────────────────────────────────────────

const vec2 = z.tuple([z.number(), z.number()]);
const vec3 = z.tuple([z.number(), z.number(), z.number()]);
const roleEnum = z.enum(['hero', 'support', 'fill']);
/** center (face the scene origin) · out (face away) · [x,z] (face a point) · degrees. */
const facing = z.union([z.literal('center'), z.literal('out'), vec2, z.number()]);
const empty = z.object({});
/** Scene-level ground/sky theme ids + atmosphere backdrop kinds (mirror Studio). */
const groundThemeEnum = z.enum([
  'meadow',
  'desert',
  'egypt',
  'plaza',
  'snow',
  'arctic',
  'edo',
  'night',
  'studio',
]);
const backdropKindEnum = z.enum(['mushroom-cloud', 'sun-disc', 'aurora', 'fuji']);
const paintKindEnum = z.enum([
  'grass',
  'concrete',
  'asphalt',
  'sand',
  'flagstone',
  'snow',
  'ice',
  'gravel',
  'stone-path',
]);
const paintShape = z.union([
  z.object({
    type: z.literal('rect'),
    x: z.number(),
    z: z.number(),
    hx: z.number(),
    hz: z.number(),
  }),
  z.object({
    type: z.literal('strip'),
    axis: z.enum(['x', 'z']),
    offset: z.number(),
    half: z.number(),
    from: z.number(),
    to: z.number(),
  }),
]);

// ── render-result → content blocks ────────────────────────────────────────────

/** base64 PNG → the raw bytes an ImageBlock wants. */
const png = (b64: string): Uint8Array => new Uint8Array(Buffer.from(b64, 'base64'));
const SHA256 = /^sha256:[0-9a-f]{64}$/;

function composerViewFidelity(res: SceneRenderResult): DerivativeReviewFidelityV1 {
  const value = res.viewFidelity;
  const valid =
    value?.version === 'kiln.derivative-review-fidelity.v1' &&
    value.exactArtifact === false &&
    value.receipts.length > 0 &&
    value.receipts.every(
      (receipt) =>
        receipt.exactArtifact === false &&
        receipt.derivativeLabel.trim().length > 0 &&
        SHA256.test(receipt.inputGlbSha256),
    );
  if (valid) {
    return {
      ...value,
      exactArtifact: false,
      receipts: value.receipts.map((receipt) => ({ ...receipt, exactArtifact: false })),
    };
  }
  return {
    version: 'kiln.derivative-review-fidelity.v1',
    requested: 'full-preferred',
    delivered: 'none',
    materialFaithful: false,
    exactArtifact: false,
    degraded: true,
    receipts: [],
    reasonCodes: [value ? 'DERIVATIVE_RECEIPT_INVALID' : 'DERIVATIVE_RECEIPT_UNAVAILABLE'],
  };
}

/** Turn a host render result into the tool-callback value: one ImageBlock per
 *  returned view (perCamera grid or single frame) + a JsonBlock of metadata, or a
 *  plain `{ok:false}` when the render failed. Block arrays are a valid (untyped)
 *  Strands callback return — cast past JSONValue, same as the kiln_* tools. */
function withVisualObservation(json: unknown, visualObservation: JSONValue): JSONValue {
  if (json && typeof json === 'object' && !Array.isArray(json)) {
    return { ...(json as Record<string, JSONValue>), visualObservation } as JSONValue;
  }
  return { result: json as JSONValue, visualObservation } as JSONValue;
}

async function renderToCallback(
  res: SceneRenderResult,
  surface: 'scene_render' | 'scene_screenshot_camera',
  evidenceHistory: ViewEvidenceHistoryStore,
  renderObservationPort?: SceneRenderObservationPort,
  generationCallBudget?: GenerationCallBudget,
): Promise<JSONValue> {
  if (!res.ok) {
    return { ok: false, error: res.error ?? 'render failed' } as JSONValue;
  }
  const frames = res.perCameraBase64?.length
    ? res.perCameraBase64
    : res.pngBase64
      ? [res.pngBase64]
      : [];
  const viewFidelity = composerViewFidelity(res);
  const json = {
    ok: true,
    views: frames.length,
    viewFidelity,
    viewEvidence: evidenceHistory.record(surface, viewFidelity),
    ...(res.tris != null ? { tris: res.tris } : {}),
  };
  if (renderObservationPort) {
    try {
      const value = await renderObservationPort({
        toolName: surface,
        pngs: frames.map(png),
        json: json as unknown as import('../render-port').SceneRenderObservationValue,
        ...(generationCallBudget ? { generationCallBudget } : {}),
      });
      return [
        new JsonBlock({
          json: withVisualObservation(json, { ok: true, value } as JSONValue),
        }),
      ] as unknown as JSONValue;
    } catch {
      return [
        new JsonBlock({
          json: withVisualObservation(json, {
            ok: false,
            reason: 'observer-unavailable',
          } as JSONValue),
        }),
      ] as unknown as JSONValue;
    }
  }
  return [
    ...frames.map((b64) => new ImageBlock({ format: 'png', source: { bytes: png(b64) } })),
    new JsonBlock({ json: json as unknown as JSONValue }),
  ] as unknown as JSONValue;
}

// ── shared mutation plumbing ──────────────────────────────────────────────────

/** A compact mutation receipt the model reads after every edit. */
interface MutationEcho {
  ok: true;
  alias?: string | string[];
  placements: number;
  overlaps: number;
  hint?: string;
}

export interface MakeComposerToolsOptions {
  /** The scene model the tools mutate (seeded with the selected catalog). */
  model: PlacementModel;
  /** Host renderer: placements (+ optional cameras) → PNG(s). */
  render: SceneRenderPort;
  /** Receives the serialized program + evaluated scene after each mutation. */
  sink: ComposerSink;
  /** Best-effort live render candidates (one per successful scene_render). */
  onCandidate?: (c: SceneRenderCandidate) => void;
  /** Host VLM seam for text-only authors; strips all image blocks from tool output. */
  renderObservationPort?: SceneRenderObservationPort;
  /** Shared author/observer aggregate model-call budget. */
  generationCallBudget?: GenerationCallBudget;
  /** Shared bounded hash-only material evidence ledger for this composer run. */
  viewEvidenceHistory?: ViewEvidenceHistoryStore;
}

/**
 * Build the in-process `scene_*` tool list for a composer run. Every mutator
 * shares one `capture()` that re-serializes + re-evaluates the model into the
 * sink and returns a `{ placements, overlaps }` receipt; a non-zero overlap count
 * carries a hint pointing at scene_validate → scene_move.
 */
export function makeSceneComposerTools(opts: MakeComposerToolsOptions): Tool[] {
  const { model, render, sink } = opts;
  const evidenceHistory = opts.viewEvidenceHistory ?? new ViewEvidenceHistoryStore();

  /** Re-serialize + re-evaluate into the sink; the single autosave point. */
  const capture = (): EvalResult => {
    const ev = model.placements();
    sink.program = serialize(model);
    sink.placements = ev.placements;
    sink.provenance = ev.provenance;
    sink.overlaps = ev.overlaps;
    return ev;
  };

  /** Standard mutation receipt: capture, then echo counts (+ overlap nudge). */
  const echo = (alias?: string | string[]): MutationEcho => {
    const ev = capture();
    const overlaps = ev.overlaps.length;
    return {
      ok: true,
      ...(alias !== undefined ? { alias } : {}),
      placements: ev.placements.length,
      overlaps,
      ...(overlaps
        ? {
            hint: `${overlaps} footprint overlap(s) — call scene_validate for separation vectors, then scene_move to resolve.`,
          }
        : {}),
    };
  };

  /** Wrap an add op (which throws on an unknown asset) into an in-band result. */
  const guarded = (fn: () => string | string[]): JSONValue => {
    try {
      return echo(fn()) as unknown as JSONValue;
    } catch (err) {
      return {
        ok: false,
        error: err instanceof Error ? err.message : String(err),
        hint: 'Call scene_list_assets to see the generationIds available in this scene.',
      } as JSONValue;
    }
  };

  // ── read tools ──────────────────────────────────────────────────────────────

  const listAssetsTool: Tool = tool({
    name: 'scene_list_assets',
    description:
      'List the assets you can place in this scene — each generationId with its name, footprint ' +
      'size [w,h,d], and tags. These are the ONLY assets available; place them by generationId. ' +
      'Call this first to plan your composition.',
    inputSchema: empty,
    callback: () => ({ assets: model.catalogList() }) as JSONValue,
  });

  const viewTool: Tool = tool({
    name: 'scene_view',
    description:
      'Read the current scene: the serialized scene program (the diffable source of truth), the ' +
      'placement aliases, and the live placement / overlap counts. Use it to see what you have ' +
      'built before deciding the next move.',
    inputSchema: empty,
    callback: () => {
      const ev = model.placements();
      return {
        program: serialize(model),
        placementCount: ev.placements.length,
        overlapCount: ev.overlaps.length,
        aliases: model.statements().map((s) => s.alias),
      } as JSONValue;
    },
  });

  const validateTool: Tool = tool({
    name: 'scene_validate',
    description:
      'Check the scene for footprint overlaps. Returns each colliding pair (a, b) with a penetration ' +
      'depth and a `separation` vector [x,y,z] — pass its x and z to scene_move as a delta on one of ' +
      'the pair to push them apart. An empty list means the scene is clean.',
    inputSchema: empty,
    callback: () => {
      const { overlaps } = model.placements();
      return {
        ok: overlaps.length === 0,
        count: overlaps.length,
        overlaps,
      } as unknown as JSONValue;
    },
  });

  const renderTool: Tool = tool({
    name: 'scene_render',
    description:
      'Render the WHOLE scene from three canonical angles (a labelled grid) so you can SEE the ' +
      'composition: spacing, facing, groupings, silhouette, and any overlaps the numbers miss. ' +
      'Call it after a batch of placements/edits, judge it, then refine. No argument.',
    inputSchema: empty,
    callback: async () => {
      const res = await render({ placements: model.placements().placements });
      if (res.ok && opts.onCandidate) {
        const b64 = res.pngBase64 ?? res.perCameraBase64?.[0];
        if (b64) {
          try {
            opts.onCandidate({
              program: serialize(model),
              pngBase64: b64,
              ...(res.tris != null ? { tris: res.tris } : {}),
            });
          } catch {
            // candidate sink is best-effort
          }
        }
      }
      return renderToCallback(
        res,
        'scene_render',
        evidenceHistory,
        opts.renderObservationPort,
        opts.generationCallBudget,
      );
    },
  });

  const screenshotTool: Tool = tool({
    name: 'scene_screenshot_camera',
    description:
      'Render the scene from ONE camera you specify — position [x,y,z] and the target [x,y,z] it ' +
      'looks at (optional fovDeg). Use it to inspect a specific vantage: a player entry view, a ' +
      'sightline down a row, or a close read of one cluster. Returns a single image.',
    inputSchema: z.object({
      position: vec3.describe('Camera position [x,y,z] in world units (+Y up).'),
      target: vec3.describe(
        'The point [x,y,z] the camera looks at (e.g. the scene centre [0,0,0]).',
      ),
      fovDeg: z.number().optional().describe('Vertical field of view in degrees (default ~50).'),
    }),
    callback: async (input) => {
      const i = input as {
        position: [number, number, number];
        target: [number, number, number];
        fovDeg?: number;
      };
      const res = await render({
        placements: model.placements().placements,
        cameras: [
          {
            position: i.position,
            target: i.target,
            ...(i.fovDeg != null ? { fovDeg: i.fovDeg } : {}),
          },
        ],
      });
      return renderToCallback(
        res,
        'scene_screenshot_camera',
        evidenceHistory,
        opts.renderObservationPort,
        opts.generationCallBudget,
      );
    },
  });

  // ── mutate tools ──────────────────────────────────────────────────────────────

  const layoutTool: Tool = tool({
    name: 'scene_layout',
    description:
      'Lay out a set of assets into an overlap-free BASELINE, then refine by hand. Explodes into one ' +
      'editable placement per asset (each independently movable). Good as a first pass; omit `assets` ' +
      'to lay out the whole catalog. anchor "zonedCenters" spreads them across four districts + a ' +
      'centre; "single" packs them around the origin.',
    inputSchema: z.object({
      assets: z
        .array(z.string())
        .optional()
        .describe('generationIds to lay out (default: all in the catalog).'),
      anchor: z
        .enum(['single', 'zonedCenters'])
        .optional()
        .describe('Layout anchoring (default single).'),
      spacing: z.number().optional().describe('District spacing for zonedCenters (default 95).'),
      facing: z
        .enum(['scene-in', 'scene-out', 'zone-in', 'random', 'none'])
        .optional()
        .describe(
          'How laid-out assets face (default scene-in: toward the centre; zone-in: toward their ' +
            'district; scene-out: away; random / none).',
        ),
      seed: z.number().optional().describe('Layout seed (deterministic; default the scene seed).'),
      scale: z
        .number()
        .optional()
        .describe('Uniform scale applied to every laid-out asset (default 1).'),
      role: roleEnum.optional().describe('Role for the laid-out assets (default support).'),
    }),
    callback: (input) => {
      const i = input as {
        assets?: string[];
        anchor?: 'single' | 'zonedCenters';
        spacing?: number;
        facing?: 'scene-in' | 'scene-out' | 'zone-in' | 'random' | 'none';
        seed?: number;
        scale?: number;
        role?: 'hero' | 'support' | 'fill';
      };
      const ids = i.assets ?? model.catalogList().map((e) => e.generationId);
      return guarded(() =>
        model.layout(ids, {
          ...(i.anchor ? { anchor: i.anchor } : {}),
          ...(i.spacing != null ? { spacing: i.spacing } : {}),
          ...(i.facing ? { facing: i.facing } : {}),
          ...(i.seed != null ? { seed: i.seed } : {}),
          ...(i.scale != null ? { scale: i.scale } : {}),
          ...(i.role ? { role: i.role } : {}),
        }),
      );
    },
  });

  const placeTool: Tool = tool({
    name: 'scene_place',
    description:
      'Place ONE asset at a ground point [x,z] (the scene centre is [0,0]; assets are authored facing ' +
      '+X). Pick `face` deliberately: "center" to face the origin, "out" away from it, [x,z] to face a ' +
      'point, or degrees. `role` (hero/support/fill) signals intent. Returns the placement alias to ' +
      'address it later.',
    inputSchema: z.object({
      asset: z.string().describe('The generationId to place (from scene_list_assets).'),
      at: vec2.describe('Ground position [x,z] in world units.'),
      y: z
        .number()
        .optional()
        .describe('Explicit Y (default: grounded so the base sits on the terrain).'),
      face: facing.optional().describe('Facing intent (default "center").'),
      scale: z.number().optional().describe('Uniform scale (default 1).'),
      role: roleEnum.optional().describe('hero | support | fill (default support).'),
      group: z.string().optional().describe('Optional group name to bind this placement into.'),
      alias: z
        .string()
        .optional()
        .describe('A friendly alias to address this placement (default derived from the name).'),
    }),
    callback: (input) => {
      const i = input as {
        asset: string;
        at: [number, number];
        y?: number;
        face?: z.infer<typeof facing>;
        scale?: number;
        role?: 'hero' | 'support' | 'fill';
        group?: string;
        alias?: string;
      };
      return guarded(() =>
        model.addPlace(i.asset, {
          at: i.at,
          ...(i.y != null ? { y: i.y } : {}),
          ...(i.face !== undefined ? { face: i.face } : {}),
          ...(i.scale != null ? { scale: i.scale } : {}),
          ...(i.role ? { role: i.role } : {}),
          ...(i.group ? { group: i.group } : {}),
          ...(i.alias ? { alias: i.alias } : {}),
        }),
      );
    },
  });

  const clusterTool: Tool = tool({
    name: 'scene_cluster',
    description:
      'Scatter N copies of an asset around a point — overlap-free by construction. Use it for organic ' +
      'density: a cluster of crates, rocks, tents, debris. `spread` is the rough diameter. Serializes ' +
      'as a single line and is addressable as one unit (alias) or per-instance (alias#i).',
    inputSchema: z.object({
      asset: z.string().describe('The generationId to scatter.'),
      around: vec2.describe('Centre point [x,z] of the cluster.'),
      count: z.number().int().min(1).describe('How many copies.'),
      spread: z.number().describe('Approximate cluster diameter in world units.'),
      face: facing.optional().describe('Facing intent for the copies (default "center").'),
      scale: z.number().optional().describe('Uniform scale (default 1).'),
      role: roleEnum.optional().describe('hero | support | fill (default fill).'),
      group: z.string().optional().describe('Optional group name.'),
      alias: z.string().optional().describe('Alias for the cluster (default <name>_cluster).'),
    }),
    callback: (input) => {
      const i = input as {
        asset: string;
        around: [number, number];
        count: number;
        spread: number;
        face?: z.infer<typeof facing>;
        scale?: number;
        role?: 'hero' | 'support' | 'fill';
        group?: string;
        alias?: string;
      };
      return guarded(() =>
        model.addCluster(i.asset, {
          around: i.around,
          count: i.count,
          spread: i.spread,
          ...(i.face !== undefined ? { face: i.face } : {}),
          ...(i.scale != null ? { scale: i.scale } : {}),
          ...(i.role ? { role: i.role } : {}),
          ...(i.group ? { group: i.group } : {}),
          ...(i.alias ? { alias: i.alias } : {}),
        }),
      );
    },
  });

  const ringTool: Tool = tool({
    name: 'scene_ring',
    description:
      'Place N copies evenly on a circle of `radius` around a centre — overlap-free. Use it for ' +
      'deliberate radial structure: columns around a plaza, lanterns around a well, stones in a ' +
      'circle. `faceOut:true` turns the copies to face outward (default: face the centre).',
    inputSchema: z.object({
      asset: z.string().describe('The generationId to ring.'),
      center: vec2.describe('Centre point [x,z] of the ring.'),
      count: z.number().int().min(1).describe('How many copies on the circle.'),
      radius: z.number().describe('Ring radius in world units.'),
      faceOut: z
        .boolean()
        .optional()
        .describe('Face outward instead of toward the centre (default false).'),
      scale: z.number().optional().describe('Uniform scale (default 1).'),
      role: roleEnum.optional().describe('hero | support | fill (default support).'),
      group: z.string().optional().describe('Optional group name.'),
      alias: z.string().optional().describe('Alias for the ring (default <name>_ring).'),
    }),
    callback: (input) => {
      const i = input as {
        asset: string;
        center: [number, number];
        count: number;
        radius: number;
        faceOut?: boolean;
        scale?: number;
        role?: 'hero' | 'support' | 'fill';
        group?: string;
        alias?: string;
      };
      return guarded(() =>
        model.addRing(i.asset, {
          center: i.center,
          count: i.count,
          radius: i.radius,
          ...(i.faceOut != null ? { faceOut: i.faceOut } : {}),
          ...(i.scale != null ? { scale: i.scale } : {}),
          ...(i.role ? { role: i.role } : {}),
          ...(i.group ? { group: i.group } : {}),
          ...(i.alias ? { alias: i.alias } : {}),
        }),
      );
    },
  });

  const moveTool: Tool = tool({
    name: 'scene_move',
    description:
      'Move a placement (by alias or stmtId): `to` sets an absolute ground point [x,z], `delta` nudges ' +
      'it by [dx,dz] (pass scene_validate’s separation x,z here to resolve an overlap), and `scale` ' +
      'resets its scale. Targets a cluster/ring by its alias to move the whole group.',
    inputSchema: z.object({
      target: z.string().describe('The placement alias (or stmtId) to move.'),
      to: vec2.optional().describe('Absolute ground position [x,z].'),
      delta: vec2.optional().describe('Relative nudge [dx,dz] (e.g. a separation vector).'),
      scale: z.number().optional().describe('New uniform scale.'),
    }),
    callback: (input) => {
      const i = input as {
        target: string;
        to?: [number, number];
        delta?: [number, number];
        scale?: number;
      };
      const r = model.move(i.target, {
        ...(i.to ? { to: i.to } : {}),
        ...(i.delta ? { delta: i.delta } : {}),
        ...(i.scale != null ? { scale: i.scale } : {}),
      });
      return (r.ok ? echo(r.alias) : r) as unknown as JSONValue;
    },
  });

  const faceTool: Tool = tool({
    name: 'scene_face',
    description:
      'Re-orient a placement: "center" faces the scene origin, "out" faces away, [x,z] faces that ' +
      'point, or pass degrees. For a ring, "out"/"center" flips faceOut. Facing is how a scene reads ' +
      'as intentional — point heroes at the viewer, turn supporting rows to frame them.',
    inputSchema: z.object({
      target: z.string().describe('The placement alias (or stmtId) to re-orient.'),
      face: facing.describe('Facing intent: "center" | "out" | [x,z] | degrees.'),
    }),
    callback: (input) => {
      const i = input as { target: string; face: z.infer<typeof facing> };
      const r = model.face(i.target, i.face);
      return (r.ok ? echo(r.alias) : r) as unknown as JSONValue;
    },
  });

  const groupTool: Tool = tool({
    name: 'scene_group',
    description:
      'Bind several placements into a named group, optionally nudging (`delta`) or relocating (`to`) ' +
      'them together — so a courtyard, a market row, or a camp moves as one unit. Returns the group ' +
      'name and its members.',
    inputSchema: z.object({
      targets: z.array(z.string()).min(1).describe('Placement aliases (or stmtIds) to group.'),
      name: z.string().optional().describe('Group name (default group_N).'),
      delta: vec2.optional().describe('Move the whole group by [dx,dz].'),
      to: vec2.optional().describe('Move every member to [x,z].'),
    }),
    callback: (input) => {
      const i = input as {
        targets: string[];
        name?: string;
        delta?: [number, number];
        to?: [number, number];
      };
      const r = model.group(i.targets, {
        ...(i.name ? { name: i.name } : {}),
        ...(i.delta ? { delta: i.delta } : {}),
        ...(i.to ? { to: i.to } : {}),
      });
      if (!r.ok) return r as JSONValue;
      const ev = capture();
      return {
        ok: true,
        group: r.group,
        members: r.members,
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
      } as JSONValue;
    },
  });

  const removeTool: Tool = tool({
    name: 'scene_remove',
    description:
      'Remove a placement (by alias or stmtId) from the scene — for a cluster/ring this drops the ' +
      'whole group. Use it to declutter or swap an asset out. Returns the remaining placement count.',
    inputSchema: z.object({
      target: z.string().describe('The placement alias (or stmtId) to remove.'),
    }),
    callback: (input) => {
      const i = input as { target: string };
      const r = model.remove(i.target);
      if (!r.ok) return r as JSONValue;
      const ev = capture();
      return {
        ok: true,
        removed: r.removed,
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
      } as JSONValue;
    },
  });

  const setEnvironmentTool: Tool = tool({
    name: 'scene_set_environment',
    description:
      "Set the scene's ground + sky THEME (terrain colour, sun, fog) — a scene-level choice, not a " +
      'placement. Match it to the setting: "edo" for a Japanese / Edo castle-town scene (warm earth ' +
      'ground, soft hanami sky), "desert"/"egypt" for arid, "snow"/"arctic" for cold, "meadow" for ' +
      'green, "plaza"/"studio"/"night" for neutral or dark. Call it once, early. Does not affect ' +
      'placements or overlaps.',
    inputSchema: z.object({
      ground: groundThemeEnum.describe('The ground/sky theme id.'),
    }),
    callback: (input) => {
      const i = input as { ground: z.infer<typeof groundThemeEnum> };
      model.setEnvironment(i.ground);
      const ev = capture();
      return {
        ok: true,
        environment: i.ground,
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
      } as JSONValue;
    },
  });

  const setBackdropTool: Tool = tool({
    name: 'scene_set_backdrop',
    description:
      'Set ONE atmosphere backdrop rendered as a sky billboard on the horizon (not a placed asset): ' +
      '"fuji" a snow-capped Mt. Fuji (use it for a Japanese / Edo scene), "sun-disc" a low sun, ' +
      '"aurora" northern lights, "mushroom-cloud". Place it far behind the composition on the view ' +
      'axis (default pos [0, 20, -160]); scale it up to dominate the skyline. Optional — omit if no ' +
      'backdrop fits. Call it once, early.',
    inputSchema: z.object({
      kind: backdropKindEnum.describe('The backdrop kind.'),
      pos: vec3.optional().describe('Base position [x,y,z] on the horizon (default [0,20,-160]).'),
      scale: z.number().optional().describe('Visual scale multiplier (default 1).'),
    }),
    callback: (input) => {
      const i = input as {
        kind: z.infer<typeof backdropKindEnum>;
        pos?: [number, number, number];
        scale?: number;
      };
      // Default pos so the persisted backdrop always satisfies Studio's required pos field.
      const pos: [number, number, number] = i.pos ?? [0, 20, -160];
      model.setBackdrop({ kind: i.kind, pos, ...(i.scale != null ? { scale: i.scale } : {}) });
      const ev = capture();
      return {
        ok: true,
        backdrop: { kind: i.kind, pos, ...(i.scale != null ? { scale: i.scale } : {}) },
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
      } as JSONValue;
    },
  });

  const paintTool: Tool = tool({
    name: 'scene_paint',
    description:
      'PAINT the ground to match your layout — flat zones drawn onto the terrain (NOT placed ' +
      'assets), so the town reads as built on purpose. Pass the full set of zones at once; this ' +
      'REPLACES any previous paint. Coordinates are the same [x,z] world units you place assets in. ' +
      'Kinds: stone-path (a paved avenue/courtyard), gravel (raked garden), flagstone, concrete, ' +
      'sand, grass, asphalt, snow, ice. Two shapes: a "strip" is a long band — ' +
      '{ type:"strip", axis:"x"|"z", offset:<the fixed cross-axis coord>, half:<half-width>, ' +
      'from:<start along axis>, to:<end along axis> } — use it for the central avenue (e.g. a ' +
      'stone-path strip down the axis from the entrance gate to the hero); a "rect" is a patch — ' +
      '{ type:"rect", x, z, hx:<half-x>, hz:<half-z> } — use it for a market plaza or a garden. ' +
      'Author a few deliberate zones (an avenue + a plaza or two), sized to span the assets they sit ' +
      'under. Call once, after you have placed the buildings so the paint lines up.',
    inputSchema: z.object({
      zones: z
        .array(
          z.object({ kind: paintKindEnum, shape: paintShape, laneLine: z.boolean().optional() }),
        )
        .max(24)
        .describe('The full set of ground-paint zones (replaces any previous paint).'),
    }),
    callback: (input) => {
      const i = input as { zones: ScenePaintZoneSpec[] };
      model.setPaint(i.zones);
      const ev = capture();
      return {
        ok: true,
        paintZones: i.zones.length,
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
      } as JSONValue;
    },
  });

  const finalizeTool: Tool = tool({
    name: 'scene_finalize',
    description:
      'Lock in the current scene as the FINAL composition. Call this exactly once, after scene_render ' +
      'reads as a cohesive, overlap-free, intentional scene. No argument — it finalizes exactly what ' +
      'you have placed. Returns the final program + placement/overlap counts.',
    inputSchema: empty,
    callback: () => {
      const ev = capture();
      sink.finalized = true;
      return {
        ok: true,
        recorded: true,
        placements: ev.placements.length,
        overlaps: ev.overlaps.length,
        program: sink.program,
      } as JSONValue;
    },
  });

  return [
    listAssetsTool,
    viewTool,
    validateTool,
    renderTool,
    screenshotTool,
    layoutTool,
    placeTool,
    clusterTool,
    ringTool,
    moveTool,
    faceTool,
    groupTool,
    removeTool,
    setEnvironmentTool,
    setBackdropTool,
    paintTool,
    finalizeTool,
  ];
}