@womp/spark-agent 4.1.1 → 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/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/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.1",
+  "version": "4.1.2",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",