@womp/spark-agent 4.1.1 → 4.2.0

package/dist/geometry.js

@@ -7,12 +7,12 @@ export { migrateParameterOverrides, readParameterOverrides, } from "./geometry/p
 let reference;
 export function geometryReference() {
     reference ??= {
-        rules: `Write one statement per line:
-param Float width = 20.0 min=1 max=100 step=1
-node box Primitive Type=Cube Position=Vec3(0.0,0.0,0.0) Rotation=Vec3(0.0,0.0,0.0) Size=width Roundness=0.0
-out Geometry=box.Geometry
-Use decimal components in Vec3 parameter/constant literals, e.g. Vec3(20.0,20.0,20.0). Output name is case-sensitive: Geometry.
-Exactly one cast applies per port and casts do not chain: Float[] -> Vec3 is unavailable even though Float[] -> Float and Float -> Vec3 are both listed. Build the vector with CombineXYZ instead.
+        rules: `Write one statement per line:
+param Float width = 20.0 min=1 max=100 step=1
+node box Primitive Type=Cube Position=Vec3(0.0,0.0,0.0) Rotation=Vec3(0.0,0.0,0.0) Size=width Roundness=0.0
+out Geometry=box.Geometry
+Use decimal components in Vec3 parameter/constant literals, e.g. Vec3(20.0,20.0,20.0). Output name is case-sensitive: Geometry.
+Exactly one cast applies per port and casts do not chain: Float[] -> Vec3 is unavailable even though Float[] -> Float and Float -> Vec3 are both listed. Build the vector with CombineXYZ instead.
 ${flowir.renderDslRulesBlock()}`,
         catalog: flowir.renderSchemaBlock(flowirRegistry.getSchema()),
     };

package/dist/prompt.js

@@ -1,55 +1,55 @@
-export const SPARK_AGENT_PROMPT = `You are Spark, Womp's unified assistant.
-Use read_skill to discover the APIs needed for the user's request. Skills provide TypeScript
-declarations for documentation; execute_javascript runs JavaScript, with top-level await.
-Only the listed capabilities are available. Reading a skill does not grant additional permissions.
-Use only the supplied womp APIs and output helpers to access application services and state.
-If a capability is unavailable, explain what is missing and ask the user to enable it when applicable.
-Do not work around missing capabilities by inspecting page globals, DOM or framework internals,
-or making direct network requests. Native execution is not a security sandbox; it does not expand
-the supported API or the user's granted capabilities.
-Give each execute_javascript call a concise present-progressive purpose, such as "Generating a car image", "Inspecting the scene", or "Importing the model". Write purpose before code.
-Each execution has fresh local variables. Keep stable object, job, and artifact references.
-Use print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact
-reference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.
-Completed generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.
-Do not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.
-Inspect the scene before editing and verify the committed result.
-Preserve existing content unless the user asks to replace or delete it. Use the latest target revision
-when a write requires one. Capabilities own transactions: an entire script is not atomic.
-If an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.
-Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
-Complete related work in this conversation without delegating to another agent. Report limits,
-unsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation
-of the result in the user's language; keep implementation details out of that explanation.
-
-Creation intent
-
-Choose the workflow from the user's intended result and the conversation.
-Describe choices by their outcome, not internal tools.
-
-- Use editable CAD for printable, measured, mechanical, or real-world-fit
-  objects. Ask about missing dimensions only when a sensible default would
-  likely make the result wrong. CAD is the preferred printing workflow;
-  do not claim print readiness without supporting validation.
-
-- Build directly in the scene for ordinary 3D requests, including “3D X”
-  and “make X in 3D,” and when the user wants individually editable shapes
-  or geometry that blends with existing objects. Printable, measured,
-  or mechanical intent takes precedence and routes to CAD.
-
-- Use mesh generation when the user explicitly requests a mesh, asks to
-  turn an existing image into 3D, or chooses a sculpted result rather than
-  individually editable shapes.
-
-- Use image generation for pictures, logos, concept art, wallpapers,
-  and other clearly visual output.
-
-- For an ambiguous creative request without explicit 3D or printing intent,
-  generate one image preview first. Then offer one short, outcome-based
-  choice: refine the image, turn it into a sculpted 3D piece, or build it
-  from individually editable shapes. Offer adjustable CAD instead of
-  editable shapes when the subject is measured or must fit something real.
-
+export const SPARK_AGENT_PROMPT = `You are Spark, Womp's unified assistant.
+Use read_skill to discover the APIs needed for the user's request. Skills provide TypeScript
+declarations for documentation; execute_javascript runs JavaScript, with top-level await.
+Only the listed capabilities are available. Reading a skill does not grant additional permissions.
+Use only the supplied womp APIs and output helpers to access application services and state.
+If a capability is unavailable, explain what is missing and ask the user to enable it when applicable.
+Do not work around missing capabilities by inspecting page globals, DOM or framework internals,
+or making direct network requests. Native execution is not a security sandbox; it does not expand
+the supported API or the user's granted capabilities.
+Give each execute_javascript call a concise present-progressive purpose, such as "Generating a car image", "Inspecting the scene", or "Importing the model". Write purpose before code.
+Each execution has fresh local variables. Keep stable object, job, and artifact references.
+Use print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact
+reference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.
+Completed generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.
+Do not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.
+Inspect the scene before editing and verify the committed result.
+Preserve existing content unless the user asks to replace or delete it. Use the latest target revision
+when a write requires one. Capabilities own transactions: an entire script is not atomic.
+If an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.
+Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
+Complete related work in this conversation without delegating to another agent. Report limits,
+unsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation
+of the result in the user's language; keep implementation details out of that explanation.
+
+Creation intent
+
+Choose the workflow from the user's intended result and the conversation.
+Describe choices by their outcome, not internal tools.
+
+- Use editable CAD for printable, measured, mechanical, or real-world-fit
+  objects. Ask about missing dimensions only when a sensible default would
+  likely make the result wrong. CAD is the preferred printing workflow;
+  do not claim print readiness without supporting validation.
+
+- Build directly in the scene for ordinary 3D requests, including “3D X”
+  and “make X in 3D,” and when the user wants individually editable shapes
+  or geometry that blends with existing objects. Printable, measured,
+  or mechanical intent takes precedence and routes to CAD.
+
+- Use mesh generation when the user explicitly requests a mesh, asks to
+  turn an existing image into 3D, or chooses a sculpted result rather than
+  individually editable shapes.
+
+- Use image generation for pictures, logos, concept art, wallpapers,
+  and other clearly visual output.
+
+- For an ambiguous creative request without explicit 3D or printing intent,
+  generate one image preview first. Then offer one short, outcome-based
+  choice: refine the image, turn it into a sculpted 3D piece, or build it
+  from individually editable shapes. Offer adjustable CAD instead of
+  editable shapes when the subject is measured or must fit something real.
+
 - Choose construction methods by the user's requested workflow and the
   available capabilities, not by assuming editable shapes require lower
   fidelity. A sculpted appearance does not by itself require mesh generation.
@@ -57,22 +57,22 @@ Describe choices by their outcome, not internal tools.
   and detail with that method. Offer alternatives only for a specific
   demonstrated limitation; ask before switching or simplifying the requested
   result. No method guarantees exact reconstruction from a single image.
-
-- When the user chooses editable shapes or CAD after a preview, preserve
-  its palette, proportions, and defining features. When they choose a
-  sculpted result, use that preview as the image-to-mesh input rather
-  than starting again from a text prompt.
-
-- If the user wants repeated generation variations and Flow is available,
-  offer a reusable Flow workflow.
-
-- Ask at most one focused question at a time, only when a sensible default
-  would likely produce the wrong outcome. Do not repeat resolved questions.
-  Interpret replies using the preceding offer; if several options were
-  offered and “yes” does not identify one, clarify briefly.
-
-- Treat a clear answer to your question as an instruction to proceed.
-  Continue from existing results rather than restarting the workflow.
-
-Offer only workflows available in this host. Follow their authorization
+
+- When the user chooses editable shapes or CAD after a preview, preserve
+  its palette, proportions, and defining features. When they choose a
+  sculpted result, use that preview as the image-to-mesh input rather
+  than starting again from a text prompt.
+
+- If the user wants repeated generation variations and Flow is available,
+  offer a reusable Flow workflow.
+
+- Ask at most one focused question at a time, only when a sensible default
+  would likely produce the wrong outcome. Do not repeat resolved questions.
+  Interpret replies using the preceding offer; if several options were
+  offered and “yes” does not identify one, clarify briefly.
+
+- Treat a clear answer to your question as an instruction to proceed.
+  Continue from existing results rather than restarting the workflow.
+
+Offer only workflows available in this host. Follow their authorization
 and confirmation requirements before generation or scene changes.`;

package/dist/scene-environment.d.ts

@@ -17,7 +17,7 @@ export declare function createSceneEnvironment(scene: SceneEdit, hdrs: readonly
     setHdrName: (name: string) => void;
     setHdrMultiplier: (multiplier: number) => void;
     setHdrOrientation: (orientation: Vec2) => void;
-    setBackgroundColor: (color: {
+    setBackgroundColor: (rgb255: {
         r: number;
         g: number;
         b: number;

package/dist/scene-environment.js

@@ -1,4 +1,5 @@
 import { metadataObject } from "./scene-metadata.js";
+import { assertColor255 } from "./color.js";
 function finite(value, label) {
     if (!Number.isFinite(value))
         throw new Error(`${label} must be a finite number`);
@@ -65,10 +66,13 @@ export function createSceneEnvironment(scene, hdrs, print) {
             write({ hdr_orientation: { x, y } });
             print(`Set HDR orientation to: (${x}, ${y})`);
         },
-        setBackgroundColor: (color) => {
-            const r = finite(color?.r, "Background red");
-            const g = finite(color?.g, "Background green");
-            const b = finite(color?.b, "Background blue");
+        setBackgroundColor: (rgb255) => {
+            const r = finite(rgb255?.r, "Background red");
+            const g = finite(rgb255?.g, "Background green");
+            const b = finite(rgb255?.b, "Background blue");
+            // The same 0-255 domain as every other color here, so the same refusal
+            // rather than a silent near-black (./color.ts).
+            assertColor255([r, g, b], "Background color");
             write({ backdrop_color1: { x: r / 255, y: g / 255, z: b / 255 } });
             print(`Set background color to: (${r}, ${g}, ${b})`);
         },

package/dist/scene-health.d.ts

@@ -40,6 +40,29 @@ export type SceneHealth = {
     reason?: string;
 };
 export declare function unverifiedSceneHealth(affectedAreaIds: string[], reason: string): SceneHealth;
+export declare const MAX_RECEIPT_THERMOMETER_OBJECTS = 8;
+/**
+ * The same health reading, with the thermometer's per-Area table bounded for a
+ * receipt.
+ *
+ * WHY. Every scene, geometry and OpenSCAD receipt embeds the whole thermometer,
+ * one entry per Area, and a receipt is both rendered in the panel and read by
+ * the model. A 20-Area scene therefore repeats a table the model did not ask
+ * about on every edit. The totals, the limits and the overflow flags are what a
+ * decision is made on, so they are kept whole: what is bounded is the number of
+ * per-Area rows, affected and overflowing Areas first, with the omission stated
+ * in `reason` rather than left silent. Health used for a repair decision --
+ * `hasGeometryOverflow`, `hasSceneResourcePressure`, the host's `onHealth` --
+ * reads the untrimmed value, so no decision changes.
+ */
+export declare function receiptSceneHealth(health: SceneHealth, limit?: number): SceneHealth;
+/**
+ * Receipt details with an embedded scene health reading bounded by
+ * `receiptSceneHealth`. Anything else, including details with no health, is
+ * returned untouched: a receipt is read back by hosts for recovery, so this
+ * changes the one payload that is unbounded by construction and nothing else.
+ */
+export declare function boundedReceiptDetails(details: Record<string, unknown>): Record<string, unknown>;
 export declare function getSdkSceneAreaId(api: KakapoAPI, objectId: number): string;
 export declare function getSdkSceneAreaIds(api: KakapoAPI): string[];
 export declare function hasGeometryOverflow(health: SceneHealth): boolean;

package/dist/scene-health.js

@@ -34,6 +34,77 @@ export function unverifiedSceneHealth(affectedAreaIds, reason) {
         reason,
     };
 }
+export const MAX_RECEIPT_THERMOMETER_OBJECTS = 8;
+/**
+ * The same health reading, with the thermometer's per-Area table bounded for a
+ * receipt.
+ *
+ * WHY. Every scene, geometry and OpenSCAD receipt embeds the whole thermometer,
+ * one entry per Area, and a receipt is both rendered in the panel and read by
+ * the model. A 20-Area scene therefore repeats a table the model did not ask
+ * about on every edit. The totals, the limits and the overflow flags are what a
+ * decision is made on, so they are kept whole: what is bounded is the number of
+ * per-Area rows, affected and overflowing Areas first, with the omission stated
+ * in `reason` rather than left silent. Health used for a repair decision --
+ * `hasGeometryOverflow`, `hasSceneResourcePressure`, the host's `onHealth` --
+ * reads the untrimmed value, so no decision changes.
+ */
+export function receiptSceneHealth(health, limit = MAX_RECEIPT_THERMOMETER_OBJECTS) {
+    const thermometer = health.thermometer;
+    if (thermometer === undefined)
+        return health;
+    const ids = Object.keys(thermometer.objects);
+    if (ids.length <= limit)
+        return health;
+    const overflowing = (id) => {
+        const object = thermometer.objects[id];
+        return (object !== undefined &&
+            (object.flag_prim_overflow > 0 ||
+                object.flag_depth_overflow > 0 ||
+                object.flag_vox_overflow > 0 ||
+                object.num_prims >= thermometer.max_num_prims ||
+                object.voxels >= thermometer.max_per_object));
+    };
+    const ordered = [
+        ...health.affectedAreaIds.filter((id) => thermometer.objects[id] !== undefined),
+        ...ids.filter((id) => !health.affectedAreaIds.includes(id) && overflowing(id)),
+        ...ids.filter((id) => !health.affectedAreaIds.includes(id) && !overflowing(id)),
+    ];
+    const kept = ordered.slice(0, limit);
+    const objects = {};
+    for (const id of kept)
+        objects[id] = thermometer.objects[id];
+    const note = `Thermometer rows bounded for this receipt: ${kept.length} of ${ids.length} Areas shown, affected and overflowing first; ${ids.length - kept.length} omitted. Totals, limits and overflow flags are complete. Use scene.health(objectIds) for a specific Area.`;
+    return {
+        ...health,
+        thermometer: { ...thermometer, objects },
+        reason: health.reason === undefined ? note : `${health.reason} ${note}`,
+    };
+}
+/**
+ * Receipt details with an embedded scene health reading bounded by
+ * `receiptSceneHealth`. Anything else, including details with no health, is
+ * returned untouched: a receipt is read back by hosts for recovery, so this
+ * changes the one payload that is unbounded by construction and nothing else.
+ */
+export function boundedReceiptDetails(details) {
+    const health = details.sceneHealth;
+    if (typeof health !== "object" || health === null || Array.isArray(health))
+        return details;
+    const candidate = health;
+    if (Array.isArray(candidate.affectedAreaIds) === false)
+        return details;
+    const parsed = thermometerSchema.safeParse(candidate.thermometer);
+    if (parsed.success === false)
+        return details;
+    return {
+        ...details,
+        sceneHealth: receiptSceneHealth({
+            ...candidate,
+            thermometer: parsed.data,
+        }),
+    };
+}
 export function getSdkSceneAreaId(api, objectId) {
     let node = api.getNode(objectId);
     let areaId = node.kind === "union" ? node.id : objectId;

package/dist/sdk-geometry-host.js

@@ -1,5 +1,6 @@
 import { compileGeometry, migrateGraphExt, readEditableGeometry, } from "./geometry/compiler.js";
 import { graphExtSchema } from "./geometry/graph.js";
+import { boundedDiagnostics } from "./geometry/diagnostics.js";
 import { migrateParameterOverrides, readParameterOverrides, } from "./geometry/parameters.js";
 import { getSdkSceneAreaId, readStableSdkSceneHealth } from "./scene-health.js";
 import { createGeometryRepairTracker, } from "./repair-state.js";
@@ -78,7 +79,8 @@ async function readTarget(api, objectId, target = resolveTarget(api, objectId))
     }
     catch (error) {
         result.source = null;
-        result.diagnostics.push(errorMessage(error));
+        // Bounded: a compiler diagnostic is unbounded text (./geometry/diagnostics.ts).
+        result.diagnostics.push(...boundedDiagnostics([errorMessage(error)]));
     }
     return structuredClone(result);
 }
@@ -163,7 +165,7 @@ export function createSdkGeometryHost(options) {
                     instanceId: target.instanceId,
                     affectedObjectIds: [],
                     revision: target.revision,
-                    diagnostics,
+                    diagnostics: boundedDiagnostics(diagnostics),
                 });
                 let compiled;
                 let nextExt;
@@ -295,7 +297,7 @@ export function createSdkGeometryHost(options) {
                     status: "applied",
                     ...applied.value,
                     revision: applied.operation.resultRevision ?? input.expectedRevision,
-                    diagnostics,
+                    diagnostics: boundedDiagnostics(diagnostics),
                 };
             }
             finally {

package/dist/sdk-scene-health-host.js

@@ -1,13 +1,35 @@
 import { getSdkSceneAreaId, getSdkSceneAreaIds, readStableSdkSceneHealth, } from "./scene-health.js";
+/**
+ * The Area that owns `objectId`, or undefined when the node is in no Area --
+ * the scene root 0, a root-level Group, a Light. The engine's thermometer has a
+ * row per Area only, so such an id has no row of its own and asking for one
+ * would report the whole scene as unverified.
+ */
+function owningAreaId(api, objectId) {
+    const areaId = getSdkSceneAreaId(api, objectId);
+    return api.getNode(Number(areaId)).kind === "union" ? areaId : undefined;
+}
 export function createSdkSceneHealthHost(editor, onHealth) {
     return {
         read: (objectIds, context) => editor.read(context, async (api) => {
-            const areaIds = objectIds.length > 0
-                ? objectIds.map((id) => getSdkSceneAreaId(api, id))
-                : getSdkSceneAreaIds(api);
+            const owned = objectIds
+                .map((id) => ({ id, areaId: owningAreaId(api, id) }))
+                .filter((entry) => entry.areaId !== undefined);
+            // `scene.read()` publishes node 0, and ids outside any Area are legal
+            // arguments. They narrow nothing, so they are reported rather than
+            // allowed to make the whole reading unverified; with nothing left to
+            // narrow by, this is the whole-scene read `health()` already means.
+            const outside = objectIds.filter((id) => owned.some((entry) => entry.id === id) === false);
+            const areaIds = owned.length > 0 ? owned.map((entry) => entry.areaId) : getSdkSceneAreaIds(api);
             const health = await readStableSdkSceneHealth(api, [...new Set(areaIds)], context.signal);
-            onHealth?.(health);
-            return health;
+            const note = outside.length === 0
+                ? undefined
+                : `${outside.join(", ")} ${outside.length === 1 ? "is" : "are"} in no Area, and the engine reports health per Area, so ${owned.length > 0 ? "health is reported for the remaining ids" : "this is the whole scene's health"}.`;
+            const reported = note === undefined
+                ? health
+                : { ...health, reason: health.reason === undefined ? note : `${health.reason} ${note}` };
+            onHealth?.(reported);
+            return reported;
         }),
     };
 }

package/dist/sdk-scene-host.d.ts

@@ -115,7 +115,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         g: number;
         b: number;
     };
-    nodeSetColor: (id: number, color: {
+    nodeSetColor: (id: number, rgb255: {
         r: number;
         g: number;
         b: number;
@@ -206,7 +206,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         g: number;
         b: number;
     };
-    materialSetColor: (id: number, color: {
+    materialSetColor: (id: number, rgb255: {
         r: number;
         g: number;
         b: number;
@@ -216,7 +216,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         g: number;
         b: number;
     };
-    materialSetSecondaryColor: (id: number, color: {
+    materialSetSecondaryColor: (id: number, rgb255: {
         r: number;
         g: number;
         b: number;
@@ -226,7 +226,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         g: number;
         b: number;
     };
-    materialSetSubsurfaceColor: (id: number, color: {
+    materialSetSubsurfaceColor: (id: number, rgb255: {
         r: number;
         g: number;
         b: number;
@@ -294,7 +294,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
     setHdrName: (name: string) => void;
     setHdrMultiplier: (multiplier: number) => void;
     setHdrOrientation: (orientation: import("@womp/kakapo-sdk").Vec2) => void;
-    setBackgroundColor: (color: {
+    setBackgroundColor: (rgb255: {
         r: number;
         g: number;
         b: number;

package/dist/sdk-scene-host.js

@@ -2,6 +2,7 @@ import { createWompSceneApi, sceneNodeType } from "./womp-scene-api.js";
 import { sceneUnitMultiplier } from "./coordinates.js";
 import { executeSceneOperation, } from "./scene-operations.js";
 import { readMaterialMetadata, writeMaterialMetadata, } from "./scene-metadata.js";
+import { boundedReceiptDetails } from "./scene-health.js";
 export function createSdkSceneDraft(api, scene, services) {
     let defaultMaterialId = scene
         .listMaterials()
@@ -100,13 +101,17 @@ export function createSdkSceneEditor(options) {
                             : operation.status === "rolled_back"
                                 ? "rolled_back"
                                 : "unknown",
-                        details: {
+                        // An embedded scene health reading is bounded here, where every
+                        // receipt is recorded -- the package's geometry and OpenSCAD
+                        // hosts and a host's own `onCommitted` all put one in details
+                        // (./scene-health.ts `boundedReceiptDetails`).
+                        details: boundedReceiptDetails({
                             ...hostDetails,
                             result: operation.result,
                             save: operation.save,
                             error: operation.error,
                             synchronized,
-                        },
+                        }),
                     });
                 };
                 try {

package/dist/server/fixtures/materials/matte-blue.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Matte Blue",
-  "resource": {
-    "data": {
-      "color.x": 0.08,
-      "color.y": 0.3,
-      "color.z": 0.8,
-      "roughness": 0.85,
-      "metalness": 0,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Matte Blue",
+  "resource": {
+    "data": {
+      "color.x": 0.08,
+      "color.y": 0.3,
+      "color.z": 0.8,
+      "roughness": 0.85,
+      "metalness": 0,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}

package/dist/server/fixtures/materials/polished-copper.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Polished Copper",
-  "resource": {
-    "data": {
-      "color.x": 0.955,
-      "color.y": 0.638,
-      "color.z": 0.538,
-      "roughness": 0.18,
-      "metalness": 1,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Polished Copper",
+  "resource": {
+    "data": {
+      "color.x": 0.955,
+      "color.y": 0.638,
+      "color.z": 0.538,
+      "roughness": 0.18,
+      "metalness": 1,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}

package/dist/server/service.js

@@ -1,3 +1,4 @@
+import { sparkErrorDiagnostics } from "../error-diagnostics.js";
 import { readUIMessageStream, validateUIMessages } from "ai";
 import { sparkDataPartSchemas, sparkMessageMetadataSchema, } from "../ui.js";
 const TERMINAL_STATUSES = new Set([
@@ -102,7 +103,7 @@ export class SparkAgentService {
     }
     async deleteConversation(ownerId, id) {
         await this.getConversation(ownerId, id);
-        if (await this.store.deleteConversation(id) === false) {
+        if ((await this.store.deleteConversation(id)) === false) {
             throw new SparkServiceError(409, "Stop the active run before deleting this conversation.");
         }
     }
@@ -209,7 +210,9 @@ export class SparkAgentService {
         this.controllers.set(run.id, controller);
         const execution = this.runInBackground(run, conversation, controller);
         this.executions.set(run.id, execution);
-        void execution.finally(() => this.executions.delete(run.id)).catch((error) => {
+        void execution
+            .finally(() => this.executions.delete(run.id))
+            .catch((error) => {
             console.error("Spark run persistence failed", error);
         });
         return run;
@@ -314,7 +317,7 @@ export class SparkAgentService {
                         continue;
                     await this.appendChunk(run, chunk);
                 }
-            })();
+            })().then(() => undefined, (error) => error);
             let executionError;
             let result;
             try {
@@ -323,9 +326,11 @@ export class SparkAgentService {
             catch (error) {
                 executionError = error;
             }
-            await consume;
+            const streamError = await consume;
             if (executionError !== undefined)
                 throw executionError;
+            if (streamError !== undefined)
+                throw streamError;
             if (controller.signal.aborted) {
                 await this.appendStatus(run, "cancelled");
                 await this.finishRun(run, conversation, "cancelled");
@@ -341,25 +346,26 @@ export class SparkAgentService {
                 await this.finishRun(run, conversation, "cancelled");
                 return;
             }
-            const message = error instanceof Error ? error.message : String(error);
+            const diagnostics = sparkErrorDiagnostics(error);
+            const message = diagnostics.message;
             const failedChunk = {
                 type: "data-run-status",
                 id: `run-status-${run.id}`,
-                data: { runId: run.id, status: "failed", error: message },
+                data: { runId: run.id, status: "failed", error: message, errorDiagnostics: diagnostics },
             };
             await this.appendChunk(run, { type: "error", errorText: message });
             await this.appendChunk(run, failedChunk);
-            await this.finishRun(run, conversation, "failed", message);
+            await this.finishRun(run, conversation, "failed", message, diagnostics);
         }
         finally {
             this.controllers.delete(run.id);
         }
     }
-    async finishRun(run, conversation, status, error) {
+    async finishRun(run, conversation, status, error, errorDiagnostics) {
         const completedAt = now();
         const storedChunks = await this.store.listRunChunks(run.id, 0);
         const chunks = storedChunks.map(({ chunk }) => chunk);
-        const assistant = await this.materializeMessage(run, chunks, status, completedAt, error);
+        const assistant = await this.materializeMessage(run, chunks, status, completedAt, error, errorDiagnostics);
         if (assistant !== undefined) {
             await this.appendChunk(run, {
                 type: "message-metadata",
@@ -379,12 +385,13 @@ export class SparkAgentService {
             ...run,
             status,
             ...(error === undefined ? {} : { error }),
+            ...(errorDiagnostics === undefined ? {} : { errorDiagnostics }),
             updatedAt: completedAt,
             completedAt,
         });
         this.wakeRun(run.id);
     }
-    async materializeMessage(run, chunks, status, completedAt, error) {
+    async materializeMessage(run, chunks, status, completedAt, error, errorDiagnostics) {
         let message;
         try {
             for await (const current of readUIMessageStream({
@@ -412,6 +419,7 @@ export class SparkAgentService {
                 modelId: run.settings.modelId,
                 ...(message.metadata?.usage === undefined ? {} : { usage: message.metadata.usage }),
                 ...(error === undefined ? {} : { error }),
+                ...(errorDiagnostics === undefined ? {} : { errorDiagnostics }),
             },
         };
     }
@@ -423,6 +431,23 @@ export class SparkAgentService {
         });
     }
     async appendChunk(run, chunk) {
+        if (chunk.type === "error")
+            chunk = { ...chunk, errorText: sparkErrorDiagnostics(chunk.errorText).message };
+        if (chunk.type === "message-metadata" || chunk.type === "data-run-status") {
+            const data = chunk.type === "message-metadata" ? chunk.messageMetadata : chunk.data;
+            const safe = {
+                ...(data.error === undefined ? {} : { error: sparkErrorDiagnostics(data.error).message }),
+                ...(data.errorDiagnostics === undefined
+                    ? {}
+                    : {
+                        errorDiagnostics: sparkErrorDiagnostics(data.errorDiagnostics),
+                    }),
+            };
+            chunk =
+                chunk.type === "message-metadata"
+                    ? { ...chunk, messageMetadata: { ...chunk.messageMetadata, ...safe } }
+                    : { ...chunk, data: { ...chunk.data, ...safe } };
+        }
         const stored = await this.store.appendRunChunk(run.id, run.conversationId, chunk);
         for (const listener of this.listeners.get(run.id) ?? [])
             listener(stored);