@womp/spark-agent 3.0.3 → 4.0.1

package/dist/server/standalone.js

@@ -5,7 +5,7 @@ import express from "express";
 import { getSparkModel, SPARK_MODELS } from "../models.js";
 import { KakapoAPI, KakapoRpcError } from "@womp/kakapo-sdk";
 import { captureSdkSceneScreenshot } from "../sdk-scene-screenshot.js";
-import { composeCapabilities, createAccountCapability, createGeometryCapability, createOpenScadCapability, createSceneCapability, createSceneHealthCapability, } from "../capabilities.js";
+import { composeCapabilities, createAccountCapability, createGeometryCapability, createOpenScadCapability, createSceneCapability, } from "../capabilities.js";
 import { loadDemoSceneMaterials } from "./demo-scene-materials.js";
 import { createDemoAccountHost } from "./demo-account.js";
 import { createSdkSceneEditor, createSdkSceneHost, } from "../sdk-scene-host.js";
@@ -20,6 +20,7 @@ import { createSparkRunExecutor } from "./executor.js";
 import { createSparkAgentRouter } from "./express.js";
 import { SparkAgentService } from "./service.js";
 import { SqliteSparkStore } from "./sqlite-store.js";
+import { clearSceneContents } from "./scene-actions.js";
 export async function checkStandaloneServices(api) {
     const [fonts, openScad] = await Promise.allSettled([
         api.listFonts(),
@@ -99,6 +100,7 @@ export async function createStandaloneSparkAgentApp(options) {
                 const sceneHost = createSdkSceneHost({
                     ...editorOptions,
                     editor,
+                    health: createSdkSceneHealthHost(editor, onHealth),
                     onSceneCommitted: async (_operation, api) => {
                         const sceneHealth = await readStableSdkSceneHealth(api, getSdkSceneAreaIds(api), context.signal);
                         onHealth(sceneHealth);
@@ -108,13 +110,13 @@ export async function createStandaloneSparkAgentApp(options) {
                     screenshot: async (settings, invocation) => {
                         invocation.signal.throwIfAborted();
                         const image = await captureSdkSceneScreenshot(api, settings);
+                        options.onScreenshot?.(context.runId);
                         invocation.signal.throwIfAborted();
                         return artifactStore.write(context.ownerId, image);
                     },
                 });
                 const capabilityBindings = {
                     scene: createSceneCapability(sceneHost),
-                    health: createSceneHealthCapability(createSdkSceneHealthHost(editor, onHealth)),
                     geometry: createGeometryCapability(createSdkGeometryHost({
                         editor,
                         repairs,
@@ -208,7 +210,21 @@ export async function createStandaloneSparkAgentApp(options) {
             };
         },
     });
-    const service = new SparkAgentService({ store, executeRun });
+    let clearingScene = false;
+    let activeRuns = 0;
+    const service = new SparkAgentService({ store, executeRun: async (context) => {
+            if (clearingScene)
+                throw new Error("The scene is being cleared. Try again when it finishes.");
+            activeRuns++;
+            try {
+                const run = await executeRun(context);
+                return { ...run, result: run.result.finally(() => { activeRuns--; }) };
+            }
+            catch (error) {
+                activeRuns--;
+                throw error;
+            }
+        } });
     try {
         for (const run of await store.listInterruptedRuns())
             await service.recoverInterruptedRun(run.id);
@@ -222,6 +238,41 @@ export async function createStandaloneSparkAgentApp(options) {
     app.get("/health", (_request, response) => {
         response.json({ status: "ok" });
     });
+    app.post(`${apiBasePath}/scene/clear`, async (request, response) => {
+        // Custom headers require a CORS preflight, preventing cross-site form submissions.
+        if (request.get("X-Spark-Action") !== "clear-scene") {
+            response.status(403).json({ error: "Use the standalone UI to clear the scene." });
+            return;
+        }
+        if (clearingScene || activeRuns > 0) {
+            response.status(409).json({ error: "Stop the active agent run before clearing the scene." });
+            return;
+        }
+        clearingScene = true;
+        const api = new KakapoAPI({ url: options.kakapoUrl, requestTimeoutMs: 30_000 });
+        try {
+            await api.connect();
+            const { save } = await api.editSceneAndSave(clearSceneContents);
+            const warning = save.status === "failed" || save.status === "unknown"
+                ? `Scene cleared, but saving ${save.status === "failed" ? "failed" : "could not be confirmed"}: ${save.error} Do not repeat the clear operation.`
+                : undefined;
+            response.json({ ok: true, warning });
+        }
+        catch (error) {
+            response.status(500).json({ error: error instanceof Error ? error.message : "Could not clear the scene." });
+        }
+        finally {
+            api.disconnect();
+            clearingScene = false;
+        }
+    });
+    app.use(apiBasePath, (request, response, next) => {
+        if (clearingScene && request.method === "POST" && request.path.endsWith("/messages")) {
+            response.status(409).json({ error: "The scene is being cleared. Try again when it finishes." });
+            return;
+        }
+        next();
+    });
     app.use(apiBasePath, createSparkAgentRouter({ service, artifactStore }));
     return Object.assign(app, {
         async dispose() {

package/dist/server/store.d.ts

@@ -1,4 +1,4 @@
-import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun } from "./types.js";
+import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun, SparkRunSettings } from "./types.js";
 import type { StoredSparkChunk } from "../ui.js";
 export declare class MemorySparkAgentStore implements SparkAgentStore {
     private readonly conversations;
@@ -8,6 +8,8 @@ export declare class MemorySparkAgentStore implements SparkAgentStore {
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     saveConversation(conversation: SparkConversation): Promise<void>;
+    saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
+    deleteConversation(id: string): Promise<boolean>;
     createRun(run: SparkRun): Promise<void>;
     getRun(id: string): Promise<SparkRun | undefined>;
     saveRun(run: SparkRun): Promise<void>;

package/dist/server/store.js

@@ -28,7 +28,27 @@ export class MemorySparkAgentStore {
         if (this.conversations.has(conversation.id) === false) {
             throw new Error(`Conversation ${conversation.id} does not exist.`);
         }
-        this.conversations.set(conversation.id, copy(conversation));
+        const { settings: _settings, ...history } = conversation;
+        const settings = this.conversations.get(conversation.id).settings;
+        this.conversations.set(conversation.id, copy({ ...history, ...(settings ? { settings } : {}) }));
+    }
+    async saveConversationSettings(id, settings) {
+        const conversation = this.conversations.get(id);
+        if (conversation === undefined)
+            throw new Error(`Conversation ${id} does not exist.`);
+        conversation.settings = copy(settings);
+    }
+    async deleteConversation(id) {
+        if (this.conversations.get(id)?.activeRunId !== undefined)
+            return false;
+        for (const [runId, run] of this.runs) {
+            if (run.conversationId !== id)
+                continue;
+            this.chunks.delete(runId);
+            this.runs.delete(runId);
+        }
+        this.conversations.delete(id);
+        return true;
     }
     async createRun(run) {
         if (this.runs.has(run.id))

package/dist/server/types.d.ts

@@ -6,6 +6,7 @@ export type SparkConversation = {
     ownerId: string;
     title: string;
     messages: SparkUIMessage[];
+    settings?: SparkRunSettings;
     activeRunId?: string;
     createdAt: string;
     updatedAt: string;
@@ -45,6 +46,10 @@ export interface SparkAgentStore {
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     saveConversation(conversation: SparkConversation): Promise<void>;
+    /** Update preferences without replacing history; saveConversation must preserve them. */
+    saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
+    /** Atomically delete an idle conversation and its runs/chunks; false if active. */
+    deleteConversation(id: string): Promise<boolean>;
     createRun(run: SparkRun): Promise<void>;
     getRun(id: string): Promise<SparkRun | undefined>;
     saveRun(run: SparkRun): Promise<void>;

package/dist/simple-bench-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/simple-bench-cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { loadEnvFile } from "node:process";
+import { parseArgs } from "node:util";
+import path from "node:path";
+import { SPARK_MODELS } from "./models.js";
+import { BENCH_PROMPTS } from "./simple-bench-prompts.js";
+import { runSimpleBench } from "./simple-bench.js";
+async function main() {
+    const { values } = parseArgs({ options: {
+            model: { type: "string", default: "gpt-6-astra" }, reasoning: { type: "string", default: "high" },
+            "kakapo-url": { type: "string" }, output: { type: "string" }, only: { type: "string" },
+            "timeout-minutes": { type: "string", default: "30" },
+            help: { type: "boolean" },
+        } });
+    if (values.help) {
+        console.log(`simple-bench [options]
+
+Runs ${BENCH_PROMPTS.length} prompts sequentially against a dedicated Kakapo scene.
+WARNING: removes all objects/materials before every prompt and makes paid model calls.
+Stop other agents/editors using this Kakapo instance first.
+
+--model <id>             Default: gpt-6-astra. Models: ${SPARK_MODELS.map((model) => model.id).join(", ")}
+--reasoning <effort>     Default: high
+--kakapo-url <url>       Default: KAKAPO_URL from .env, or ws://127.0.0.1:5502
+--output <directory>     New directory only; default: .spark/bench/<timestamp>
+--only <id>              ${BENCH_PROMPTS.map((prompt) => prompt.id).join(", ")}
+--timeout-minutes <n>    Per-case timeout; default: 30`);
+        return;
+    }
+    const model = SPARK_MODELS.find((item) => item.id === values.model);
+    if (!model)
+        throw new Error("Select a supported model using --model. See --help.");
+    const reasoning = values.reasoning;
+    if (!model.reasoningEfforts.includes(reasoning))
+        throw new Error("Unsupported reasoning effort for this model.");
+    const timeoutMs = Number(values["timeout-minutes"]) * 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+        throw new Error("Invalid timeout.");
+    if (existsSync(".env"))
+        loadEnvFile();
+    const key = { openai: "OPENAI_API_KEY", anthropic: "ANTHROPIC_API_KEY", google: "GEMINI_API_KEY" }[model.provider];
+    if (!process.env[key]?.trim())
+        throw new Error(`${key} is required in the environment or .env.`);
+    const controller = new AbortController();
+    const stop = () => controller.abort(new Error("Benchmark interrupted."));
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    const output = path.resolve(values.output ?? `.spark/bench/${new Date().toISOString().replaceAll(":", "-")}`);
+    console.log(`Results: ${output}`);
+    try {
+        if (!await runSimpleBench({
+            settings: { modelId: model.id, reasoningEffort: reasoning },
+            kakapoUrl: values["kakapo-url"] ?? process.env.KAKAPO_URL ?? "ws://127.0.0.1:5502",
+            output, only: values.only, timeoutMs, signal: controller.signal,
+        }))
+            process.exitCode = 1;
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/simple-bench-prompts.d.ts

@@ -0,0 +1,28 @@
+export declare const BENCH_PROMPTS: readonly [{
+    readonly id: "armchair";
+    readonly prompt: "Make a mustard-yellow upholstered armchair, 85 cm wide, 90 cm deep, and 85 cm tall. Give it a thick square seat cushion, a slightly reclined backrest, rounded armrests, and four short tapered wooden legs.";
+}, {
+    readonly id: "desk-lamp";
+    readonly prompt: "Make a matte-black desk lamp, 45 cm tall, with a circular base 18 cm in diameter, two slender articulated arms, and a conical shade 15 cm wide. Give the shade a white interior and a warm-white bulb.";
+}, {
+    readonly id: "coffee-mug";
+    readonly prompt: "Make a teal ceramic mug, 10 cm tall and 9 cm in diameter, with a gently rounded base, an open top, a thick rim, and a large C-shaped handle. Give it a cream-colored interior.";
+}, {
+    readonly id: "bookshelf";
+    readonly prompt: "Make a light-oak bookshelf, 180 cm tall, 90 cm wide, and 30 cm deep. Give it five evenly spaced open compartments, thick rectangular side panels, a solid back panel, and a recessed base.";
+}, {
+    readonly id: "backpack";
+    readonly prompt: "Make a navy-blue backpack, 45 cm tall, 30 cm wide, and 18 cm deep. Give it a rounded rectangular body, a large front zipper pocket, two padded shoulder straps, a top carry handle, and light-gray zipper pulls.";
+}, {
+    readonly id: "toaster";
+    readonly prompt: "Make a cream-colored two-slot toaster, 28 cm wide, 18 cm deep, and 20 cm tall. Give it rounded corners, a brushed-metal top, two long bread slots, a silver side lever, and a circular browning dial.";
+}, {
+    readonly id: "plant-pot";
+    readonly prompt: "Make a terracotta plant pot, 25 cm tall, tapering from a 30 cm opening to a 20 cm base. Give it a thick rolled rim and dark soil containing a small plant with six broad green leaves on short stems.";
+}, {
+    readonly id: "suitcase";
+    readonly prompt: "Make a burgundy hard-shell suitcase, 65 cm tall, 42 cm wide, and 26 cm deep. Give it rounded corners, five vertical ribs on each broad face, four black spinner wheels, a silver telescoping handle, and a black side carry handle.";
+}, {
+    readonly id: "dining-table";
+    readonly prompt: "Make a rectangular walnut dining table, 160 cm long, 90 cm wide, and 75 cm tall. Give it a 4 cm thick tabletop with softly rounded corners, four square tapered legs, and a recessed wooden apron beneath the top.";
+}];

package/dist/simple-bench-prompts.js

@@ -0,0 +1,11 @@
+export const BENCH_PROMPTS = [
+    { id: "armchair", prompt: "Make a mustard-yellow upholstered armchair, 85 cm wide, 90 cm deep, and 85 cm tall. Give it a thick square seat cushion, a slightly reclined backrest, rounded armrests, and four short tapered wooden legs." },
+    { id: "desk-lamp", prompt: "Make a matte-black desk lamp, 45 cm tall, with a circular base 18 cm in diameter, two slender articulated arms, and a conical shade 15 cm wide. Give the shade a white interior and a warm-white bulb." },
+    { id: "coffee-mug", prompt: "Make a teal ceramic mug, 10 cm tall and 9 cm in diameter, with a gently rounded base, an open top, a thick rim, and a large C-shaped handle. Give it a cream-colored interior." },
+    { id: "bookshelf", prompt: "Make a light-oak bookshelf, 180 cm tall, 90 cm wide, and 30 cm deep. Give it five evenly spaced open compartments, thick rectangular side panels, a solid back panel, and a recessed base." },
+    { id: "backpack", prompt: "Make a navy-blue backpack, 45 cm tall, 30 cm wide, and 18 cm deep. Give it a rounded rectangular body, a large front zipper pocket, two padded shoulder straps, a top carry handle, and light-gray zipper pulls." },
+    { id: "toaster", prompt: "Make a cream-colored two-slot toaster, 28 cm wide, 18 cm deep, and 20 cm tall. Give it rounded corners, a brushed-metal top, two long bread slots, a silver side lever, and a circular browning dial." },
+    { id: "plant-pot", prompt: "Make a terracotta plant pot, 25 cm tall, tapering from a 30 cm opening to a 20 cm base. Give it a thick rolled rim and dark soil containing a small plant with six broad green leaves on short stems." },
+    { id: "suitcase", prompt: "Make a burgundy hard-shell suitcase, 65 cm tall, 42 cm wide, and 26 cm deep. Give it rounded corners, five vertical ribs on each broad face, four black spinner wheels, a silver telescoping handle, and a black side carry handle." },
+    { id: "dining-table", prompt: "Make a rectangular walnut dining table, 160 cm long, 90 cm wide, and 75 cm tall. Give it a 4 cm thick tabletop with softly rounded corners, four square tapered legs, and a recessed wooden apron beneath the top." },
+];

package/dist/simple-bench.d.ts

@@ -0,0 +1,15 @@
+import type { SparkRunSettings } from "./server/types.js";
+export { createBenchMetrics } from "./run-metrics.js";
+type BenchCost = {
+    costUsd: number | null;
+    costStatus: "estimated" | "partial" | "unavailable";
+};
+export declare function totalBenchCost(results: readonly BenchCost[]): BenchCost;
+export declare function runSimpleBench(options: {
+    settings: SparkRunSettings;
+    kakapoUrl: string;
+    output: string;
+    only?: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}): Promise<boolean>;

package/dist/simple-bench.js

@@ -0,0 +1,175 @@
+import { once } from "node:events";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { KakapoAPI } from "@womp/kakapo-sdk";
+import { z } from "zod";
+import { SparkChatTransport } from "./client.js";
+import { createStandaloneSparkAgentApp } from "./server/standalone.js";
+import { BENCH_PROMPTS } from "./simple-bench-prompts.js";
+import { createBenchMetrics } from "./run-metrics.js";
+export { createBenchMetrics } from "./run-metrics.js";
+export function totalBenchCost(results) {
+    const known = results.filter((result) => result.costUsd !== null);
+    return {
+        costUsd: known.length ? known.reduce((sum, result) => sum + result.costUsd, 0) : null,
+        costStatus: !known.length ? "unavailable" : results.some((result) => result.costStatus !== "estimated") ? "partial" : "estimated",
+    };
+}
+function costLabel(cost) {
+    return cost.costUsd === null ? "cost unavailable" : `$${cost.costUsd.toFixed(4)} USD (${cost.costStatus})`;
+}
+export async function runSimpleBench(options) {
+    const prompts = BENCH_PROMPTS.filter((item) => !options.only || item.id === options.only);
+    if (!prompts.length)
+        throw new Error("Unknown prompt ID. Use --help to list the available prompts.");
+    // Never reuse a result directory or overwrite a previous benchmark.
+    await mkdir(path.dirname(options.output), { recursive: true });
+    await mkdir(options.output);
+    const captures = new Map();
+    const app = await createStandaloneSparkAgentApp({
+        kakapoUrl: options.kakapoUrl,
+        storagePath: path.join(options.output, "history.sqlite"),
+        openAiApiKey: process.env.OPENAI_API_KEY,
+        anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+        geminiApiKey: process.env.GEMINI_API_KEY,
+        onScreenshot: (runId) => captures.set(runId, (captures.get(runId) ?? 0) + 1),
+    });
+    const server = app.listen(0, "127.0.0.1");
+    const results = [];
+    const startedAt = new Date().toISOString();
+    const report = async () => {
+        await writeFile(path.join(options.output, "results.json"), JSON.stringify({
+            version: 1, startedAt, nodeVersion: process.version, settings: options.settings,
+            timeoutMs: options.timeoutMs, camera: "fitted-perspective-preserving-direction", plannedPrompts: prompts.map((item) => item.id),
+            totalCost: totalBenchCost(results), results,
+        }, null, 2));
+        const columns = ["id", "status", "steps", "readSkill", "executeJavaScript", "screenshots", "durationMs", "costUsd", "costStatus", "image", "error"];
+        const quote = (value) => `"${String(value ?? "").replaceAll('"', '""')}"`;
+        const total = { id: "TOTAL", ...totalBenchCost(results) };
+        await writeFile(path.join(options.output, "results.csv"), [columns.join(","), ...[...results, total].map((result) => columns.map((key) => quote(result[key])).join(","))].join("\n"));
+    };
+    try {
+        await once(server, "listening");
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new Error("Benchmark server did not start.");
+        const base = `http://127.0.0.1:${address.port}/agent`;
+        const transport = new SparkChatTransport({ api: base, getSettings: () => options.settings });
+        for (const item of prompts) {
+            options.signal.throwIfAborted();
+            const result = { ...item, status: "failed", steps: 0, readSkill: 0, executeJavaScript: 0, screenshots: 0, durationMs: null, costUsd: null, costStatus: "unavailable" };
+            const metrics = createBenchMetrics();
+            let started;
+            let ended;
+            let usageComplete = false;
+            const signal = AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs)]);
+            try {
+                console.log(`Running ${item.id}…`);
+                const clear = await fetch(`${base}/scene/clear`, { method: "POST", headers: { "X-Spark-Action": "clear-scene" }, signal });
+                const cleared = await clear.json();
+                if (!clear.ok || cleared.warning)
+                    throw new Error(cleared.error ?? cleared.warning ?? "Scene cleanup failed.");
+                const conversation = await transport.createConversation({ title: `simple-bench: ${item.id}` });
+                result.conversationId = conversation.id;
+                started = performance.now();
+                const stream = await transport.sendMessages({
+                    trigger: "submit-message", chatId: conversation.id, messageId: undefined,
+                    messages: [{ id: crypto.randomUUID(), role: "user", parts: [{ type: "text", text: item.prompt }] }],
+                    abortSignal: signal,
+                });
+                for await (const value of stream) {
+                    const chunk = value;
+                    metrics.accept(chunk);
+                    if (chunk.type === "data-run-status") {
+                        result.runId = chunk.data.runId;
+                        result.status = chunk.data.status;
+                        if (chunk.data.error)
+                            result.error = chunk.data.error;
+                    }
+                    if (chunk.type === "error")
+                        result.error = chunk.errorText;
+                }
+                ended = performance.now();
+                usageComplete = result.status === "completed";
+                const saved = await transport.getConversation(conversation.id);
+                await writeFile(path.join(options.output, `${item.id}.conversation.json`), JSON.stringify(saved, null, 2));
+                const reply = saved.messages.filter((message) => message.role === "assistant").at(-1);
+                await writeFile(path.join(options.output, `${item.id}.md`), reply?.parts.filter((part) => part.type === "text").map((part) => part.text).join("\n\n") ?? "");
+                if (result.status !== "completed")
+                    throw new Error(result.error ?? `Run ended with status ${result.status}.`);
+                const api = new KakapoAPI({ url: options.kakapoUrl, requestTimeoutMs: 30_000 });
+                try {
+                    await api.connect();
+                    const ids = api.listNodes({ parentId: 0 })
+                        .filter((node) => node.kind !== "light" && (!("hidden" in node) || !node.hidden))
+                        .map((node) => node.id);
+                    const bounds = await api.getNodesBoundingBox(ids);
+                    const viewport = await api.captureScreenshot({});
+                    const { camera } = await api.refreshScene();
+                    const direction = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).parse(camera.dir);
+                    const directionLength = Math.hypot(direction.x, direction.y, direction.z);
+                    if (directionLength === 0)
+                        throw new Error("Cannot frame a scene with a zero camera direction.");
+                    const target = {
+                        x: (bounds.min.x + bounds.max.x) / 2,
+                        y: (bounds.min.y + bounds.max.y) / 2,
+                        z: (bounds.min.z + bounds.max.z) / 2,
+                    };
+                    const radius = Math.hypot(bounds.max.x - bounds.min.x, bounds.max.y - bounds.min.y, bounds.max.z - bounds.min.z) / 2;
+                    const halfAngle = Math.atan(Math.tan(Math.PI / 6) * Math.min(1, viewport.height / viewport.width));
+                    const offset = Math.max(0.1, radius * 1.1 / Math.sin(halfAngle)) / directionLength;
+                    const image = await api.captureScreenshot({ camera: {
+                            position: { x: target.x - direction.x * offset, y: target.y - direction.y * offset, z: target.z - direction.z * offset },
+                            target, projection: "perspective", horizontalFovDegrees: 60,
+                        }, timeoutMs: 30_000 });
+                    result.image = `${item.id}.jpg`;
+                    await writeFile(path.join(options.output, result.image), image.data);
+                }
+                finally {
+                    api.disconnect();
+                }
+            }
+            catch (error) {
+                ended ??= performance.now();
+                result.error = error instanceof Error ? error.message : String(error);
+                result.status = signal.aborted ? "cancelled" : "failed";
+                if (result.conversationId) {
+                    try {
+                        await transport.cancelRun(result.conversationId);
+                    }
+                    catch (cancelError) {
+                        result.error += ` Cancellation failed: ${String(cancelError)}`;
+                    }
+                }
+            }
+            finally {
+                result.durationMs = started === undefined ? null : Math.round((ended ?? performance.now()) - started);
+                Object.assign(result, metrics.snapshot());
+                if (started === undefined) {
+                    result.costUsd = 0;
+                    result.costStatus = "estimated";
+                }
+                else if (!usageComplete && result.costUsd !== null)
+                    result.costStatus = "partial";
+                result.screenshots = result.runId ? captures.get(result.runId) ?? 0 : 0;
+                results.push(result);
+                await report();
+                console.log(`${item.id}: ${result.status}, ${result.steps} steps, ${result.durationMs ?? 0} ms, ${costLabel(result)}`);
+                console.log(`Benchmark total: ${costLabel(totalBenchCost(results))}`);
+            }
+            // Do not clear again after an uncertain mutation, failed cleanup or cancelled run.
+            if (result.status !== "completed")
+                break;
+        }
+        return results.every((result) => result.status === "completed") && results.length === prompts.length;
+    }
+    finally {
+        try {
+            await app.dispose();
+        }
+        finally {
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        }
+    }
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ReasoningEffort } from "./models.js";
-import type { ScreenshotView } from "@womp/kakapo-sdk";
+import type { ScreenshotImage } from "@womp/kakapo-sdk";
+import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 export type SparkImage = {
     name: string;
     mediaType: string;
@@ -15,14 +16,7 @@ export type SparkRunInput = {
     reasoningEffort: ReasoningEffort;
     context: SparkContextMessage[];
 };
-export type ExecutionScreenshot = {
-    data: Uint8Array;
-    mediaType: "image/jpeg";
-    width: number;
-    height: number;
-    view: ScreenshotView | "current";
-    targetId: number;
-};
+export type ExecutionScreenshot = ScreenshotImage;
 export type ExecutionResult = {
     ok: boolean;
     purpose: string;
@@ -70,8 +64,5 @@ export interface SparkRuntime {
     connect(): Promise<void>;
     disconnect(): void;
     execute(code: string, purpose: string): Promise<ExecutionResult>;
-    screenshot(input: {
-        targetId?: number;
-        view?: ScreenshotView;
-    }): Promise<ExecutionScreenshot>;
+    screenshot(input: SceneScreenshotOptions): Promise<ExecutionScreenshot>;
 }

package/dist/ui.d.ts

@@ -1,4 +1,5 @@
 import type { InferUIMessageChunk, UIMessage } from "ai";
+import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import { z } from "zod";
 import type { ExecutionReceipt, SparkSkill } from "./capabilities.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
@@ -95,14 +96,8 @@ export type ExecuteJavaScriptOutput = {
     }[];
     error?: string;
 };
-export type ScreenshotInput = {
-    targetId?: number;
-    view?: "front" | "back" | "left" | "right" | "top" | "bottom" | "isometric";
-};
-export type ScreenshotOutput = SparkArtifact & {
-    targetId: number;
-    view: string;
-};
+export type ScreenshotInput = SceneScreenshotOptions;
+export type ScreenshotOutput = SparkArtifact;
 export type SparkUITools = {
     execute_javascript: {
         input: ExecuteJavaScriptInput;

package/dist/womp-scene-api.d.ts

@@ -79,7 +79,10 @@ export type WompSceneApiContext = {
 };
 export type WompSceneApi = ReturnType<typeof createWompSceneApi>;
 export declare function sceneNodeType(kind: NodeKind): number;
+/** Align local +Z toward target. Both points are in the same parent-local coordinates. */
 declare function lookAt(origin: Vec3, target: Vec3): Vec3;
+/** XYZ degrees aligning the selected positive local axis to a parent-local direction. */
+declare function alignAxis(direction: Vec3, axis: "x" | "y" | "z"): Vec3;
 export declare function createWompSceneApi(context: WompSceneApiContext): {
     listSuperMaterials: () => string[];
     _getParentId: (childId: number) => number;
@@ -120,6 +123,12 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeCreate: (type: number, parentId?: number) => number;
     nodeDelete: (id: number) => void;
     nodeClone: (id: number) => number;
+    /** Deep clone; preserves sibling order and remaps internal references. Await before other edits. */
+    cloneSubtree: (id: number, options?: {
+        parentId?: number;
+        name?: string;
+        index?: number;
+    }) => Promise<number>;
     nodeList: () => number[];
     nodeChildren: (parentId: number) => number[];
     nodeSetParent: (id: number, parentId: number, index?: number) => void;
@@ -139,7 +148,9 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeSetHide: (id: number, hidden: boolean) => void;
     nodeGetOp: (id: number) => number;
     nodeSetOp: (id: number, operation: number) => void;
+    /** Blend radius in millimetres before parent scaling, independent of project units. */
     nodeGetBlend: (id: number) => number;
+    /** Set blend radius in millimetres before parent scaling; clamps to 0–500. */
     nodeSetBlend: (id: number, blend: number) => void;
     nodeGetRound: (id: number) => number;
     nodeSetRound: (id: number, round: number) => void;
@@ -148,7 +159,7 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeGetMaterialId: (id: number) => number | null;
     nodeSetMaterialId: (id: number, materialId: number) => void;
     nodeGetResolution: (id: number) => number;
-    nodeSetResolution: (id: number, resolution: number) => void;
+    nodeSetUnionResolution: (unionId: number, resolution: number) => void;
     nodeGetLightType: (id: number) => number;
     nodeSetLightType: (id: number, lightType: number) => void;
     nodeGetPower: (id: number) => number;
@@ -190,8 +201,7 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     curvePointSetHandleIn: (curveId: number, pointIndex: number, value: Vec3) => void;
     curvePointSetHandleOut: (curveId: number, pointIndex: number, value: Vec3) => void;
     curvePointCount: (curveId: number) => number;
-    curvePointAdd: (curveId: number, point?: CurvePointInput) => number;
-    curvePointInsert: (curveId: number, pointIndex: number, point?: CurvePointInput) => number;
+    curvePointAdd: (curveId: number, point: CurvePointInput, pointIndex?: number) => number;
     curvePointRemove: (curveId: number, pointIndex: number) => void;
     curvePointGetName: (curveId: number, pointIndex: number) => string;
     curvePointSetName: (curveId: number, pointIndex: number, name: string) => void;
@@ -262,6 +272,7 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     aabbCenter: (box: AABB) => Vec3;
     aabbRadius: (box: AABB) => number;
     lookAt: typeof lookAt;
+    alignAxis: typeof alignAxis;
     scenePropertiesRead: () => {
         hdr_name: string | undefined;
         hdr_multiplier: number | undefined;