@womp/spark-agent 4.4.1 → 5.0.0

package/dist/server/standalone.js

@@ -3,7 +3,7 @@ import { createOpenAI } from "@ai-sdk/openai";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import express from "express";
 import { getSparkModel, SPARK_MODELS } from "../models.js";
-import { KakapoAPI, KakapoRpcError } from "@womp/kakapo-sdk";
+import { KakapoAPI, KakapoRpcError, KakapoSceneCommitError } from "@womp/kakapo-sdk";
 import { captureSdkSceneScreenshot } from "../sdk-scene-screenshot.js";
 import { composeCapabilities, createAccountCapability, createGeometryCapability, createOpenScadCapability, createSceneCapability, } from "../capabilities.js";
 import { loadDemoSceneMaterials } from "./demo-scene-materials.js";
@@ -13,7 +13,7 @@ import { createSdkGeometryHost } from "../sdk-geometry-host.js";
 import { createSdkOpenScadHost } from "../sdk-openscad-host.js";
 import { createSdkSceneHealthHost } from "../sdk-scene-health-host.js";
 import { geometryReference } from "../geometry.js";
-import { getSdkSceneAreaIds, hasSceneResourcePressure, readStableSdkSceneHealth, } from "../scene-health.js";
+import { hasSceneResourcePressure, } from "../scene-health.js";
 import { QuickJSJavaScriptExecutor } from "../quickjs-executor.js";
 import { sparkModelOptions } from "../model-options.js";
 import { createSparkRunExecutor } from "./executor.js";
@@ -21,7 +21,7 @@ import { createSparkAgentRouter } from "./express.js";
 import { SparkAgentService } from "./service.js";
 import { SqliteSparkStore } from "./sqlite-store.js";
 import { clearSceneContents } from "./scene-actions.js";
