@womp/spark-agent 3.0.1 → 3.0.3

package/dist/prompt.js

@@ -1,19 +1,19 @@
-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.
-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. 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
+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.
+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. 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.`;

package/dist/scene-operations.js

@@ -113,11 +113,16 @@ export async function executeSceneOperation(options) {
     catch (error) {
         const status = error instanceof KakapoSceneCommitError ? error.outcome
             : "rolled_back";
-        await store.saveSceneOperation({
-            ...(status === "rolled_back" ? complete(operation, status) : { ...operation, status }),
-            error: error instanceof Error ? error.message : String(error),
-            ...(operation.save && status === "rolled_back" ? { save: { status: "not_needed" } } : {}),
-        });
+        try {
+            await store.saveSceneOperation({
+                ...(status === "rolled_back" ? complete(operation, status) : { ...operation, status }),
+                error: error instanceof Error ? error.message : String(error),
+                ...(operation.save && status === "rolled_back" ? { save: { status: "not_needed" } } : {}),
+            });
+        }
+        catch {
+            // Keep the original error; recovery can inspect the prepared record.
+        }
         throw error;
     }
     // Recovery requires both the operation marker and the exact prepared scene revision.

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

@@ -24,8 +24,8 @@ export type SdkSceneEditorOptions = {
     /** Supply this when the host adds a stricter connection lifetime. */
     context?: SparkInvocationContext) => Promise<T>): Promise<T>;
     assertEditable(context: SparkInvocationContext): void | Promise<void>;
-    /** Acquire host coordination only after the draft is durably prepared. */
-    prepareCommit?(operation: SceneOperation, context: SparkInvocationContext): Promise<() => void | Promise<void>>;
+    /** Acquire after preparation. Cleanup receives false until rollback or host synchronization is confirmed. */
+    prepareCommit?(operation: SceneOperation, context: SparkInvocationContext): Promise<(synchronized: boolean) => void | Promise<void>>;
     /** Must adopt each operation ID at most once, including during recovery. */
     onCommitted?(operation: SceneOperation, api: KakapoAPI, context: SparkInvocationContext, identity: SdkSceneEditIdentity): Promise<Record<string, unknown> | void>;
 };

package/dist/sdk-scene-host.js

@@ -89,6 +89,26 @@ export function createSdkSceneEditor(options) {
                     },
                 });
                 let releaseCommit;
+                let synchronized = false;
+                let hostDetails = {};
+                const record = async (operation, details) => {
+                    hostDetails = { ...hostDetails, ...details };
+                    await activeContext.recordReceipt({
+                        ...receipt(),
+                        status: operation.status === "committed"
+                            ? "committed"
+                            : operation.status === "rolled_back"
+                                ? "rolled_back"
+                                : "unknown",
+                        details: {
+                            ...hostDetails,
+                            result: operation.result,
+                            save: operation.save,
+                            error: operation.error,
+                            synchronized,
+                        },
+                    });
+                };
                 try {
                     let result;
                     try {
@@ -117,39 +137,54 @@ export function createSdkSceneEditor(options) {
                         });
                     }
                     catch (error) {
-                        const operation = await options.operations.getSceneOperation(options.targetKey, id);
-                        if (operation)
-                            await activeContext.recordReceipt({
-                                ...receipt(),
-                                status: operation.status === "committed"
-                                    ? "committed"
-                                    : operation.status === "rolled_back"
-                                        ? "rolled_back"
-                                        : "unknown",
-                            });
+                        // Receipt persistence must not replace the original SDK/tool error.
+                        try {
+                            const operation = await options.operations.getSceneOperation(options.targetKey, id);
+                            if (operation) {
+                                synchronized = operation.status === "rolled_back";
+                                await record(operation);
+                            }
+                        }
+                        catch {
+                            /* The prepared receipt remains recoverable. */
+                        }
                         throw error;
                     }
-                    let details;
-                    if (result.operation.changed) {
-                        const adopted = await options.onCommitted?.(result.operation, api, activeContext, identity);
-                        const finalized = await afterCommitted?.(result.operation, api);
-                        details = { ...adopted, ...finalized };
+                    synchronized = !result.operation.changed || !options.onCommitted;
+                    await record(result.operation);
+                    if (!synchronized) {
+                        let details;
+                        try {
+                            details = await options.onCommitted(result.operation, api, activeContext, identity);
+                            synchronized = true;
+                        }
+                        catch (error) {
+                            try {
+                                await record(result.operation, {
+                                    synchronizationError: error instanceof Error ? error.message : String(error),
+                                });
+                            }
+                            catch {
+                                /* Preserve the synchronization error. */
+                            }
+                            throw error;
+                        }
+                        await record(result.operation, details || undefined);
                     }
-                    await activeContext.recordReceipt({
-                        ...receipt(),
-                        status: "committed",
-                        ...(details && Object.keys(details).length ? { details } : {}),
-                    });
                     if (result.operation.changed) {
                         if (result.operation.save?.status === "failed")
                             throw new Error(`The scene edit was applied, but the save failed: ${result.operation.save.error} Do not repeat the edit.`);
-                        if (result.operation.save?.status === "unknown")
+                        if (result.operation.save?.status === "unknown" ||
+                            result.operation.save?.status === "requested")
                             throw new Error("The scene edit was applied, but its save outcome is unknown. Inspect persistence before continuing; do not repeat the edit.");
+                        const details = await afterCommitted?.(result.operation, api);
+                        if (details)
+                            await record(result.operation, details);
                     }
                     return result;
                 }
                 finally {
-                    await releaseCommit?.();
+                    await releaseCommit?.(synchronized);
                 }
             });
         },

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/sqlite-store.js

@@ -39,14 +39,14 @@ export class SqliteSparkStore {
       CREATE TABLE IF NOT EXISTS execution_owner (
         singleton INTEGER PRIMARY KEY CHECK (singleton = 1), pid INTEGER NOT NULL, token TEXT NOT NULL
       );
-      CREATE TABLE IF NOT EXISTS scene_operations (
-        target_key TEXT NOT NULL, id TEXT NOT NULL, revision INTEGER NOT NULL, data TEXT NOT NULL,
-        PRIMARY KEY (target_key, id)
-      );
-      CREATE TABLE IF NOT EXISTS repair_states (
-        target_key TEXT PRIMARY KEY, revision INTEGER NOT NULL, data TEXT NOT NULL
-      );
-      PRAGMA user_version = 4;
+      CREATE TABLE IF NOT EXISTS scene_operations (
+        target_key TEXT NOT NULL, id TEXT NOT NULL, revision INTEGER NOT NULL, data TEXT NOT NULL,
+        PRIMARY KEY (target_key, id)
+      );
+      CREATE TABLE IF NOT EXISTS repair_states (
+        target_key TEXT PRIMARY KEY, revision INTEGER NOT NULL, data TEXT NOT NULL
+      );
+      PRAGMA user_version = 4;
     `);
     }
     repairStateStore(targetKey) {

package/package.json

@@ -1,135 +1,135 @@
-{
-  "name": "@womp/spark-agent",
-  "version": "3.0.1",
-  "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "spark-agent": "dist/cli.js"
-  },
-  "exports": {
-    "./browser": {
-      "types": "./dist/browser.d.ts",
-      "import": "./dist/browser.js",
-      "default": "./dist/browser.js"
-    },
-    "./capabilities": {
-      "types": "./dist/capabilities.d.ts",
-      "import": "./dist/capabilities.js",
-      "default": "./dist/capabilities.js"
-    },
-    "./kakapo": {
-      "types": "./dist/kakapo.d.ts",
-      "import": "./dist/kakapo.js",
-      "default": "./dist/kakapo.js"
-    },
-    "./geometry": {
-      "types": "./dist/geometry.d.ts",
-      "import": "./dist/geometry.js",
-      "default": "./dist/geometry.js"
-    },
-    "./openscad": {
-      "types": "./dist/openscad.d.ts",
-      "import": "./dist/openscad.js",
-      "default": "./dist/openscad.js"
-    },
-    "./quickjs": {
-      "types": "./dist/quickjs-executor.d.ts",
-      "import": "./dist/quickjs-executor.js",
-      "default": "./dist/quickjs-executor.js"
-    },
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./ui": {
-      "types": "./dist/ui.d.ts",
-      "import": "./dist/ui.js",
-      "default": "./dist/ui.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js",
-      "default": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server/index.d.ts",
-      "import": "./dist/server/index.js",
-      "default": "./dist/server/index.js"
-    },
-    "./express": {
-      "types": "./dist/server/express.d.ts",
-      "import": "./dist/server/express.js",
-      "default": "./dist/server/express.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "dist/server/fixtures/**/*.json",
-    "dist/geometry/schemas/**/*.json",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.13"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wompxyz/spark-agent.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "yarn clean && node scripts/generate-skill-declarations.mjs && tsc -p tsconfig.json && node scripts/copy-fixtures.mjs",
-    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p web/tsconfig.json",
-    "lint": "yarn typecheck",
-    "dev": "yarn build && concurrently --kill-others \"yarn dev:server\" \"yarn dev:web\"",
-    "dev:server": "tsx src/cli.ts",
-    "dev:demo-account": "yarn build && concurrently --kill-others \"yarn dev:server --profile demo-account\" \"yarn dev:web\"",
-    "dev:web": "vite --config web/vite.config.ts",
-    "start": "node dist/cli.js",
-    "web:build": "yarn build && tsc --noEmit -p web/tsconfig.json && vite build --config web/vite.config.ts",
-    "test": "yarn build && tsx --tsconfig tsconfig.json --test test/**/*.test.ts && node --input-type=module -e \"await Promise.all([import('@womp/spark-agent'), import('@womp/spark-agent/ui'), import('@womp/spark-agent/client'), import('@womp/spark-agent/server'), import('@womp/spark-agent/express'), import('@womp/spark-agent/kakapo'), import('@womp/spark-agent/geometry'), import('@womp/spark-agent/openscad')])\"",
-    "test:live": "tsx --tsconfig tsconfig.json test/womp-scene-api.live.ts",
-    "prepack": "yarn build"
-  },
-  "dependencies": {
-    "@ai-sdk/anthropic": "4.0.50",
-    "@ai-sdk/google": "4.0.69",
-    "@ai-sdk/openai": "4.0.63",
-    "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
-    "@womp/flowir": "0.3.0",
-    "@womp/kakapo-sdk": "0.3.0",
-    "ai": "7.0.95",
-    "eventsource-parser": "^3.0.6",
-    "express": "^5.2.1",
-    "lodash": "4.18.1",
-    "quickjs-emscripten-core": "0.32.0",
-    "zod": "4.5.4"
-  },
-  "devDependencies": {
-    "@ai-sdk/react": "^4.0.77",
-    "@types/express": "^5.0.5",
-    "@types/lodash": "4.17.24",
-    "@types/node": "^24.0.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
-    "concurrently": "^9.2.1",
-    "lucide-react": "^1.26.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "react-markdown": "^10.1.0",
-    "remark-gfm": "^4.0.1",
-    "tsx": "^4.23.1",
-    "typescript": "^5.9.3",
-    "vite": "^8.1.5"
-  }
-}
+{
+  "name": "@womp/spark-agent",
+  "version": "3.0.3",
+  "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "spark-agent": "dist/cli.js"
+  },
+  "exports": {
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "import": "./dist/capabilities.js",
+      "default": "./dist/capabilities.js"
+    },
+    "./kakapo": {
+      "types": "./dist/kakapo.d.ts",
+      "import": "./dist/kakapo.js",
+      "default": "./dist/kakapo.js"
+    },
+    "./geometry": {
+      "types": "./dist/geometry.d.ts",
+      "import": "./dist/geometry.js",
+      "default": "./dist/geometry.js"
+    },
+    "./openscad": {
+      "types": "./dist/openscad.d.ts",
+      "import": "./dist/openscad.js",
+      "default": "./dist/openscad.js"
+    },
+    "./quickjs": {
+      "types": "./dist/quickjs-executor.d.ts",
+      "import": "./dist/quickjs-executor.js",
+      "default": "./dist/quickjs-executor.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js",
+      "default": "./dist/ui.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./express": {
+      "types": "./dist/server/express.d.ts",
+      "import": "./dist/server/express.js",
+      "default": "./dist/server/express.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/server/fixtures/**/*.json",
+    "dist/geometry/schemas/**/*.json",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wompxyz/spark-agent.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "yarn clean && node scripts/generate-skill-declarations.mjs && tsc -p tsconfig.json && node scripts/copy-fixtures.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p web/tsconfig.json",
+    "lint": "yarn typecheck",
+    "dev": "yarn build && concurrently --kill-others \"yarn dev:server\" \"yarn dev:web\"",
+    "dev:server": "tsx src/cli.ts",
+    "dev:demo-account": "yarn build && concurrently --kill-others \"yarn dev:server --profile demo-account\" \"yarn dev:web\"",
+    "dev:web": "vite --config web/vite.config.ts",
+    "start": "node dist/cli.js",
+    "web:build": "yarn build && tsc --noEmit -p web/tsconfig.json && vite build --config web/vite.config.ts",
+    "test": "yarn build && tsx --tsconfig tsconfig.json --test test/**/*.test.ts && node --input-type=module -e \"await Promise.all([import('@womp/spark-agent'), import('@womp/spark-agent/ui'), import('@womp/spark-agent/client'), import('@womp/spark-agent/server'), import('@womp/spark-agent/express'), import('@womp/spark-agent/kakapo'), import('@womp/spark-agent/geometry'), import('@womp/spark-agent/openscad')])\"",
+    "test:live": "tsx --tsconfig tsconfig.json test/womp-scene-api.live.ts",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "4.0.50",
+    "@ai-sdk/google": "4.0.69",
+    "@ai-sdk/openai": "4.0.63",
+    "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
+    "@womp/flowir": "0.3.0",
+    "@womp/kakapo-sdk": "0.3.1",
+    "ai": "7.0.95",
+    "eventsource-parser": "^3.0.6",
+    "express": "^5.2.1",
+    "lodash": "4.18.1",
+    "quickjs-emscripten-core": "0.32.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@ai-sdk/react": "^4.0.77",
+    "@types/express": "^5.0.5",
+    "@types/lodash": "4.17.24",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.4",
+    "concurrently": "^9.2.1",
+    "lucide-react": "^1.26.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5"
+  }
+}