@womp/spark-agent 3.0.2 → 4.0.0

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;

package/dist/womp-scene-api.js

@@ -1,6 +1,7 @@
+import { xyzRotationFromMatrix, MAX_BLEND_RADIUS_MM, MAX_MIRROR_BLEND_RADIUS_MM } from "@womp/kakapo-sdk";
 import { metadataObject, readMaterialMetadata, removeMaterialMetadata, shiftCurvePointMetadata, writeMaterialMetadata, } from "./scene-metadata.js";
 import { createSceneEnvironment } from "./scene-environment.js";
-import { convertRotationBasis, sceneUnitMultiplier, fromEngineDimensions, fromEngineBlend, fromEngineMirrorRotation, fromEnginePosition, toEngineBlend, toEngineDimensions, toEngineMirrorGoop, toEngineMirrorRotation, toEnginePosition, } from "./coordinates.js";
+import { convertRotationBasis, sceneUnitMultiplier, fromEngineDimensions, fromEngineMirrorRotation, fromEnginePosition, toEngineDimensions, toEngineMirrorRotation, toEnginePosition, } from "./coordinates.js";
 export const NodeType = {
     Primitive: 0,
     Union: 1,
@@ -143,12 +144,25 @@ function convertAABB(box, unitMultiplier) {
         },
     };
 }
+/** Align local +Z toward target. Both points are in the same parent-local coordinates. */
 function lookAt(origin, target) {
-    const forward = normalize({
+    if (![origin.x, origin.y, origin.z, target.x, target.y, target.z].every(Number.isFinite)) {
+        throw new Error("lookAt requires finite points in the same parent coordinate system.");
+    }
+    if (Math.hypot(target.x - origin.x, target.y - origin.y, target.z - origin.z) === 0) {
+        throw new Error("lookAt requires distinct origin and target points.");
+    }
+    return alignAxis({
         x: target.x - origin.x,
         y: target.y - origin.y,
         z: target.z - origin.z,
-    });
+    }, "z");
+}
+/** XYZ degrees aligning the selected positive local axis to a parent-local direction. */
+function alignAxis(direction, axis) {
+    if (!["x", "y", "z"].includes(axis))
+        throw new Error("Alignment axis must be x, y, or z.");
+    const forward = normalize(direction);
     let up = { x: 0, y: 1, z: 0 };
     let right = cross(up, forward);
     if (Math.hypot(right.x, right.y, right.z) < 1e-6) {
@@ -157,17 +171,19 @@ function lookAt(origin, target) {
     }
     right = normalize(right);
     const correctedUp = cross(forward, right);
-    return {
-        x: (Math.asin(clamp(correctedUp.z, -1, 1)) * 180) / Math.PI,
-        y: (Math.atan2(-right.z, forward.z) * 180) / Math.PI,
-        z: (Math.atan2(-correctedUp.x, correctedUp.y) * 180) / Math.PI,
-    };
+    const [x, y, z] = axis === "x" ? [forward, right, correctedUp]
+        : axis === "y" ? [right, forward, scale(correctedUp, -1)] : [right, correctedUp, forward];
+    return xyzRotationFromMatrix([
+        [x.x, y.x, z.x],
+        [x.y, y.y, z.y],
+        [x.z, y.z, z.z],
+    ]);
 }
 function normalize(value) {
     const length = Math.hypot(value.x, value.y, value.z);
-    return length < 1e-10
-        ? { x: 0, y: 0, z: 0 }
-        : { x: value.x / length, y: value.y / length, z: value.z / length };
+    if (!Number.isFinite(length) || length === 0)
+        throw new Error("Cannot orient a zero-length or non-finite direction.");
+    return { x: value.x / length, y: value.y / length, z: value.z / length };
 }
 function cross(left, right) {
     return {
@@ -286,12 +302,6 @@ export function createWompSceneApi(context) {
         rotation: { ...plane.rotation },
         ...(plane.customRotation ? { customRotation: { ...plane.customRotation } } : {}),
     }));
-    const curvePoints = (id) => requireCurve(id).points.map((point) => ({
-        ...point,
-        position: { ...point.position },
-        rotation: { ...point.rotation },
-        scale: { ...point.scale },
-    }));
     const requirePoint = (curveId, pointIndex) => {
         const index = Math.round(finite(pointIndex, "pointIndex"));
         const count = requireCurve(curveId).points.length;
@@ -338,7 +348,18 @@ export function createWompSceneApi(context) {
                 },
             }]);
     };
