@womp/spark-agent 8.0.0 → 9.0.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ Notable changes to `@womp/spark-agent`, newest first. Versions follow
 [Semantic Versioning](https://semver.org/). Add an entry with each version bump; describe what
 changed for hosts and users, and how to migrate across breaking changes.
 
+## 9.0.0 — 2026-10-12
+
+The scene operation journal is gone: every SDK scene adapter applies each edit directly to the
+scene and saves it, as the browser has since it moved to scene events. The journal only deduped an
+edit whose tool call ran again with the same operation id and settled uncertain edits that turned
+out to change nothing; no host re-runs a tool call within a live run, and a restart ends the run.
+
+### Removed
+
+- `SceneOperationStore`, `recoverSceneOperation` and the `operations` option of
+  `SdkSceneEditorOptions` (and so of `createSdkSceneEditor` and `createSdkSceneHost`).
+- `SdkSceneEditor.getOperation`.
+- `SceneOperation.revision`, which only versioned journal records.
+- `executeSceneOperation`'s `store` option and the `reused` flag on its result.
+- The standalone SQLite store's `scene_operations` table. Opening an older database drops it and
+  sets the schema version to 5.
+
+### Changed
+
+- Every edit that fails after it began throws `SceneOperationError`, whose `operation` reports
+  whether it was committed, rolled back or left uncertain. Before, hosts that supplied
+  `operations` got the original error unwrapped; it is now the error's `cause`.
+- Receipts no longer carry `details.synchronized`; `details.synchronizationError` still reports
+  a failed `onCommitted`.
+
+### Migrating
+
+Stop passing `operations` and delete any `SceneOperationStore` implementation. A custom
+`SdkSceneEditor` drops `getOperation`. Code that read an edit's outcome from the journal after a
+failure reads `error.operation` from the `SceneOperationError` instead.
+
 ## 8.0.0 — 2026-10-12
 
 Geometry Nodes moves to FlowIR 0.5.0. The dialect is FlowIR's strict, flat format, the

package/README.md

@@ -59,8 +59,9 @@ locks. The run stays active with `requires_action` progress and resumes the same
 input; the wait is excluded from the execution budget. Abort settles the wait and late answers
 cannot revive it. Custom executors must honor the optional host-owned `userWait` argument to `execute`.
 
-Shared SDK scene adapters may omit `operations` to edit and save directly. Supplying `operations`
-adds a durable operation journal and recovery of uncertain edits.
+Shared SDK scene adapters apply each edit directly to the scene and save it; nothing is journaled
+or replayed. An edit that fails after it began throws `SceneOperationError`, whose `operation`
+reports whether the edit was committed, rolled back or left uncertain.
 
 ### Persistence and run lifecycle
 

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { applyCompaction, latestCompaction, type SparkCompactionLimits } from ".
 export * from "./context-window.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, type SdkSceneEditor, type SdkSceneEditorOptions, type SdkSceneEditIdentity, type SdkSceneServices, } from "./sdk-scene-host.js";
-export { recoverSceneOperation, type SceneOperation, type SceneOperationStore } from "./scene-operations.js";
+export type { SceneOperation } from "./scene-operations.js";
 export type { JavaScriptExecutor, JavaScriptGlobals, JavaScriptUserWait } from "./executor.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export type { ModelProvider, ReasoningEffort, SparkModel } from "./models.js";

package/dist/index.js

@@ -5,6 +5,5 @@ export { applyCompaction, latestCompaction } from "./compaction.js";
 export * from "./context-window.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, } from "./sdk-scene-host.js";
-export { recoverSceneOperation } from "./scene-operations.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export { SPARK_AGENT_PROMPT, sparkSystemPrompt } from "./prompt.js";

package/dist/kakapo.d.ts

@@ -1,6 +1,6 @@
 export { KakapoRuntime } from "./runtime.js";
 export { createSdkSceneDraft, createSdkSceneEditor, createSdkSceneHost, type SdkSceneEditor, type SdkSceneEditorOptions, type SdkSceneEditIdentity, type SdkSceneServices, } from "./sdk-scene-host.js";
-export type { SceneOperation, SceneOperationStore, } from "./scene-operations.js";
+export type { SceneOperation } from "./scene-operations.js";
 export { createWompSceneApi, NodeType, OperationType, PrimitiveTypeValue, } from "./womp-scene-api.js";
 export type { WompSceneApi, WompSceneApiContext } from "./womp-scene-api.js";
 export { createSdkGeometryHost, type SdkGeometryHostOptions, } from "./sdk-geometry-host.js";

package/dist/scene-operations.d.ts

@@ -4,10 +4,10 @@ export type SceneEditResult = {
 } | {
     empty: true;
 };
+/** One scene edit's outcome, held for the invocation that made it. */
 export type SceneOperation = {
     id: string;
     targetKey: string;
-    revision: number;
     status: "started" | "prepared" | "committed" | "rolled_back" | "unknown";
     result?: SceneEditResult;
     changed?: boolean;
@@ -17,23 +17,9 @@ export type SceneOperation = {
     };
     completedAt?: string;
 };
-export interface SceneOperationStore {
-    getSceneOperation(targetKey: string, id: string): Promise<SceneOperation | undefined>;
-    createSceneOperation(operation: SceneOperation): Promise<boolean>;
-    saveSceneOperation(operation: SceneOperation): Promise<SceneOperation>;
-}
-/** Recover acknowledged/no-op results without replaying or refetching an uncertain edit. */
-export declare function recoverSceneOperation(options: {
-    api: KakapoAPI;
-    store: SceneOperationStore;
-    targetKey: string;
-    id: string;
-    assertActive(): void | Promise<void>;
-}): Promise<SceneOperation | undefined>;
-/** Hosts may omit persistence; journal-backed hosts retain duplicate-operation protection. */
+/** Applies one edit directly to the scene and reports its outcome; nothing is journaled or replayed. */
 export declare function executeSceneOperation<T>(options: {
     api: KakapoAPI;
-    store?: SceneOperationStore;
     onOutcome?(operation: SceneOperation): void;
     operation: Pick<SceneOperation, "id" | "targetKey">;
     assertEditable(): void | Promise<void>;
@@ -44,5 +30,4 @@ export declare function executeSceneOperation<T>(options: {
 }): Promise<{
     value: T;
     operation: SceneOperation;
-    reused?: boolean;
 }>;

package/dist/scene-operations.js

@@ -42,44 +42,15 @@ function resultValue(operation) {
 function complete(operation, status) {
     return { ...operation, status, completedAt: operation.completedAt ?? new Date().toISOString() };
 }
-/** Recover acknowledged/no-op results without replaying or refetching an uncertain edit. */
-export async function recoverSceneOperation(options) {
-    await options.assertActive();
-    const previous = await options.store.getSceneOperation(options.targetKey, options.id);
-    if (!previous || previous.status === "committed" || previous.status === "rolled_back")
-        return previous;
-    await options.assertActive();
-    if (previous.changed === false && previous.result) {
-        return options.store.saveSceneOperation(complete(previous, "committed"));
-    }
-    return previous;
-}
-/** Hosts may omit persistence; journal-backed hosts retain duplicate-operation protection. */
+/** Applies one edit directly to the scene and reports its outcome; nothing is journaled or replayed. */
 export async function executeSceneOperation(options) {
-    const { api, store, operation: identity } = options;
+    const { api, operation: identity } = options;
     const savesScene = options.saveToRenderer === true;
     await options.assertEditable();
-    const previous = await store?.getSceneOperation(identity.targetKey, identity.id);
-    if (previous && store) {
-        if ((previous.save !== undefined) !== savesScene)
-            throw new Error("Scene operation identity was reused with a different save policy");
-        if (previous.status === "committed")
-            return { value: resultValue(previous), operation: previous, reused: true };
-        if (previous.status === "rolled_back")
-            throw new Error(previous.error ?? "Scene operation was rolled back");
-        const recovered = await recoverSceneOperation({
-            api, store, targetKey: identity.targetKey, id: identity.id, assertActive: options.assertEditable,
-        });
-        if (recovered?.status === "committed")
-            return { value: resultValue(recovered), operation: recovered, reused: true };
-        throw new Error("Scene edit outcome is uncertain. Inspect the scene before making a new edit; this operation was not replayed.");
-    }
     let operation = {
-        ...identity, revision: 0, status: "started",
+        ...identity, status: "started",
         ...(savesScene ? { save: { status: "unknown" } } : {}),
     };
-    if (store && !await store.createSceneOperation(operation))
-        throw new Error("Scene operation is already in progress");
     try {
         const edit = async (draft) => {
             await options.assertEditable();
@@ -94,8 +65,6 @@ export async function executeSceneOperation(options) {
                     ...operation, status: "prepared", changed,
                     ...(savesScene && !changed ? { save: { status: "not_needed" } } : {}),
                 };
-                if (store)
-                    operation = await store.saveSceneOperation(operation);
                 await options.assertEditable();
                 if (changed)
                     await options.prepareCommit?.(operation);
@@ -118,16 +87,11 @@ export async function executeSceneOperation(options) {
                 ...(operation.save && status === "rolled_back" ? { save: { status: "not_needed" } } : {}),
             };
             options.onOutcome?.(operation);
-            if (store)
-                operation = await store.saveSceneOperation(operation);
         }
         catch {
-            // Keep the original error; recovery can inspect the prepared record.
+            // Keep the original error.
         }
         throw error;
     }
-    // A prepared record alone never proves an uncertain commit succeeded.
-    if (store)
-        operation = await store.saveSceneOperation(complete(operation, "committed"));
     return { value: resultValue(operation), operation };
 }

package/dist/sdk-geometry-host.js

@@ -246,8 +246,7 @@ export function createSdkGeometryHost(options) {
             }
             catch (error) {
                 if (operationId !== undefined && repairKey !== undefined) {
-                    const operation = error instanceof SceneOperationError ? error.operation : await editor.getOperation(operationId);
-                    if (operation?.status === "rolled_back")
+                    if (error instanceof SceneOperationError && error.operation.status === "rolled_back")
                         await repairs.refund(repairKey, operationId);
                 }
                 throw error;

package/dist/sdk-openscad-host.js

@@ -238,9 +238,7 @@ export function createSdkOpenScadHost(options) {
         }
         catch (error) {
             if (creating === false && operationId !== "") {
-                const operation = error instanceof SceneOperationError
-                    ? error.operation : await editor.getOperation(operationId);
-                if (operation?.status === "rolled_back") {
+                if (error instanceof SceneOperationError && error.operation.status === "rolled_back") {
                     await geometryRepairs.refund(resolved.repairKey, operationId);
                     await printabilityRepairs.refund(resolved.repairKey, operationId);
                 }

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

@@ -1,7 +1,7 @@
 import type { FontFamily, KakapoAPI, SceneEdit, MaterialResource, NativeSceneSnapshot } from "@womp/kakapo-sdk";
 import type { ArtifactRef, SparkInvocationContext } from "./capabilities.js";
 import type { SceneHost, SceneHealthHost, SceneScreenshotOptions } from "./capabilities/scene.js";
-import { type SceneOperation, type SceneOperationStore } from "./scene-operations.js";
+import { type SceneOperation } from "./scene-operations.js";
 import type { SceneHdr } from "./scene-environment.js";
 export type SdkSceneServices = {
     fonts: FontFamily[];
@@ -19,7 +19,6 @@ export type SdkSceneServices = {
 export type SdkSceneEditorOptions = {
     targetKey: string;
     projectId?: number;
-    operations?: SceneOperationStore;
     saveToRenderer?: boolean;
     withConnection<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void, 
     /** Supply this when the host adds a stricter connection lifetime. */
@@ -27,7 +26,7 @@ export type SdkSceneEditorOptions = {
     assertEditable(context: SparkInvocationContext): void | Promise<void>;
     /** Suspend for the complete access, including reads and failed preparation. */
     acquireAccess?(context: SparkInvocationContext): Promise<(synchronized: boolean) => void | Promise<void>>;
-    /** Must adopt each operation ID at most once, including during recovery. */
+    /** Must adopt each operation ID at most once. */
     onCommitted?(operation: SceneOperation, api: KakapoAPI, context: SparkInvocationContext, identity: SdkSceneEditIdentity, scene: NativeSceneSnapshot): Promise<Record<string, unknown> | void>;
 };
 export type SdkSceneEditIdentity = {
@@ -35,13 +34,12 @@ export type SdkSceneEditIdentity = {
     operation: string;
     target?: Record<string, unknown> | (() => Record<string, unknown>);
 };
-/** Carries this invocation's outcome without requiring a persistent journal. */
+/** A failed edit's outcome, for callers that settle per-edit state such as repair budgets. */
 export declare class SceneOperationError extends Error {
     readonly operation: SceneOperation;
     constructor(operation: SceneOperation, cause: unknown);
 }
 export type SdkSceneEditor = {
-    getOperation(operationId: string): Promise<SceneOperation | undefined>;
     withConnection<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void) => T | Promise<T>): Promise<T>;
     read<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void) => T | Promise<T>): Promise<T>;
     access<T>(identity: SdkSceneEditIdentity, callback: (api: KakapoAPI, draft: SceneEdit, operationId: string) => T | Promise<T>, context: SparkInvocationContext, afterCommitted?: (operation: SceneOperation, api: KakapoAPI) => Promise<Record<string, unknown> | void>): Promise<{

package/dist/sdk-scene-host.js

@@ -10,7 +10,7 @@ function assertSceneSaved(operation) {
     if (operation.save?.status === "unknown" || 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.");
 }
-/** Carries this invocation's outcome without requiring a persistent journal. */
+/** A failed edit's outcome, for callers that settle per-edit state such as repair budgets. */
 export class SceneOperationError extends Error {
     operation;
     constructor(operation, cause) {
@@ -74,7 +74,6 @@ export function createSdkSceneDraft(api, scene, services) {
 export function createSdkSceneEditor(options) {
     const ordinals = new WeakMap();
     return {
-        getOperation: (operationId) => options.operations?.getSceneOperation(options.targetKey, operationId) ?? Promise.resolve(undefined),
         withConnection: (context, action) => options.withConnection(context, async (api, settle, active = context) => {
             active.signal.throwIfAborted();
             return action(api, settle);
@@ -131,7 +130,6 @@ export function createSdkSceneEditor(options) {
                             result: operation.result,
                             save: operation.save,
                             error: operation.error,
-                            ...(options.operations ? { synchronized } : {}),
                         }),
                     });
                 };
@@ -142,7 +140,6 @@ export function createSdkSceneEditor(options) {
                     try {
                         result = await executeSceneOperation({
                             api,
-                            store: options.operations,
                             onOutcome: operation => { outcome = operation; },
                             saveToRenderer: options.saveToRenderer,
                             operation: {
@@ -168,10 +165,9 @@ export function createSdkSceneEditor(options) {
                     catch (error) {
                         // Receipt persistence must not replace the original SDK/tool error.
                         try {
-                            const operation = outcome ?? await options.operations?.getSceneOperation(options.targetKey, id);
-                            if (operation) {
-                                synchronized = operation.status === "rolled_back";
-                                await record(operation);
+                            if (outcome) {
+                                synchronized = outcome.status === "rolled_back";
+                                await record(outcome);
                             }
                         }
                         catch {
@@ -180,12 +176,6 @@ export function createSdkSceneEditor(options) {
                         throw error;
                     }
                     saveSettled = !result.operation.changed || !["unknown", "requested"].includes(result.operation.save?.status ?? "");
-                    // A duplicate returns its journaled result; retain its original receipt
-                    // and let explicit recovery handle any earlier synchronization failure.
-                    if (result.reused) {
-                        assertSceneSaved(result.operation);
-                        return result;
-                    }
                     synchronized = !result.operation.changed || !options.onCommitted;
                     await record(result.operation);
                     if (!synchronized) {
@@ -216,7 +206,7 @@ export function createSdkSceneEditor(options) {
                     return result;
                 }
                 catch (error) {
-                    if (!options.operations && outcome)
+                    if (outcome)
                         throw new SceneOperationError(outcome, error);
                     throw error;
                 }

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

@@ -2,11 +2,10 @@ import type { SparkGoal } from "../goals.js";
 import type { ExecutionScreenshot } from "../types.js";
 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, SparkRunSettings } from "./types.js";
 /** Local development storage. Execution ownership belongs to the host service. */
-export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactStore, SceneOperationStore {
+export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactStore {
     private readonly artifactBaseUrl;
     private readonly database;
     private ownershipToken;
@@ -15,9 +14,6 @@ export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactS
     close(): void;
     claimExecutionOwnership(): void;
     listInterruptedRuns(): Promise<SparkRun[]>;
-    getSceneOperation(targetKey: string, id: string): Promise<SceneOperation | undefined>;
-    createSceneOperation(operation: SceneOperation): Promise<boolean>;
-    saveSceneOperation(operation: SceneOperation): Promise<SceneOperation>;
     createConversation(value: SparkConversation): Promise<void>;
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;

package/dist/server/sqlite-store.js

@@ -2,7 +2,6 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { emptyRepairState, } from "../repair-state.js";
-const completedSceneOperationLimit = 128;
 /** Local development storage. Execution ownership belongs to the host service. */
 export class SqliteSparkStore {
     artifactBaseUrl;
@@ -13,7 +12,7 @@ export class SqliteSparkStore {
         mkdirSync(dirname(path), { recursive: true });
         this.database = new DatabaseSync(path);
         const version = this.database.prepare("PRAGMA user_version").get()?.user_version;
-        if (version !== 0 && version !== 1 && version !== 2 && version !== 3 && version !== 4) {
+        if (version !== 0 && version !== 1 && version !== 2 && version !== 3 && version !== 4 && version !== 5) {
             this.database.close();
             throw new Error(`Unsupported Spark database version: ${version}`);
         }
@@ -39,14 +38,11 @@ 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)
-      );
+      DROP TABLE IF EXISTS scene_operations;
       CREATE TABLE IF NOT EXISTS repair_states (
         target_key TEXT PRIMARY KEY, revision INTEGER NOT NULL, data TEXT NOT NULL
       );
-      PRAGMA user_version = 4;
+      PRAGMA user_version = 5;
     `);
     }
     repairStateStore(targetKey) {
@@ -111,39 +107,6 @@ export class SqliteSparkStore {
             throw new Error("Claim execution ownership before recovering runs");
         return this.database.prepare("SELECT data FROM runs WHERE json_extract(data, '$.status') IN ('queued', 'running')").all().map((row) => JSON.parse(String(row.data)));
     }
-    async getSceneOperation(targetKey, id) {
-        const row = this.database.prepare("SELECT data FROM scene_operations WHERE target_key = ? AND id = ?").get(targetKey, id);
-        return row ? JSON.parse(String(row.data)) : undefined;
-    }
-    async createSceneOperation(operation) {
-        const result = this.database.prepare("INSERT OR IGNORE INTO scene_operations VALUES (?, ?, ?, ?)").run(operation.targetKey, operation.id, operation.revision, JSON.stringify(operation));
-        return result.changes === 1;
-    }
-    async saveSceneOperation(operation) {
-        const next = { ...operation, revision: operation.revision + 1 };
-        this.database.exec("BEGIN IMMEDIATE");
-        try {
-            const result = this.database.prepare("UPDATE scene_operations SET revision = ?, data = ? WHERE target_key = ? AND id = ? AND revision = ?").run(next.revision, JSON.stringify(next), operation.targetKey, operation.id, operation.revision);
-            if (result.changes !== 1)
-                throw new Error("Scene operation changed concurrently or is missing");
-            if (next.status === "committed" || next.status === "rolled_back") {
-                this.database.prepare(`
-          DELETE FROM scene_operations WHERE rowid IN (
-            SELECT rowid FROM scene_operations
-            WHERE target_key = ? AND json_extract(data, '$.status') IN ('committed', 'rolled_back')
-            ORDER BY COALESCE(json_extract(data, '$.completedAt'), '') DESC
-            LIMIT -1 OFFSET ?
-          )
-        `).run(next.targetKey, completedSceneOperationLimit);
-            }
-            this.database.exec("COMMIT");
-            return next;
-        }
-        catch (error) {
-            this.database.exec("ROLLBACK");
-            throw error;
-        }
-    }
     async createConversation(value) {
         this.database.prepare("INSERT INTO conversations VALUES (?, ?, ?, ?)")
             .run(value.id, value.ownerId, value.updatedAt, JSON.stringify(value));

package/dist/server/standalone.js

@@ -102,7 +102,6 @@ export async function createStandaloneSparkAgentApp(options) {
                 const targetKey = `${context.ownerId}:${sceneIdentity}`;
                 const editorOptions = {
                     targetKey,
-                    operations: store,
                     saveToRenderer: true,
                     withConnection: (invocation, action) => sceneAccess.run(invocation.signal, async (signal, beginSettlement) => {
                         if (!api.isConnected)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",