@womp/spark-agent 3.0.3 → 4.0.1

package/dist/index.js

@@ -1,7 +1,6 @@
 export { runSparkAgent, } from "./agent.js";
 export { createSparkTools } from "./agent-tools.js";
 export { convertSparkMessages } from "./model-history.js";
-export { prepareSparkContext, estimateSparkContextTokens, SparkContextLimitError, } from "./context.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, } from "./sdk-scene-host.js";
 export { recoverSceneOperation } from "./scene-operations.js";

package/dist/models.d.ts

@@ -7,33 +7,40 @@ export type SparkModel = {
     note: string;
     provider: ModelProvider;
     reasoningEfforts: readonly ReasoningEffort[];
+    /** Published capacity for display only; providers enforce their own limits. */
+    contextWindow?: number;
 };
 export declare const SPARK_MODELS: readonly [{
     readonly id: "gpt-6-astra";
+    readonly contextWindow: 1050000;
     readonly label: "GPT-6 Astra";
     readonly note: "Best OpenAI quality";
     readonly provider: "openai";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
     readonly id: "gpt-5.6-luna";
+    readonly contextWindow: 1050000;
     readonly label: "GPT-5.6 Luna";
     readonly note: "Fast, cost-efficient OpenAI model";
     readonly provider: "openai";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
     readonly id: "gemini-3.8-flash";
+    readonly contextWindow: 1048576;
     readonly label: "Gemini 3.8 Flash";
     readonly note: "Fast Google model";
     readonly provider: "google";
     readonly reasoningEfforts: readonly ["low", "medium", "high"];
 }, {
     readonly id: "claude-opus-5";
+    readonly contextWindow: 1000000;
     readonly label: "Opus 5";
     readonly note: "Best Anthropic quality";
     readonly provider: "anthropic";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
     readonly id: "claude-fable-5";
+    readonly contextWindow: 1000000;
     readonly label: "Fable 5";
     readonly note: "Fast Anthropic model";
     readonly provider: "anthropic";

package/dist/models.js

@@ -15,6 +15,8 @@ const EXTENDED_REASONING_EFFORTS = [
 export const SPARK_MODELS = [
     {
         id: "gpt-6-astra",
+        // https://developers.openai.com/api/docs/models/gpt-6-astra
+        contextWindow: 1_050_000,
         label: "GPT-6 Astra",
         note: "Best OpenAI quality",
         provider: "openai",
@@ -22,6 +24,8 @@ export const SPARK_MODELS = [
     },
     {
         id: "gpt-5.6-luna",
+        // https://developers.openai.com/api/docs/models/gpt-5.6-luna
+        contextWindow: 1_050_000,
         label: "GPT-5.6 Luna",
         note: "Fast, cost-efficient OpenAI model",
         provider: "openai",
@@ -29,6 +33,8 @@ export const SPARK_MODELS = [
     },
     {
         id: "gemini-3.8-flash",
+        // https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash
+        contextWindow: 1_048_576,
         label: "Gemini 3.8 Flash",
         note: "Fast Google model",
         provider: "google",
@@ -36,6 +42,8 @@ export const SPARK_MODELS = [
     },
     {
         id: "claude-opus-5",
+        // https://platform.claude.com/docs/en/models/opus-5/whats-new-opus-5
+        contextWindow: 1_000_000,
         label: "Opus 5",
         note: "Best Anthropic quality",
         provider: "anthropic",
@@ -43,6 +51,8 @@ export const SPARK_MODELS = [
     },
     {
         id: "claude-fable-5",
+        // https://platform.claude.com/docs/en/models/fable-5/introducing-claude-fable-5-and-claude-mythos-5
+        contextWindow: 1_000_000,
         label: "Fable 5",
         note: "Fast Anthropic model",
         provider: "anthropic",

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.\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. Inspect 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.";
+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.\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. Inspect 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.";

package/dist/prompt.js

@@ -16,4 +16,56 @@ If an operation fails after earlier effects, use its receipts to inspect and ret
 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.`;
+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.
+
+- 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.
+
+- 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/request-limits.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_JSON_LIMIT_BYTES: number;

package/dist/request-limits.js

@@ -0,0 +1 @@
+export const DEFAULT_JSON_LIMIT_BYTES = 25 * 1024 * 1024;

package/dist/run-metrics.d.ts

@@ -0,0 +1,15 @@
+import type { SparkStepMetricsData, SparkUIMessageChunk } from "./ui.js";
+export declare function createBenchMetrics(): {
+    accept(chunk: SparkUIMessageChunk): void;
+    details(): {
+        toolCounts: Record<string, number>;
+        steps: SparkStepMetricsData[];
+    };
+    snapshot(): {
+        steps: number;
+        readSkill: number;
+        executeJavaScript: number;
+        costUsd: number | null;
+        costStatus: "unavailable" | "partial" | "estimated";
+    };
+};

package/dist/run-metrics.js

@@ -0,0 +1,30 @@
+export function createBenchMetrics() {
+    const steps = new Map();
+    const calls = new Map();
+    return {
+        accept(chunk) {
+            if (chunk.type === "data-step-metrics")
+                steps.set(chunk.data.step, chunk.data);
+            if (chunk.type === "tool-input-available")
+                calls.set(chunk.toolCallId, chunk.toolName);
+        },
+        details() {
+            const toolCounts = {};
+            for (const name of calls.values())
+                toolCounts[name] = (toolCounts[name] ?? 0) + 1;
+            return { toolCounts, steps: Array.from(steps.values()) };
+        },
+        snapshot() {
+            const names = Array.from(calls.values());
+            const priced = Array.from(steps.values()).map((step) => step.cost?.totalUsd ?? null)
+                .filter((cost) => cost !== null);
+            return {
+                steps: steps.size,
+                readSkill: names.filter((name) => name === "read_skill").length,
+                executeJavaScript: names.filter((name) => name === "execute_javascript").length,
+                costUsd: priced.length ? priced.reduce((sum, cost) => sum + cost, 0) : null,
+                costStatus: (priced.length === 0 ? "unavailable" : priced.length < steps.size ? "partial" : "estimated"),
+            };
+        },
+    };
+}

package/dist/runtime.d.ts

@@ -1,4 +1,5 @@
-import { KakapoAPI, type ScreenshotView } from "@womp/kakapo-sdk";
+import { KakapoAPI } from "@womp/kakapo-sdk";
+import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import type { JavaScriptExecutor } from "./executor.js";
 import type { ExecutionResult, ExecutionScreenshot, SparkRuntimeEventSink, SparkRuntime } from "./types.js";
 import { type WompSceneApi } from "./womp-scene-api.js";
@@ -31,9 +32,6 @@ export declare class KakapoRuntime implements SparkRuntime {
         scene: import("@womp/kakapo-sdk").Scene;
     }>;
     edit<T>(callback: (draft: WompSceneApi) => Promise<T> | T, expectedRevision: string, context: SparkInvocationContext): Promise<T>;
-    screenshot(input: {
-        targetId?: number;
-        view?: ScreenshotView;
-    }): Promise<ExecutionScreenshot>;
+    screenshot(input: SceneScreenshotOptions): Promise<ExecutionScreenshot>;
     execute(code: string, purpose: string): Promise<ExecutionResult>;
 }

package/dist/scene-metadata.js

@@ -41,7 +41,7 @@ export function shiftCurvePointMetadata(scene, curveId, index, direction) {
     if (direction === 1) {
         points[index] = {
             locked: false,
-            libraryId: metadataObject(points[String(Math.max(0, index - 1))]).libraryId ?? -1,
+            libraryId: -1,
             name: `Point ${index + 1}`,
         };
     }

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

@@ -1,6 +1,6 @@
 import type { FontFamily, KakapoAPI, SceneEdit, MaterialResource } from "@womp/kakapo-sdk";
 import type { ArtifactRef, SparkInvocationContext } from "./capabilities.js";
-import type { SceneHost, SceneScreenshotOptions } from "./capabilities/scene.js";
+import type { SceneHost, SceneHealthHost, SceneScreenshotOptions } from "./capabilities/scene.js";
 import { type SceneOperation, type SceneOperationStore } from "./scene-operations.js";
 import type { SceneHdr } from "./scene-environment.js";
 export type SdkSceneServices = {
@@ -82,6 +82,11 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
     nodeCreate: (type: number, parentId?: number) => number;
     nodeDelete: (id: number) => void;
     nodeClone: (id: number) => number;
+    cloneSubtree: (id: number, options?: {
+        parentId?: number;
+        name?: string;
+        index?: number;
+    }) => Promise<number>;
     nodeList: () => number[];
     nodeChildren: (parentId: number) => number[];
     nodeSetParent: (id: number, parentId: number, index?: number) => void;
@@ -118,7 +123,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
     nodeGetMaterialId: (id: number) => number | null;
     nodeSetMaterialId: (id: number, materialId: number) => void;
     nodeGetResolution: (id: number) => number;
-    nodeSetResolution: (id: number, resolution: number) => void;
+    nodeSetUnionResolution: (unionId: number, resolution: number) => void;
     nodeGetLightType: (id: number) => number;
     nodeSetLightType: (id: number, lightType: number) => void;
     nodeGetPower: (id: number) => number;
@@ -164,16 +169,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
     curvePointSetHandleIn: (curveId: number, pointIndex: number, value: import("@womp/kakapo-sdk").Vec3) => void;
     curvePointSetHandleOut: (curveId: number, pointIndex: number, value: import("@womp/kakapo-sdk").Vec3) => void;
     curvePointCount: (curveId: number) => number;
-    curvePointAdd: (curveId: number, point?: {
-        name?: string;
-        pos?: import("@womp/kakapo-sdk").Vec3;
-        rot?: import("@womp/kakapo-sdk").Vec3;
-        size?: import("@womp/kakapo-sdk").Vec3;
-        fixed?: boolean;
-        round?: number;
-        materialId?: number;
-    }) => number;
-    curvePointInsert: (curveId: number, pointIndex: number, point?: {
+    curvePointAdd: (curveId: number, point: {
         name?: string;
         pos?: import("@womp/kakapo-sdk").Vec3;
         rot?: import("@womp/kakapo-sdk").Vec3;
@@ -181,7 +177,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         fixed?: boolean;
         round?: number;
         materialId?: number;
-    }) => number;
+    }, pointIndex?: number) => number;
     curvePointRemove: (curveId: number, pointIndex: number) => void;
     curvePointGetName: (curveId: number, pointIndex: number) => string;
     curvePointSetName: (curveId: number, pointIndex: number, name: string) => void;
@@ -285,6 +281,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         max: import("@womp/kakapo-sdk").Vec3;
     }) => number;
     lookAt: (origin: import("@womp/kakapo-sdk").Vec3, target: import("@womp/kakapo-sdk").Vec3) => import("@womp/kakapo-sdk").Vec3;
+    alignAxis: (direction: import("@womp/kakapo-sdk").Vec3, axis: "x" | "y" | "z") => import("@womp/kakapo-sdk").Vec3;
     scenePropertiesRead: () => {
         hdr_name: string | undefined;
         hdr_multiplier: number | undefined;
@@ -306,6 +303,7 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
 export declare function createSdkSceneEditor(options: SdkSceneEditorOptions): SdkSceneEditor;
 export declare function createSdkSceneHost(options: SdkSceneEditorOptions & {
     editor?: SdkSceneEditor;
+    health?: SceneHealthHost;
     services(api: KakapoAPI, context: SparkInvocationContext): Promise<SdkSceneServices>;
     screenshot(options: SceneScreenshotOptions, context: SparkInvocationContext): Promise<ArtifactRef>;
     onSceneCommitted?(operation: SceneOperation, api: KakapoAPI): Promise<Record<string, unknown> | void>;

package/dist/sdk-scene-host.js

@@ -193,6 +193,7 @@ export function createSdkSceneEditor(options) {
 export function createSdkSceneHost(options) {
     const editor = options.editor ?? createSdkSceneEditor(options);
     return {
+        health: options.health?.read.bind(options.health),
         read: (context) => editor.read(context, async (api) => {
             const scene = api.getScene();
             const revision = await api.getSceneRevision();

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

@@ -1,7 +1,5 @@
-import type { KakapoAPI, ScreenshotView } from "@womp/kakapo-sdk";
+import type { KakapoAPI } from "@womp/kakapo-sdk";
+import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import type { ExecutionScreenshot } from "./types.js";
-/** Native capture policy shared by SDK-backed hosts; camera permissions belong to the host. */
-export declare function captureSdkSceneScreenshot(api: KakapoAPI, input: {
-    targetId?: number;
-    view?: ScreenshotView;
-}): Promise<ExecutionScreenshot>;
+/** Convert Womp scene coordinates at the host boundary; never fit a camera implicitly. */
+export declare function captureSdkSceneScreenshot(api: KakapoAPI, input: SceneScreenshotOptions): Promise<ExecutionScreenshot>;

package/dist/sdk-scene-screenshot.js

@@ -1,17 +1,16 @@
-/** Native capture policy shared by SDK-backed hosts; camera permissions belong to the host. */
+import { INTERNAL_UNITS_PER_MM, sceneUnitMultiplier, toEnginePosition } from "./coordinates.js";
+/** Convert Womp scene coordinates at the host boundary; never fit a camera implicitly. */
 export async function captureSdkSceneScreenshot(api, input) {
-    const view = input.view ?? (input.targetId === undefined ? "current" : "isometric");
-    let targetId = input.targetId;
-    if (view !== "current") {
-        await api.refreshScene();
-        if (targetId !== undefined) {
-            let target = api.getNode(targetId);
-            while (target.parentId !== null && target.parentId !== 0) {
-                target = api.getNode(target.parentId);
-            }
-            if (target.kind === "union" || target.kind === "group")
-                targetId = target.id;
-        }
-    }
-    return api.captureScreenshot({ targetId, view, timeoutMs: 30_000 });
+    if (!input.camera)
+        return api.captureScreenshot({ timeoutMs: 30_000 });
+    const scene = await api.refreshScene();
+    const units = sceneUnitMultiplier(scene.properties.unit_multiplier);
+    const camera = {
+        ...input.camera,
+        position: toEnginePosition(input.camera.position, units),
+        target: toEnginePosition(input.camera.target, units),
+    };
+    if (camera.orthographicWidth !== undefined)
+        camera.orthographicWidth *= INTERNAL_UNITS_PER_MM / units;
+    return api.captureScreenshot({ camera, timeoutMs: 30_000 });
 }

package/dist/server/artifacts.js

@@ -11,13 +11,9 @@ export class MemorySparkArtifactStore {
             ownerId,
             url: `${this.publicBaseUrl}/${id}`,
             mediaType: screenshot.mediaType,
-            name: `spark-${screenshot.view}.jpg`,
+            name: "spark-screenshot.jpg",
             width: screenshot.width,
             height: screenshot.height,
-            metadata: {
-                view: screenshot.view,
-                targetId: screenshot.targetId,
-            },
             data: screenshot.data.slice(),
         };
         this.artifacts.set(id, artifact);

package/dist/server/executor.d.ts

@@ -6,7 +6,6 @@ export type ResolvedSparkModel = {
     modelId: string;
     providerOptions?: SparkAgentOptions["providerOptions"];
     maxOutputTokens?: number;
-    maxInputTokens?: number;
 };
 export type SparkRunExecutorOptions = {
     resolveModel(settings: SparkRunSettings): ResolvedSparkModel | Promise<ResolvedSparkModel>;

package/dist/server/executor.js

@@ -20,7 +20,6 @@ export function createSparkRunExecutor(options) {
                 modelId: resolved.modelId,
                 providerOptions: resolved.providerOptions,
                 maxOutputTokens: resolved.maxOutputTokens,
-                maxInputTokens: resolved.maxInputTokens,
                 runId: context.runId,
                 messageId: context.assistantMessageId,
                 signal: context.signal,

package/dist/server/express.js

@@ -3,7 +3,12 @@ import express from "express";
 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";
 const reasoningEffortSchema = z.enum(["low", "medium", "high", "xhigh", "max"]);
+const settingsSchema = z.object({
+    modelId: z.string().min(1),
+    reasoningEffort: reasoningEffortSchema,
+});
 const messageSchema = z.object({
     id: z.string().min(1),
     role: z.enum(["system", "user", "assistant"]),
@@ -14,10 +19,7 @@ const submitSchema = z.object({
     trigger: z.enum(["submit-message", "regenerate-message"]),
     message: messageSchema,
     messageId: z.string().optional(),
-    settings: z.object({
-        modelId: z.string().min(1),
-        reasoningEffort: reasoningEffortSchema,
-    }),
+    settings: settingsSchema,
 });
 function parseSequence(value) {
     if (typeof value !== "string" || /^\d+$/u.test(value) === false)
@@ -37,7 +39,7 @@ export function createSparkAgentRouter(options) {
     const router = express.Router();
     const resolveOwnerId = options.resolveOwnerId ?? (() => "local");
     const heartbeatMs = options.heartbeatMs ?? 15_000;
-    router.use(express.json({ limit: options.jsonLimit ?? "25mb" }));
+    router.use(express.json({ limit: options.jsonLimit ?? DEFAULT_JSON_LIMIT_BYTES }));
     router.get("/conversations", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         response.json({ conversations: await options.service.listConversations(ownerId) });
@@ -56,6 +58,16 @@ export function createSparkAgentRouter(options) {
         const conversation = await options.service.getConversation(ownerId, request.params.conversationId);
         response.json({ conversation });
     });
+    router.patch("/conversations/:conversationId/settings", async (request, response) => {
+        const ownerId = await resolveOwnerId(request);
+        await options.service.saveConversationSettings(ownerId, request.params.conversationId, settingsSchema.parse(request.body));
+        response.sendStatus(204);
+    });
+    router.delete("/conversations/:conversationId", async (request, response) => {
+        const ownerId = await resolveOwnerId(request);
+        await options.service.deleteConversation(ownerId, request.params.conversationId);
+        response.status(204).end();
+    });
     router.post("/conversations/:conversationId/messages", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         const body = submitSchema.parse(request.body);

package/dist/server/scene-actions.d.ts

@@ -0,0 +1,2 @@
+import type { SceneEdit } from "@womp/kakapo-sdk";
+export declare function clearSceneContents(scene: SceneEdit): number;

package/dist/server/scene-actions.js

@@ -0,0 +1,20 @@
+function nodeDepth(node, nodes) {
+    let depth = 0;
+    let parentId = node.parentId;
+    while (parentId !== null && parentId !== 0) {
+        depth += 1;
+        parentId = nodes.get(parentId)?.parentId ?? null;
+    }
+    return depth;
+}
+export function clearSceneContents(scene) {
+    const nodes = scene.listNodes().filter(({ id }) => id !== 0);
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    nodes.sort((a, b) => nodeDepth(b, nodesById) - nodeDepth(a, nodesById));
+    for (const node of nodes)
+        scene.deleteNode(node.id);
+    const materials = scene.listMaterials();
+    for (const material of materials)
+        scene.deleteMaterial(material.id);
+    return nodes.length + materials.length;
+}

package/dist/server/service.d.ts

@@ -28,6 +28,8 @@ export declare class SparkAgentService {
     }): Promise<SparkConversation>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     getConversation(ownerId: string, id: string): Promise<SparkConversation>;
+    saveConversationSettings(ownerId: string, id: string, settings: SparkRunSettings): Promise<void>;
+    deleteConversation(ownerId: string, id: string): Promise<void>;
     getRun(ownerId: string, id: string): Promise<SparkRun>;
     getActiveRun(ownerId: string, conversationId: string): Promise<SparkRun | undefined>;
     /** The host must establish exclusive ownership before recovering abandoned runs. */

package/dist/server/service.js

@@ -96,6 +96,16 @@ export class SparkAgentService {
         }
         return conversation;
     }
+    async saveConversationSettings(ownerId, id, settings) {
+        await this.getConversation(ownerId, id);
+        await this.store.saveConversationSettings(id, settings);
+    }
+    async deleteConversation(ownerId, id) {
+        await this.getConversation(ownerId, id);
+        if (await this.store.deleteConversation(id) === false) {
+            throw new SparkServiceError(409, "Stop the active run before deleting this conversation.");
+        }
+    }
     async getRun(ownerId, id) {
         const run = await this.store.getRun(id);
         if (run === undefined)

package/dist/server/sqlite-store.d.ts

@@ -3,7 +3,7 @@ import type { SparkArtifact, StoredSparkChunk } from "../ui.js";
 import type { SparkArtifactStore, StoredSparkArtifact } from "./artifacts.js";
 import type { SceneOperation, SceneOperationStore } from "../scene-operations.js";
 import { type RepairStateStore } from "../repair-state.js";
-import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun } from "./types.js";
+import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun, SparkRunSettings } from "./types.js";
 /** Local development storage. Execution ownership belongs to the host service. */
 export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactStore, SceneOperationStore {
     private readonly artifactBaseUrl;
@@ -21,6 +21,8 @@ export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactS
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     saveConversation(value: SparkConversation): Promise<void>;
+    saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
+    deleteConversation(id: string): Promise<boolean>;
     createRun(value: SparkRun): Promise<void>;
     getRun(id: string): Promise<SparkRun | undefined>;
     saveRun(value: SparkRun): Promise<void>;

package/dist/server/sqlite-store.js

@@ -159,10 +159,34 @@ export class SqliteSparkStore {
         });
     }
     async saveConversation(value) {
-        const result = this.database.prepare("UPDATE conversations SET owner_id = ?, updated_at = ?, data = ? WHERE id = ?").run(value.ownerId, value.updatedAt, JSON.stringify(value), value.id);
+        const result = this.database.prepare("UPDATE conversations SET owner_id = ?, updated_at = ?, data = json_patch(json_remove(?, '$.settings'), json_object('settings', json_extract(data, '$.settings'))) WHERE id = ?").run(value.ownerId, value.updatedAt, JSON.stringify(value), value.id);
         if (result.changes === 0)
             throw new Error(`Conversation ${value.id} does not exist.`);
     }
+    async saveConversationSettings(id, settings) {
+        const result = this.database.prepare("UPDATE conversations SET data = json_set(data, '$.settings', json(?)) WHERE id = ?").run(JSON.stringify(settings), id);
+        if (result.changes === 0)
+            throw new Error(`Conversation ${id} does not exist.`);
+    }
+    async deleteConversation(id) {
+        this.database.exec("BEGIN IMMEDIATE");
+        try {
+            const active = this.database.prepare("SELECT id FROM conversations WHERE id = ? AND json_extract(data, '$.activeRunId') IS NOT NULL").get(id);
+            if (active) {
+                this.database.exec("ROLLBACK");
+                return false;
+            }
+            this.database.prepare("DELETE FROM chunks WHERE run_id IN (SELECT id FROM runs WHERE conversation_id = ?)").run(id);
+            this.database.prepare("DELETE FROM runs WHERE conversation_id = ?").run(id);
+            this.database.prepare("DELETE FROM conversations WHERE id = ?").run(id);
+            this.database.exec("COMMIT");
+            return true;
+        }
+        catch (error) {
+            this.database.exec("ROLLBACK");
+            throw error;
+        }
+    }
     async createRun(value) {
         this.database.prepare("INSERT INTO runs VALUES (?, ?, ?)")
             .run(value.id, value.conversationId, JSON.stringify(value));
@@ -205,9 +229,8 @@ export class SqliteSparkStore {
         const id = crypto.randomUUID();
         const artifact = {
             id, url: `${this.artifactBaseUrl.replace(/\/$/u, "")}/${id}`,
-            mediaType: image.mediaType, name: `spark-${image.view}.jpg`,
+            mediaType: image.mediaType, name: "spark-screenshot.jpg",
             width: image.width, height: image.height,
-            metadata: { view: image.view, targetId: image.targetId },
         };
         this.database.prepare("INSERT INTO artifacts VALUES (?, ?, ?, ?)")
             .run(id, ownerId, JSON.stringify(artifact), image.data);

package/dist/server/standalone.d.ts

@@ -11,6 +11,8 @@ export type StandaloneSparkAgentOptions = {
     /** Stable host-verified identity for the scene behind kakapoUrl. */
     sceneIdentity?: string;
     logger?: Pick<Console, "info" | "warn">;
+    /** Observe successful renderer captures, including captures not attached to a reply. */
+    onScreenshot?: (runId: string) => void;
 };
 export type StandaloneSparkAgentApp = Express & {
     dispose(): Promise<void>;