-    const applyPointInput = (curveId, index, input) => {
+    const addCurvePoint = (curveId, point, pointIndex) => {
+        const curve = requireCurve(curveId);
+        const count = curve.points.length;
+        if (count >= MAX_CURVE_POINTS)
+            throw new Error("A curve cannot exceed 100 points");
+        const index = pointIndex === undefined ? count : pointIndex;
+        if (!Number.isInteger(index) || index < 0 || index > count)
+            throw new Error(`Curve ${curveId}: index must be an integer from 0 through ${count}`);
+        const input = {
+            pos: { x: 0, y: 0, z: 0 }, size: { x: 1, y: 1, z: 1 },
+            materialId: curve.materialId ?? context.getDefaultMaterialId(), ...point,
+        };
         const patch = {};
         const parentScale = ancestorScale(curveId);
         if (input.pos) {
@@ -358,10 +379,11 @@ export function createWompSceneApi(context) {
             context.requireMaterial(materialId);
             patch.materialId = materialId;
         }
-        if (Object.keys(patch).length)
-            setPoint(curveId, index, patch);
-        if (input.name !== undefined)
-            setPointName(curveId, index, input.name);
+        context.call("addCurvePoint", [curveId, patch, index], () => scene.addCurvePoint(curveId, patch, index));
+        shiftCurvePointMetadata(scene, curveId, index, 1);
+        if (point.name !== undefined)
+            setPointName(curveId, index, point.name);
+        return index;
     };
     const setNodeSize = (id, sizeValue) => {
         const node = requireEditableTransform(id);
@@ -374,8 +396,12 @@ export function createWompSceneApi(context) {
             update(id, { size: { x: converted.z, y: converted.y } });
             return;
         }
-        if (!("z" in sizeValue))
-            throw new Error("size.z must be a finite number");
+        if (!("z" in sizeValue)) {
+            if (node.kind !== "primitive" ||
+                !["cylinder", "cone", "torus", "pyramid"].includes(node.primitive))
+                throw new Error("size.z must be a finite number");
+            sizeValue = { ...sizeValue, z: sizeValue.x };
+        }
         const requestedSize = vector(sizeValue, "size");
         const size = node.kind === "primitive"
             ? normalizePrimitiveSize(node.primitive, requestedSize)
@@ -404,21 +430,6 @@ export function createWompSceneApi(context) {
         }
         return converted;
     };
-    const insertCurvePoint = (curveId, pointIndex, point = {}) => {
-        const points = curvePoints(curveId);
-        if (points.length >= MAX_CURVE_POINTS)
-            throw new Error("A curve cannot exceed 100 points");
-        const index = Math.round(finite(pointIndex, "pointIndex"));
-        if (index < 0 || index > points.length)
-            throw new Error("Curve insertion index is out of range");
-        if (points.length === 0)
-            throw new Error("Cannot add to an empty curve");
-        const sourceIndex = Math.max(0, index - 1);
-        context.call("cloneCurvePoint", [curveId, sourceIndex, index], () => scene.cloneCurvePoint(curveId, sourceIndex, index));
-        shiftCurvePointMetadata(scene, curveId, index, 1);
-        applyPointInput(curveId, index, point);
-        return index;
-    };
     const api = {
         ...createSceneEnvironment(scene, context.hdrs, context.print),
         listSuperMaterials: () => {
@@ -471,29 +482,12 @@ export function createWompSceneApi(context) {
                         closed: false,
                         primitive: "sphere",
                         operation: "union",
-                        blend: toEngineBlend(0.36),
+                        blend: 0,
                         density: 80,
                         roundness: 2,
                         smoothing: 0.02,
                         materialId: context.getDefaultMaterialId(),
-                        points: [
-                            {
-                                position: scale(toEnginePosition({ x: 0, y: 2, z: 0 }), 1 / parentScale),
-                                rotation: { x: 0, y: 0, z: 0 },
-                                scale: scale(toEngineDimensions({ x: 4, y: 4, z: 4 }), 1 / parentScale),
-                                materialId: context.getDefaultMaterialId(),
-                                fixed: false,
-                                round: 0,
-                            },
-                            {
-                                position: scale(toEnginePosition({ x: 6, y: 2, z: 0 }), 1 / parentScale),
-                                rotation: { x: 0, y: 0, z: 0 },
-                                scale: scale(toEngineDimensions({ x: 4, y: 4, z: 4 }), 1 / parentScale),
-                                materialId: context.getDefaultMaterialId(),
-                                fixed: false,
-                                round: 0,
-                            },
-                        ],
+                        points: [],
                     }
                     : kind === "text"
                         ? {
@@ -533,6 +527,27 @@ export function createWompSceneApi(context) {
             context.trackNode(clone.id);
             return clone.id;
         },
+        /** Deep clone; preserves sibling order and remaps internal references. Await before other edits. */
+        cloneSubtree: async (id, options = {}) => {
+            if (id === context.rootId)
+                throw new Error("The scene root cannot be cloned");
+            const check = (nodeId) => {
+                requireNode(nodeId);
+                for (const child of scene.getNodeChildren(nodeId))
+                    check(child.id);
+            };
+            check(id);
+            if (options.parentId !== undefined)
+                requireNode(options.parentId);
+            const clone = await context.callAsync("cloneSubtree", [id, options], () => scene.cloneSubtree(id, options));
+            const track = (nodeId) => {
+                context.trackNode(nodeId);
+                for (const child of scene.getNodeChildren(nodeId))
+                    track(child.id);
+            };
+            track(clone.id);
+            return clone.id;
+        },
         nodeList: () => scene
             .listNodes()
             .filter((node) => node.id !== context.rootId)
@@ -642,11 +657,13 @@ export function createWompSceneApi(context) {
             }
             context.call("setNodeOperation", [id, value], () => scene.setNodeOperation(id, value));
         },
+        /** Blend radius in millimetres before parent scaling, independent of project units. */
         nodeGetBlend: (id) => {
             const node = requireNode(id);
-            return "blend" in node ? fromEngineBlend(node.blend) : 0;
+            return "blend" in node ? node.blend : 0;
         },
-        nodeSetBlend: (id, blend) => update(id, { blend: toEngineBlend(finite(blend, "blend")) }),
+        /** Set blend radius in millimetres before parent scaling; clamps to 0–500. */
+        nodeSetBlend: (id, blend) => update(id, { blend: Math.min(MAX_BLEND_RADIUS_MM, Math.max(0, finite(blend, "Blend radius (mm)"))) }),
         nodeGetRound: (id) => {
             const node = requireNode(id);
             if (node.kind !== "primitive" && node.kind !== "text")
@@ -673,11 +690,11 @@ export function createWompSceneApi(context) {
                 throw new Error("Resolution is only valid for Unions");
             return node.resolution;
         },
-        nodeSetResolution: (id, resolution) => {
-            const node = requireNode(id);
+        nodeSetUnionResolution: (unionId, resolution) => {
+            const node = requireNode(unionId);
             if (node.kind !== "union")
-                throw new Error("Resolution is only valid for Unions");
-            update(id, { resolution: clamp(finite(resolution, "resolution"), 0, 0.65) });
+                throw new Error(`Node ${unionId} (${node.kind}): resolution belongs to an Area/Union, not this node`);
+            update(unionId, { resolution: clamp(finite(resolution, "resolution"), 0.01, 0.65) });
         },
         nodeGetLightType: (id) => LIGHT_TYPES.indexOf(requireLight(id).lightType),
         nodeSetLightType: (id, lightType) => {
@@ -687,7 +704,12 @@ export function createWompSceneApi(context) {
             update(id, { lightType: value });
         },
         nodeGetPower: (id) => requireLight(id).power,
-        nodeSetPower: (id, power) => update(id, { power: clamp(finite(power, "power"), 0, 100) }),
+        nodeSetPower: (id, power) => {
+            requireLight(id);
+            if (!Number.isFinite(power) || power < 0 || power > 100)
+                throw new Error(`Light ${id}: power must be a finite number from 0 through 100`);
+            update(id, { power });
+        },
         nodeGetText: (id) => requireText(id).text,
         nodeSetText: (id, text) => update(id, { text: String(text) }),
         nodeGetFont: (id) => requireText(id).fontFamily,
@@ -768,7 +790,7 @@ export function createWompSceneApi(context) {
             return {
                 axis: axis ?? "custom",
                 planePosition: axis ? position[axis] : 0,
-                goop: fromEngineBlend(plane.value),
+                goop: plane.value,
             };
         },
         nodeSetMirror: (id, slot, axis, planePosition = 0, goop = 0) => {
@@ -790,7 +812,7 @@ export function createWompSceneApi(context) {
             mirrors[index] = {
                 position: scale(toEnginePosition(publicPosition, unitMultiplier), 1 / ancestorScale(id)),
                 rotation,
-                value: toEngineMirrorGoop(finite(goop, "Mirror goop")),
+                value: Math.min(MAX_MIRROR_BLEND_RADIUS_MM, Math.max(0, finite(goop, "Mirror radius (mm)"))),
                 hide: 0,
                 hideMirrorPlane: true,
                 constraint,
@@ -815,12 +837,8 @@ export function createWompSceneApi(context) {
         curvePointSetHandleIn: (curveId, pointIndex, value) => setPointHandle(curveId, pointIndex, "handleIn", value),
         curvePointSetHandleOut: (curveId, pointIndex, value) => setPointHandle(curveId, pointIndex, "handleOut", value),
         curvePointCount: (curveId) => requireCurve(curveId).points.length,
-        curvePointAdd: (curveId, point = {}) => insertCurvePoint(curveId, requireCurve(curveId).points.length, point),
-        curvePointInsert: insertCurvePoint,
+        curvePointAdd: addCurvePoint,
         curvePointRemove: (curveId, pointIndex) => {
-            const points = curvePoints(curveId);
-            if (points.length <= 1)
-                throw new Error("A curve must keep at least one point");
             const index = requirePoint(curveId, pointIndex);
             context.call("deleteCurvePoint", [curveId, index], () => scene.deleteCurvePoint(curveId, index));
             shiftCurvePointMetadata(scene, curveId, index, -1);
@@ -969,6 +987,7 @@ export function createWompSceneApi(context) {
         }),
         aabbRadius: (box) => Math.hypot(box.max.x - box.min.x, box.max.y - box.min.y, box.max.z - box.min.z) / 2,
         lookAt,
+        alignAxis,
     };
     return api;
 }

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@womp/spark-agent",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "spark-agent": "dist/cli.js"
+    "spark-agent": "dist/cli.js",
+    "simple-bench": "dist/simple-bench-cli.js",
+    "agent-run": "dist/agent-run-cli.js"
   },
   "exports": {
     "./browser": {
@@ -92,6 +94,8 @@
     "lint": "yarn typecheck",
     "dev": "yarn build && concurrently --kill-others \"yarn dev:server\" \"yarn dev:web\"",
     "dev:server": "tsx src/cli.ts",
+    "simple-bench": "tsx src/simple-bench-cli.ts",
+    "agent-run": "tsx src/agent-run-cli.ts",
     "dev:demo-account": "yarn build && concurrently --kill-others \"yarn dev:server --profile demo-account\" \"yarn dev:web\"",
     "dev:web": "vite --config web/vite.config.ts",
     "start": "node dist/cli.js",
@@ -106,7 +110,7 @@
     "@ai-sdk/openai": "4.0.63",
     "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
     "@womp/flowir": "0.3.0",
-    "@womp/kakapo-sdk": "0.3.0",
+    "@womp/kakapo-sdk": "0.4.0",
     "ai": "7.0.95",
     "eventsource-parser": "^3.0.6",
     "express": "^5.2.1",

package/dist/capabilities/health.d.ts

@@ -1,9 +0,0 @@
-import type { SparkCapability, SparkInvocationContext } from "../capabilities.js";
-import type { SceneHealth } from "../scene-health.js";
-export type WompHealthApi = {
-    read(objectIds: number[]): Promise<SceneHealth>;
-};
-export interface SceneHealthHost {
-    read(objectIds: number[], context: SparkInvocationContext): Promise<SceneHealth>;
-}
-export declare function createSceneHealthCapability(host: SceneHealthHost): SparkCapability<WompHealthApi>;

package/dist/capabilities/health.js

@@ -1,27 +0,0 @@
-import { z } from "zod";
-import { WOMP_HEALTH_DECLARATIONS } from "../generated/health-declarations.js";
-export function createSceneHealthCapability(host) {
-    return {
-        skills: [
-            {
-                name: "scene-health",
-                version: "1",
-                description: "Required before scene checks or procedural edits: engine limits, empty Areas, fresh geometry feedback, and bounded repairs.",
-                instructions: `Before checking or editing a model, call womp.health.read([]) for current scene health. A health read is a snapshot and does not prove that the latest edit finished evaluating. Inspect scene edit receipts before claiming success.
-For confirmed primitive or depth overflow, repair the same target while preserving design, dimensions, active parameter overrides, and unrelated objects. At most two geometry repairs are allowed per target in one logical run. Unverified feedback must not trigger blind regeneration or a claim that the model passed. Empty Areas may be pending, intentionally empty, mesh-only, or failed. Overflow flags take precedence over possibly stale counts. max_total_depth is a scene hierarchy limit, not measured Boolean depth.`,
-                declarations: WOMP_HEALTH_DECLARATIONS,
-                examples: ["print(await womp.health.read([]));"],
-            },
-        ],
-        createApi: (context) => ({
-            read: (objectIds) => {
-                const parsed = z
-                    .array(z.number().int().positive())
-                    .safeParse(objectIds);
-                if (parsed.success === false)
-                    return Promise.reject(parsed.error);
-                return host.read(parsed.data, context);
-            },
-        }),
-    };
-}

package/dist/context.d.ts

@@ -1,15 +0,0 @@
-import type { ModelMessage } from "ai";
-/** Host input budget, not a claim about a provider's maximum context window. */
-export type SparkContextPolicy = {
-    maxInputTokens: number;
-};
-export declare class SparkContextLimitError extends Error {
-    constructor();
-}
-/** Heuristic, not provider tokenization. Encoded media bytes are not text tokens. */
-export declare function estimateSparkContextTokens(value: unknown): number;
-/**
- * Project model input only. Never mutate persisted messages, remove call/result
- * pairs, summarize user requests, or discard receipts, references, and failures.
- */
-export declare function prepareSparkContext(messages: ModelMessage[], system: string, policy: SparkContextPolicy): ModelMessage[];