@womp/spark-agent 4.2.2 → 4.3.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/models.d.ts

@@ -18,10 +18,17 @@ export declare const SPARK_MODELS: readonly [{
     readonly provider: "openai";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
-    readonly id: "gpt-5.6-luna";
+    readonly id: "gpt-6-sol";
     readonly contextWindow: 1050000;
-    readonly label: "GPT-5.6 Luna";
-    readonly note: "Fast, cost-efficient OpenAI model";
+    readonly label: "GPT-6 Sol";
+    readonly note: "Complex coding and agentic workflows";
+    readonly provider: "openai";
+    readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
+}, {
+    readonly id: "gpt-6-luna";
+    readonly contextWindow: 1050000;
+    readonly label: "GPT-6 Luna";
+    readonly note: "Efficient, high-volume OpenAI model";
     readonly provider: "openai";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
@@ -32,9 +39,9 @@ export declare const SPARK_MODELS: readonly [{
     readonly provider: "google";
     readonly reasoningEfforts: readonly ["low", "medium", "high"];
 }, {
-    readonly id: "claude-opus-5";
+    readonly id: "claude-opus-5-5";
     readonly contextWindow: 1000000;
-    readonly label: "Opus 5";
+    readonly label: "Opus 5.5";
     readonly note: "Best Anthropic quality";
     readonly provider: "anthropic";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];

package/dist/models.js

@@ -23,11 +23,20 @@ export const SPARK_MODELS = [
         reasoningEfforts: EXTENDED_REASONING_EFFORTS,
     },
     {
-        id: "gpt-5.6-luna",
-        // https://developers.openai.com/api/docs/models/gpt-5.6-luna
+        id: "gpt-6-sol",
+        // https://developers.openai.com/api/docs/models/gpt-6-sol
         contextWindow: 1_050_000,
-        label: "GPT-5.6 Luna",
-        note: "Fast, cost-efficient OpenAI model",
+        label: "GPT-6 Sol",
+        note: "Complex coding and agentic workflows",
+        provider: "openai",
+        reasoningEfforts: EXTENDED_REASONING_EFFORTS,
+    },
+    {
+        id: "gpt-6-luna",
+        // https://developers.openai.com/api/docs/models/gpt-6-luna
+        contextWindow: 1_050_000,
+        label: "GPT-6 Luna",
+        note: "Efficient, high-volume OpenAI model",
         provider: "openai",
         reasoningEfforts: EXTENDED_REASONING_EFFORTS,
     },
@@ -41,10 +50,10 @@ export const SPARK_MODELS = [
         reasoningEfforts: ["low", "medium", "high"],
     },
     {
-        id: "claude-opus-5",
-        // https://platform.claude.com/docs/en/models/opus-5/whats-new-opus-5
+        id: "claude-opus-5-5",
+        // https://platform.claude.com/docs/en/models/opus-5-5/overview
         contextWindow: 1_000_000,
-        label: "Opus 5",
+        label: "Opus 5.5",
         note: "Best Anthropic quality",
         provider: "anthropic",
         reasoningEfforts: EXTENDED_REASONING_EFFORTS,

package/dist/pricing.js

@@ -1,5 +1,15 @@
 // Standard, global, direct API rates in USD per million tokens, checked 2026-09-09.
 const PRICES = {
+    "gpt-6-sol": {
+        input: 2, read: 0.2, write: 2.5, output: 10, longContext: 272_000,
+        source: "https://developers.openai.com/api/docs/pricing",
+        pricingDate: "2026-09-22",
+    },
+    "gpt-6-luna": {
+        input: 0.1, read: 0.01, write: 0.125, output: 0.5, longContext: 272_000,
+        source: "https://developers.openai.com/api/docs/pricing",
+        pricingDate: "2026-09-22",
+    },
     "gpt-5.6-luna": {
         input: 0.2, read: 0.02, write: 0.25, output: 1.2, longContext: 272_000,
         source: "https://developers.openai.com/api/docs/models/gpt-5.6-luna",
@@ -14,6 +24,11 @@ const PRICES = {
         input: 10, read: 1, write: 12.5, output: 50, longContext: 272_000,
         source: "https://developers.openai.com/api/docs/models/gpt-6-astra",
     },
+    "claude-opus-5-5": {
+        input: 4, read: 0.2, write: 5, output: 20,
+        source: "https://platform.claude.com/docs/en/models/opus-5-5/overview",
+        pricingDate: "2026-09-22",
+    },
     "claude-opus-5": {
         input: 5, read: 0.5, write: 6.25, output: 25,
         source: "https://platform.claude.com/docs/en/models/opus-5/overview",

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- 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.";
+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\nResolve the requested outcome from the current message and preceding dialogue, not keyword matches.\nExplicit method choices take precedence. Continue edits in the existing representation unless the user\nasks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.\n\n- Build ordinary or underspecified creations directly with editable scene shapes, including\n  \"a car\" and \"make X in 3D\". Proceed without an image preview or method-selection menu.\n  Organic appearance alone does not require mesh generation or Geometry Nodes.\n\n- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,\n  except when another method is explicit (including primitives with dimensions), or when\n  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:\n  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.\n\n- Generate/edit images or generate meshes when requested. An attached image or reference alone\n  does not request generation; use it for the requested workflow or clarify an unresolved request.\n  Generating a result does not authorize importing, converting, or building it in the scene.\n\n- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or\n  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be\n  open; explain that prerequisite if closed instead of silently generating inline. Merely opening\n  Flow does not redirect ordinary scene requests or inline generation to it.\n\n- After completing explicitly requested generation, you may briefly suggest a relevant next step\n  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,\n  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing\n  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the\n  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.\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- 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. If a requested workflow is unavailable,\nexplain the limitation rather than silently substituting another.";

package/dist/prompt.js

@@ -1,55 +1,57 @@
-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
+
+Resolve the requested outcome from the current message and preceding dialogue, not keyword matches.
+Explicit method choices take precedence. Continue edits in the existing representation unless the user
+asks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.
+
+- Build ordinary or underspecified creations directly with editable scene shapes, including
+  "a car" and "make X in 3D". Proceed without an image preview or method-selection menu.
+  Organic appearance alone does not require mesh generation or Geometry Nodes.
+
+- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,
+  except when another method is explicit (including primitives with dimensions), or when
+  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:
+  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.
+
+- Generate/edit images or generate meshes when requested. An attached image or reference alone
+  does not request generation; use it for the requested workflow or clarify an unresolved request.
+  Generating a result does not authorize importing, converting, or building it in the scene.
+
+- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or
+  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be
+  open; explain that prerequisite if closed instead of silently generating inline. Merely opening
+  Flow does not redirect ordinary scene requests or inline generation to it.
+
+- After completing explicitly requested generation, you may briefly suggest a relevant next step
+  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,
+  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing
+  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the
+  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.
+
 - 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 +59,15 @@ 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.
-
+
+- 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.`;
+and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
+explain the limitation rather than silently substituting another.`;

package/dist/server/express.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { SPARK_RUN_STATUSES } from "../ui.js";
 import { SparkServiceError } from "./service.js";
 import { DEFAULT_JSON_LIMIT_BYTES } from "../request-limits.js";
+import { sparkErrorDiagnostics } from "../error-diagnostics.js";
 const reasoningEffortSchema = z.enum(["low", "medium", "high", "xhigh", "max"]);
 const settingsSchema = z.object({
     modelId: z.string().min(1),
@@ -164,7 +165,14 @@ export function createSparkAgentRouter(options) {
             response.status(400).json({ error: "Invalid request.", issues: error.issues });
             return;
         }
-        response.status(500).json({ error: "Internal Spark Agent error." });
+        const diagnostics = sparkErrorDiagnostics(error);
+        const status = diagnostics.status && diagnostics.status >= 400 ? diagnostics.status : 500;
+        if (status === 413)
+            diagnostics.message = "Request is too large. Remove some image attachments or use smaller images.";
+        // JSON parse errors can quote user content; keep only the parser category.
+        if (error instanceof SyntaxError && status === 400)
+            diagnostics.message = "Invalid JSON request body.";
+        response.status(status).json({ error: diagnostics.message, diagnostics });
     });
     return router;
 }

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/message-fold.d.ts

@@ -0,0 +1,59 @@
+import type { SparkUIMessage, SparkUIMessageChunk, StoredSparkChunk } from "../ui.js";
+/** Reads the stored chunks after `afterSequence`, in sequence order. */
+export type ListChunksAfter = (afterSequence: number) => Promise<StoredSparkChunk[]>;
+export type RunMessageFold = {
+    /**
+     * The message as a full replay of every stored chunk would build it, or
+     * `undefined` when the run has no chunk the reader writes a message for.
+     * Rejects only if `list` rejects. Calls must not overlap.
+     *
+     * THE ANSWER SHARES PART OBJECTS WITH THE FOLD'S SETTLED MESSAGE, and later
+     * answers hand back the same objects for settled parts. A caller must not
+     * mutate a part it is given (copy it instead), or the next answer is wrong.
+     *
+     * WHILE A PART STAYS OPEN ACROSS STEPS nothing settles, and each read has to
+     * fold everything since the last settled point. Once that tail is
+     * `UNSETTLED_TAIL_THROTTLE` chunks long, a read folds it again only after it
+     * has grown by a quarter, and otherwise answers with the last message it
+     * built, a little behind the chunks. That keeps the total work a few full
+     * passes rather than one per read. `complete: true` always folds everything
+     * (a run's ending).
+     */
+    read(list: ListChunksAfter, options?: {
+        complete?: boolean;
+    }): Promise<SparkUIMessage | undefined>;
+    /** How many chunks the reader has been given in total. A read adds the
+     *  chunks since the last settled step start, not the whole run's. */
+    foldedChunks(): number;
+};
+/** How many step starts may pass with a part still open before it is logged. */
+export declare const UNSETTLED_STEPS_LOGGED = 10;
+export type RunMessageFoldOptions = {
+    /**
+     * Called once per run when a text, reasoning or tool input part has stayed
+     * open across `UNSETTLED_STEPS_LOGGED` step starts. Until it closes nothing
+     * settles, so every read folds all the chunks since the last settled point,
+     * as a full replay would: correct, but its cost grows with the run again.
+     */
+    onUnsettled?(detail: {
+        steps: number;
+        chunks: number;
+    }): void;
+};
+/** An unsettled tail this long is re-folded only after it grows by a quarter. */
+export declare const UNSETTLED_TAIL_THROTTLE = 400;
+export declare function createRunMessageFold(options?: RunMessageFoldOptions): RunMessageFold;
+/** How long `foldAllChunks` works before it lets other callbacks run. */
+export declare const FOLD_YIELD_MS = 10;
+/**
+ * The message a full replay of `chunks` builds (the last message
+ * `readUIMessageStream` yields, with `terminateOnError: false`), folded a step
+ * at a time and giving the event loop back every `FOLD_YIELD_MS`. The reader
+ * only ever sees about one step's chunks and the parts they name; with a part
+ * left open across steps, one pass over the rest of the run.
+ */
+export declare function foldAllChunks(chunks: readonly SparkUIMessageChunk[], options?: {
+    yieldMs?: number;
+    /** A fresh fold to read through, whose `foldedChunks()` then says what it cost. */
+    fold?: RunMessageFold;
+}): Promise<SparkUIMessage | undefined>;