@womp/spark-agent 4.1.0 → 4.1.2

package/dist/agent.js

@@ -1,9 +1,10 @@
+import { sparkErrorDiagnostics } from "./error-diagnostics.js";
 import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 import { createSparkTools } from "./agent-tools.js";
 import { SPARK_AGENT_PROMPT } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
 function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+    return sparkErrorDiagnostics(error).message;
 }
 export function runSparkAgent(options) {
     const maxSteps = options.maxSteps ?? 100;
@@ -187,7 +188,15 @@ export function runSparkAgent(options) {
                 const status = options.signal?.aborted ? "cancelled" : "failed";
                 writer.write({
                     type: "message-metadata",
-                    messageMetadata: { ...metadata(status), error: errorMessage(failure) },
+                    messageMetadata: {
+                        ...metadata(status),
+                        error: errorMessage(failure),
+                        ...(status === "cancelled"
+                            ? {}
+                            : {
+                                errorDiagnostics: sparkErrorDiagnostics(failure),
+                            }),
+                    },
                 });
                 rejectResult(failure);
                 throw failure;

package/dist/capabilities/scene.js

@@ -16,14 +16,15 @@ export function createSceneCapability(host) {
         skills: [
             {
                 name: "scene-editing",
-                version: "25",
+                version: "29",
                 description: "Inspect the open scene and edit its objects, materials, curves, and environment.",
                 instructions: `Read the scene first and keep its revision and object IDs. read() includes health.
 Use womp.scene.health() to refresh whole-scene health or womp.scene.health(objectIds) to check specific objects (mapped to their owning Areas).
 Health is a separate snapshot, not proof of consistency with read().revision or that the latest edit finished evaluating. Inspect post-edit health in receipts before claiming success; refresh only when needed.
 Unavailable, stale, or unverified feedback must not trigger blind regeneration or a claim that the model passed. Hosts without health services return unverified health with a reason.
 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.
-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.
+Empty Areas may be pending, intentionally empty, mesh-only, or failed. Overflow flags take precedence over possibly stale counts.
+max_total_depth reports the engine's tier-dependent nesting allowance, not measured depth. Compiled Boolean depth includes generated grouping; organizational Groups do not add a level. Use flag_depth_overflow to detect evaluator rejection.
 Call scene.edit(callback, expectedRevision)
 for one coherent undoable change. The callback receives a draft; all node/material/curve functions and enums
 are properties of that draft. The draft expires when the callback ends. Await asynchronous methods.
@@ -32,6 +33,7 @@ Preserve the existing scene unless asked to remove or replace content. Use seman
 known IDs when editing rather than creating duplicates. Distances follow the current project's units
 (read().unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
 Convert a dimension in millimetres to project units by multiplying it by read().unitMultiplier.
+The SDK-backed draft clamps dimension writes to 0.01–1000 mm per component before converting to native units; this is an adapter limit, not a scene-wide size limit. Read back dimensions when physical size matters.
 Area size is a dimensionless scale; Group size stays fixed at one. Lights must be created at root (parentId 0); their size has x/y dimensions.
 Light power must be a finite number in [0, 100].
 nodeCreate(Curve, parentId) creates an empty curve with zero blend. curvePointAdd(curveId, point, index?) returns the new index; omit index to append or supply an integer from 0 through point count to insert before that position.
@@ -62,9 +64,12 @@ Groups are organizational only; move and rotate their child Areas individually,
 Sphere uses size.x as uniform diameter (y/z do not stretch it), including new or resized spherical curve points. Cylinder/Cone/Pyramid use x as base diameter/width and y as height;
 Torus uses x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
 Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
-For reference images, match the camera before adjusting geometry. Compare renders with the source from a consistent view,
-correcting the largest silhouette, proportion, and pose differences before adding details. Return to that view after close-ups
-or depth checks; do not distort geometry to compensate for a camera mismatch.
+Reference fidelity:
+When recreating an image, treat its visible geometry and level of detail as the target—not merely its subject, colors, or list of parts. Preserve the user's chosen workflow and editability requirements.
+Establish a comparison view matching the reference's angle, projection, and subject framing as closely as practical. Match silhouette, proportions, pose, and negative spaces first; then local contours, thickness, curvature, surface transitions, and defining details. Infer unseen geometry conservatively.
+Compare each rendered pass directly with the source. Identify the largest remaining visible shape mismatch, edit it, and verify that it improved before moving to smaller details. Use close-ups when the comparison view cannot resolve a feature; return to the comparison view afterward. Adjust sampling or resolution when visible faceting or segmentation requires it—not as a substitute for reshaping.
+Do not stop at semantic resemblance or after a fixed number of screenshots. Continue while substantial visible mismatches remain and supported edits are making progress, within the available budget. If progress stalls or the chosen representation cannot achieve the requested fidelity, explain the specific limitation and ask before changing workflows. Before finishing, compare the latest render with the reference and address the largest remaining visible mismatch; if substantial differences remain, identify the concrete stopping reason rather than treating an approximation disclaimer as completion.
+
 nodeClone is shallow (no children). await cloneSubtree(id, { parentId?, name?, index? }) copies the complete hierarchy with fresh IDs,
 preserving local transforms, order and metadata, remapping internal references and sharing external materials/assets.
 Cloning requires a host transport with atomic scene patches; an unsupported host rejects it without changing the draft.
@@ -79,8 +84,10 @@ screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspect
 sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
 For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
 Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
-Omitted projection/lens settings are preserved. The camera changes immediately and remains active; there is no auto-fit.
-screenshot() keeps the active camera. Do not change a locked camera without the user's instruction. Verify silhouette,
+Omitted projection/lens settings come from the active camera. Pass the camera again for repeatable captures.
+For object-focused screenshots, identify the requested object and frame it with an explicit camera position and target using its bounds; reuse established framing when appropriate. Choose a view that reveals the requested features without clipping the subject.
+Omitting camera captures the active viewport without auto-fit. Use it when the user asks about the current viewport or clearly refers to what is visible on screen, not on the assumption that it shows the requested object.
+Respect the host's camera-lock restrictions. Verify silhouette,
 connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
 OpenSCAD part bounds are local to the part; individual primitive and curve bounds are unsupported. Renderer bounds and resize calls
 must finish before subsequent writes. Inside scene.edit, complete renderer-backed bounds reads before the first

package/dist/error-diagnostics.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/** Allowlisted diagnostics only; never serialize an SDK error or request wholesale. */
+export type SparkErrorDiagnostics = {
+    message: string;
+    name?: string;
+    code?: string;
+    status?: number;
+    requestId?: string;
+    cause?: SparkErrorDiagnostics;
+};
+export declare const sparkErrorDiagnosticsSchema: z.ZodObject<{
+    cause: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        requestId: z.ZodOptional<z.ZodString>;
+        cause: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    message: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function sparkErrorDiagnostics(error: unknown): SparkErrorDiagnostics;

package/dist/error-diagnostics.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+const fields = {
+    message: z.string().max(1024),
+    name: z.string().max(128).optional(),
+    code: z.string().max(128).optional(),
+    status: z.number().int().min(100).max(599).optional(),
+    requestId: z.string().max(128).optional(),
+};
+const causeSchema = z.object(fields);
+export const sparkErrorDiagnosticsSchema = z.object({
+    ...fields,
+    cause: causeSchema.extend({ cause: causeSchema.optional() }).optional(),
+});
+function record(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function responseData(value) {
+    if (typeof value !== "string" || value.length > 16384)
+        return {};
+    try {
+        return record(JSON.parse(value));
+    }
+    catch {
+        return {};
+    }
+}
+function text(value, limit = 1024) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    // Bound work as well as storage. Embedded JSON/request dumps are not diagnostics.
+    return String(value)
+        .slice(0, 8192)
+        .replace(/\{[\s\S]*|\[(?=\s*["{0-9])[\s\S]*/u, "[payload omitted]")
+        .replace(/\b(?:request(?:\s*body)?|response\s*body|payload|headers|image|prompt)\s*[:=][\s\S]*/giu, "[payload omitted]")
+        .replace(/data:[^\s]+/giu, "[data omitted]")
+        .replace(/https?:\/\/[^\s]+/giu, "[url omitted]")
+        .replace(/\b(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key|api[_ -]?key|access[_ -]?token|refresh[_ -]?token|token|password|(?:client[_ -]?)?secret)\b\s*[:=]\s*[^\r\n,;]+/giu, "[credential omitted]")
+        .replace(/\b(?:Bearer|Basic)\s+[^\s,;]+/giu, "[credential omitted]")
+        .replace(/\b(?:sk-|sk_|AIza)[A-Za-z0-9_-]+/gu, "[credential omitted]")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/gu, "[credential omitted]")
+        .replace(/[A-Za-z0-9+/=_-]{200,}/gu, "[data omitted]")
+        .slice(0, limit);
+}
+export function sparkErrorDiagnostics(error) {
+    const seen = new Set();
+    const visit = (value, depth) => {
+        seen.add(value);
+        const source = record(value);
+        const data = record(source.data);
+        const body = responseData(source.responseBody);
+        const provider = record(data.error ?? source.error ?? body.error ?? body);
+        const headers = record(source.responseHeaders);
+        const status = source.statusCode ?? source.status ?? provider.status;
+        const result = {
+            message: text(source.message ?? provider.message ?? value) || "An error occurred.",
+        };
+        const name = text(source.name, 128);
+        const code = text(source.code ?? provider.code ?? data.code, 128);
+        const requestId = text(source.requestId ??
+            source.request_id ??
+            provider.request_id ??
+            body.request_id ??
+            headers["x-request-id"] ??
+            headers["request-id"] ??
+            headers["x-amzn-requestid"], 128);
+        if (name)
+            result.name = name;
+        if (code)
+            result.code = code;
+        if (typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599)
+            result.status = status;
+        if (requestId)
+            result.requestId = requestId;
+        const cause = source.cause ?? source.lastError;
+        if (depth < 2 && cause !== undefined && !seen.has(cause))
+            result.cause = visit(cause, depth + 1);
+        return result;
+    };
+    return visit(error, 0);
+}

package/dist/prompt.d.ts

@@ -1 +1 @@
-export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill to discover the APIs needed for the user's request. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive 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.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted 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.\nDo 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.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nIf an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.\nNever claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nChoose the workflow from the user's intended result and the conversation.\nDescribe choices by their outcome, not internal tools.\n\n- Use editable CAD for printable, measured, mechanical, or real-world-fit\n  objects. Ask about missing dimensions only when a sensible default would\n  likely make the result wrong. CAD is the preferred printing workflow;\n  do not claim print readiness without supporting validation.\n\n- Build directly in the scene for ordinary 3D requests, including \u201C3D X\u201D\n  and \u201Cmake X in 3D,\u201D and when the user wants individually editable shapes\n  or geometry that blends with existing objects. Printable, measured,\n  or mechanical intent takes precedence and routes to CAD.\n\n- Use mesh generation when the user explicitly requests a mesh, asks to\n  turn an existing image into 3D, or chooses a sculpted result rather than\n  individually editable shapes.\n\n- Use image generation for pictures, logos, concept art, wallpapers,\n  and other clearly visual output.\n\n- For an ambiguous creative request without explicit 3D or printing intent,\n  generate one image preview first. Then offer one short, outcome-based\n  choice: refine the image, turn it into a sculpted 3D piece, or build it\n  from individually editable shapes. Offer adjustable CAD instead of\n  editable shapes when the subject is measured or must fit something real.\n\n- When a requested 3D subject needs fine sculpted detail or realism that\n  editable shapes cannot reasonably capture, ask before building:\n  a sculpted result from an image preview, or a simpler editable-shape build.\n  Respect an explicit choice already made by the user.\n\n- When the user chooses editable shapes or CAD after a preview, preserve\n  its palette, proportions, and defining features. When they choose a\n  sculpted result, use that preview as the image-to-mesh input rather\n  than starting again from a text prompt.\n\n- If the user wants repeated generation variations and Flow is available,\n  offer a reusable Flow workflow.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes.";
+export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill to discover the APIs needed for the user's request. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive 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.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted 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.\nDo 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.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nIf an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.\nNever claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nChoose the workflow from the user's intended result and the conversation.\nDescribe choices by their outcome, not internal tools.\n\n- Use editable CAD for printable, measured, mechanical, or real-world-fit\n  objects. Ask about missing dimensions only when a sensible default would\n  likely make the result wrong. CAD is the preferred printing workflow;\n  do not claim print readiness without supporting validation.\n\n- Build directly in the scene for ordinary 3D requests, including \u201C3D X\u201D\n  and \u201Cmake X in 3D,\u201D and when the user wants individually editable shapes\n  or geometry that blends with existing objects. Printable, measured,\n  or mechanical intent takes precedence and routes to CAD.\n\n- Use mesh generation when the user explicitly requests a mesh, asks to\n  turn an existing image into 3D, or chooses a sculpted result rather than\n  individually editable shapes.\n\n- Use image generation for pictures, logos, concept art, wallpapers,\n  and other clearly visual output.\n\n- For an ambiguous creative request without explicit 3D or printing intent,\n  generate one image preview first. Then offer one short, outcome-based\n  choice: refine the image, turn it into a sculpted 3D piece, or build it\n  from individually editable shapes. Offer adjustable CAD instead of\n  editable shapes when the subject is measured or must fit something real.\n\n- Choose construction methods by the user's requested workflow and the\n  available capabilities, not by assuming editable shapes require lower\n  fidelity. A sculpted appearance does not by itself require mesh generation.\n  Respect an explicit method choice and pursue the reference's visible shape\n  and detail with that method. Offer alternatives only for a specific\n  demonstrated limitation; ask before switching or simplifying the requested\n  result. No method guarantees exact reconstruction from a single image.\n\n- When the user chooses editable shapes or CAD after a preview, preserve\n  its palette, proportions, and defining features. When they choose a\n  sculpted result, use that preview as the image-to-mesh input rather\n  than starting again from a text prompt.\n\n- If the user wants repeated generation variations and Flow is available,\n  offer a reusable Flow workflow.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes.";

package/dist/prompt.js

@@ -50,10 +50,13 @@ Describe choices by their outcome, not internal tools.
   from individually editable shapes. Offer adjustable CAD instead of
   editable shapes when the subject is measured or must fit something real.
 
-- When a requested 3D subject needs fine sculpted detail or realism that
-  editable shapes cannot reasonably capture, ask before building:
-  a sculpted result from an image preview, or a simpler editable-shape build.
-  Respect an explicit choice already made by the user.
+- 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.
+  Respect an explicit method choice and pursue the reference's visible shape
+  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

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);

package/dist/server/types.d.ts

@@ -1,3 +1,4 @@
+import type { SparkErrorDiagnostics } from "../error-diagnostics.js";
 import type { SparkAgentRun } from "../agent.js";
 import type { ReasoningEffort } from "../models.js";
 import type { SparkRunStatus, SparkUIMessage, StoredSparkChunk } from "../ui.js";
@@ -26,6 +27,7 @@ export type SparkRun = {
     status: SparkRunStatus;
     settings: SparkRunSettings;
     error?: string;
+    errorDiagnostics?: SparkErrorDiagnostics;
     createdAt: string;
     updatedAt: string;
     startedAt?: string;

package/dist/ui.d.ts

@@ -1,3 +1,5 @@
+import { type SparkErrorDiagnostics } from "./error-diagnostics.js";
+export { sparkErrorDiagnostics, sparkErrorDiagnosticsSchema, type SparkErrorDiagnostics, } from "./error-diagnostics.js";
 import type { InferUIMessageChunk, UIMessage } from "ai";
 import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import { z } from "zod";
@@ -24,6 +26,7 @@ export type SparkMessageMetadata = {
     modelId?: string;
     usage?: unknown;
     error?: string;
+    errorDiagnostics?: SparkErrorDiagnostics;
 };
 export type SparkConsoleData = {
     stream: "stdout" | "stderr";
@@ -33,6 +36,7 @@ export type SparkRunStatusData = {
     runId: string;
     status: SparkRunStatus;
     error?: string;
+    errorDiagnostics?: SparkErrorDiagnostics;
     label?: string;
 };
 export declare const sparkStepCostSchema: z.ZodObject<{
@@ -157,6 +161,27 @@ export declare const sparkMessageMetadataSchema: z.ZodObject<{
     modelId: z.ZodOptional<z.ZodString>;
     usage: z.ZodOptional<z.ZodUnknown>;
     error: z.ZodOptional<z.ZodString>;
+    errorDiagnostics: z.ZodOptional<z.ZodObject<{
+        cause: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            requestId: z.ZodOptional<z.ZodString>;
+            cause: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+                code: z.ZodOptional<z.ZodString>;
+                status: z.ZodOptional<z.ZodNumber>;
+                requestId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const sparkDataPartSchemas: {
     readonly "tool-input-label": z.ZodObject<{
@@ -211,6 +236,27 @@ export declare const sparkDataPartSchemas: {
             incomplete: "incomplete";
         }>;
         error: z.ZodOptional<z.ZodString>;
+        errorDiagnostics: z.ZodOptional<z.ZodObject<{
+            cause: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+                code: z.ZodOptional<z.ZodString>;
+                status: z.ZodOptional<z.ZodNumber>;
+                requestId: z.ZodOptional<z.ZodString>;
+                cause: z.ZodOptional<z.ZodObject<{
+                    message: z.ZodString;
+                    name: z.ZodOptional<z.ZodString>;
+                    code: z.ZodOptional<z.ZodString>;
+                    status: z.ZodOptional<z.ZodNumber>;
+                    requestId: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            message: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
         label: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     readonly "step-metrics": z.ZodObject<{

package/dist/ui.js

@@ -1,3 +1,5 @@
+import { sparkErrorDiagnosticsSchema } from "./error-diagnostics.js";
+export { sparkErrorDiagnostics, sparkErrorDiagnosticsSchema, } from "./error-diagnostics.js";
 import { z } from "zod";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export const SPARK_RUN_STATUSES = [
@@ -48,9 +50,14 @@ export const sparkMessageMetadataSchema = z.object({
     modelId: z.string().optional(),
     usage: z.unknown().optional(),
     error: z.string().optional(),
+    errorDiagnostics: sparkErrorDiagnosticsSchema.optional(),
 });
 export const sparkDataPartSchemas = {
-    "tool-input-label": z.object({ toolCallId: z.string(), field: z.enum(["name", "purpose"]), value: z.string() }),
+    "tool-input-label": z.object({
+        toolCallId: z.string(),
+        field: z.enum(["name", "purpose"]),
+        value: z.string(),
+    }),
     "execution-receipt": z.object({ toolCallId: z.string(), receipt: sparkExecutionReceiptSchema }),
     console: z.object({
         stream: z.enum(["stdout", "stderr"]),
@@ -61,6 +68,7 @@ export const sparkDataPartSchemas = {
         runId: z.string().min(1),
         status: z.enum(SPARK_RUN_STATUSES),
         error: z.string().optional(),
+        errorDiagnostics: sparkErrorDiagnosticsSchema.optional(),
         label: z.string().optional(),
     }),
     "step-metrics": z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",

package/.env.example

@@ -1,6 +0,0 @@
-OPENAI_API_KEY=
-ANTHROPIC_API_KEY=
-GEMINI_API_KEY=
-KAKAPO_URL=ws://127.0.0.1:5502
-PORT=8787
-SPARK_STORAGE_PATH=.spark/spark.sqlite