-import { initializeStandaloneScene } from "./scene-initialization.js";
+import { standaloneSceneAccess } from "./scene-access.js";
 export async function checkStandaloneServices(api) {
     const [fonts, openScad] = await Promise.allSettled([
         api.listFonts(),
@@ -57,6 +57,7 @@ export async function createStandaloneSparkAgentApp(options) {
         throw error;
     }
     const artifactStore = store;
+    const sceneAccess = standaloneSceneAccess(options.kakapoUrl);
     const executeRun = createSparkRunExecutor({
         createHost: async (context) => {
             const api = new KakapoAPI({
@@ -65,9 +66,7 @@ export async function createStandaloneSparkAgentApp(options) {
             });
             try {
                 context.signal.throwIfAborted();
-                await api.connect();
-                context.signal.throwIfAborted();
-                await initializeStandaloneScene(api, context.signal);
+                await api.connect({ refreshScene: false });
                 context.signal.throwIfAborted();
                 const support = await checkStandaloneServices(api);
                 const services = {
@@ -81,12 +80,12 @@ export async function createStandaloneSparkAgentApp(options) {
                     targetKey,
                     operations: store,
                     saveToRenderer: true,
-                    withConnection: async (invocation, action) => {
-                        invocation.signal.throwIfAborted();
+                    withConnection: (invocation, action) => sceneAccess.run(invocation.signal, async (signal, beginSettlement) => {
                         if (!api.isConnected)
                             throw new Error("The Kakapo connection was interrupted; reconnect before continuing");
-                        return action(api, () => { }, invocation);
-                    },
+                        return action(api, beginSettlement, { ...invocation, signal });
+                    }),
+                    acquireAccess: async () => sceneAccess.release,
                     assertEditable: () => {
                         if (!api.isConnected)
                             throw new Error("The Kakapo connection is unavailable");
@@ -103,16 +102,11 @@ export async function createStandaloneSparkAgentApp(options) {
                 const sceneHost = createSdkSceneHost({
                     ...editorOptions,
                     editor,
-                    health: createSdkSceneHealthHost(editor, onHealth),
-                    onSceneCommitted: async (_operation, api) => {
-                        const sceneHealth = await readStableSdkSceneHealth(api, getSdkSceneAreaIds(api), context.signal);
-                        onHealth(sceneHealth);
-                        return { sceneHealth };
-                    },
+                    health: createSdkSceneHealthHost(editor, onHealth, repairs),
                     services: async () => services,
                     screenshot: async (settings, invocation) => {
                         invocation.signal.throwIfAborted();
-                        const image = await captureSdkSceneScreenshot(api, settings);
+                        const image = await editor.withConnection(invocation, activeApi => captureSdkSceneScreenshot(activeApi, settings));
                         options.onScreenshot?.(context.runId);
                         invocation.signal.throwIfAborted();
                         return artifactStore.write(context.ownerId, image);
@@ -254,8 +248,19 @@ export async function createStandaloneSparkAgentApp(options) {
         clearingScene = true;
         const api = new KakapoAPI({ url: options.kakapoUrl, requestTimeoutMs: 30_000 });
         try {
-            await api.connect();
-            const { save } = await api.editSceneAndSave(clearSceneContents);
+            await api.connect({ refreshScene: false });
+            const { save } = await sceneAccess.run(new AbortController().signal, async () => {
+                try {
+                    const result = await api.accessScene(clearSceneContents, { save: true });
+                    sceneAccess.release(result.save.status !== "unknown");
+                    return result;
+                }
+                catch (error) {
+                    if (error instanceof KakapoSceneCommitError && error.outcome === "unknown")
+                        sceneAccess.release(false);
+                    throw error;
+                }
+            });
             const warning = save.status === "failed" || save.status === "unknown"
                 ? `Scene cleared, but saving ${save.status === "failed" ? "failed" : "could not be confirmed"}: ${save.error} Do not repeat the clear operation.`
                 : undefined;

package/dist/womp-scene-api.d.ts

@@ -306,5 +306,20 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
         g: number;
         b: number;
     }) => void;
+    unitMultiplier: number;
+    /** Current draft summaries. Filters precede pagination; defaults to 100 results, maximum 1000. */
+    nodes(options?: {
+        ids?: number[];
+        type?: number;
+        parentId?: number;
+        name?: string;
+        offset?: number;
+        limit?: number;
+    }): {
+        id: number;
+        name: string;
+        type: number;
+        parentId: number;
+    }[];
 };
 export {};

package/dist/womp-scene-api.js

@@ -436,6 +436,23 @@ export function createWompSceneApi(context) {
         return converted;
     };
     const api = {
+        get unitMultiplier() {
+            return sceneUnitMultiplier(scene.getSceneProperties().unit_multiplier);
+        },
+        /** Current draft summaries. Filters precede pagination; defaults to 100 results, maximum 1000. */
+        nodes(options = {}) {
+            const { offset = 0, limit = 100 } = options;
+            if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+                throw new Error("nodes() requires a nonnegative integer offset and a limit from 1 to 1000");
+            const ids = options.ids === undefined ? undefined : new Set(options.ids);
+            const query = options.name?.toLowerCase();
+            return scene.listNodeSummaries().filter(({ id, name, kind, parentId }) => (ids === undefined || ids.has(id)) &&
+                (options.type === undefined || sceneNodeType(kind) === options.type) &&
+                (options.parentId === undefined || (parentId ?? 0) === options.parentId) &&
+                (query === undefined || name.toLowerCase().includes(query))).slice(offset, offset + limit).map(({ id, name, kind, parentId }) => ({
+                id, name, type: sceneNodeType(kind), parentId: parentId ?? 0,
+            }));
+        },
         ...createSceneEnvironment(scene, context.hdrs, context.print),
         listSuperMaterials: () => {
             if (!context.superMaterialNames)
@@ -611,7 +628,7 @@ export function createWompSceneApi(context) {
         nodeSetLock: (id, locked) => {
             requireNode(id);
             const current = metadataObject(scene.getSceneExt([String(id)])[String(id)]);
-            scene.patchSceneExt([{ op: "add", path: `/${id}`, value: { ...current, locked: Boolean(locked) } }]);
+            scene.patchSceneExt([{ op: "add", path: `/${id}`, value: { ...current, locked: Boolean(locked) } }], { returnScene: false });
         },
         nodeSetPos: (id, position) => {
             requireEditableTransform(id);

package/package.json

@@ -1,139 +1,139 @@
-{
-  "name": "@womp/spark-agent",
-  "version": "4.4.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",
-    "simple-bench": "dist/simple-bench-cli.js",
-    "agent-run": "dist/agent-run-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",
-    "simple-bench": "tsx src/simple-bench-cli.ts",
-    "agent-run": "tsx src/agent-run-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.6.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": "5.0.0",
+  "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",
+    "simple-bench": "dist/simple-bench-cli.js",
+    "agent-run": "dist/agent-run-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",
+    "simple-bench": "tsx src/simple-bench-cli.ts",
+    "agent-run": "tsx src/agent-run-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.7.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"
+  }
+}

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

@@ -1,3 +0,0 @@
-import { type KakapoAPI } from "@womp/kakapo-sdk";
-/** Only for the standalone host's direct, atomic native Kakapo connection. */
-export declare function initializeStandaloneScene(api: Pick<KakapoAPI, "rpc" | "refreshScene">, signal: AbortSignal): Promise<void>;

package/dist/server/scene-initialization.js

@@ -1,44 +0,0 @@
-import { KakapoSceneCommitError } from "@womp/kakapo-sdk";
-/** Only for the standalone host's direct, atomic native Kakapo connection. */
-export async function initializeStandaloneScene(api, signal) {
-    signal.throwIfAborted();
-    const response = await api.rpc("scene_state_get");
-    signal.throwIfAborted();
-    const snapshot = typeof response === "string" ? JSON.parse(response) : response;
-    if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) {
-        throw new Error("Kakapo returned an invalid scene snapshot during scene initialization.");
-    }
-    const additions = [];
-    if (snapshot.ext === undefined)
-        additions.push({ op: "add", path: "/ext", value: {} });
-    for (const key of ["materials", "shaders"]) {
-        if (snapshot.storage[key] === undefined) {
-            additions.push({ op: "add", path: `/storage/${key}`, value: {} });
-        }
-    }
-    if (snapshot.storage.openscad === undefined) {
-        additions.push({ op: "add", path: "/storage/openscad", value: { scripts: {} } });
-    }
-    else if (snapshot.storage.openscad.scripts === undefined) {
-        additions.push({ op: "add", path: "/storage/openscad/scripts", value: {} });
-    }
-    if (additions.length === 0)
-        return;
-    // The SDK requires /ext; native resource updates require per-ID patch paths.
-    // Initialize missing collections so later edits address individual resources.
-    // The whole-scene test rejects concurrent changes before editing begins.
-    let result;
-    try {
-        result = await api.rpc("scene_state_patch", [JSON.stringify([
-                { op: "test", path: "", value: snapshot },
-                ...additions,
-            ])]);
-    }
-    catch (error) {
-        throw new KakapoSceneCommitError("unknown", error);
-    }
-    if (result !== undefined && result !== null && result !== "") {
-        throw new KakapoSceneCommitError("unknown", new Error(`Scene initialization was not acknowledged: ${JSON.stringify(result)}`));
-    }
-    await api.refreshScene();
-}