@womp/spark-agent 4.4.1 → 5.0.0

package/dist/runtime.js

@@ -46,7 +46,7 @@ export class KakapoRuntime {
         this.eventSink(event);
     }
     async connect() {
-        await this.sdkCall("connect", [], () => this.api.connect());
+        await this.sdkCall("connect", [], () => this.api.connect({ refreshScene: false }));
         this.fonts = await this.sdkCall("listFonts", [], () => this.api.listFonts());
         this.rootId = 0;
     }
@@ -135,31 +135,25 @@ export class KakapoRuntime {
             print,
         });
     }
-    async inspect() {
-        await this.api.refreshScene();
-        return { revision: await this.api.getSceneRevision(), scene: this.api.getScene() };
-    }
-    async edit(callback, expectedRevision, context) {
+    async access(callback, context) {
         let changed = false;
         const ordinal = this.editOrdinals.get(context) ?? 0;
         this.editOrdinals.set(context, ordinal + 1);
         const receipt = {
-            id: `${context.runId}:${context.toolCallId}:scene.edit:${ordinal}`,
+            id: `${context.runId}:${context.toolCallId}:scene.access:${ordinal}`,
             capability: "scene",
-            operation: "edit",
+            operation: "access",
         };
         let value;
         try {
-            value = await this.api.editScene(async (scene) => {
+            const accessed = await this.api.accessScene(async (scene) => {
                 context.signal.throwIfAborted();
-                if ((await this.api.getSceneRevision()) !== expectedRevision) {
-                    throw new Error("Scene changed since inspection. Read the scene again before editing.");
-                }
                 const result = await callback(this.sceneApi(scene, () => undefined));
                 context.signal.throwIfAborted();
-                changed = (await this.api.getSceneRevision()) !== expectedRevision;
                 return result;
             });
+            value = accessed.value;
+            changed = accessed.changed;
         }
         catch (error) {
             await context.recordReceipt({
@@ -191,7 +185,7 @@ export class KakapoRuntime {
             error: (...values) => consoleFacade.log("ERROR", ...values),
         };
         try {
-            const value = await this.api.editScene((scene) => {
+            const { value } = await this.api.accessScene((scene) => {
                 const api = this.sceneApi(scene, (...values) => consoleFacade.log(...values));
                 return this.executor.execute(code, { ...api, console: consoleFacade }, 60_000);
             });

package/dist/scene-environment.js

@@ -32,7 +32,7 @@ export function createSceneEnvironment(scene, hdrs, print) {
             op: "add",
             path: `/${key}`,
             value,
-        })));
+        })), { returnScene: false });
     };
     return {
         scenePropertiesRead: () => {

package/dist/scene-health.d.ts

@@ -63,10 +63,9 @@ export declare function receiptSceneHealth(health: SceneHealth, limit?: number):
  * changes the one payload that is unbounded by construction and nothing else.
  */
 export declare function boundedReceiptDetails(details: Record<string, unknown>): Record<string, unknown>;
-export declare function getSdkSceneAreaId(api: KakapoAPI, objectId: number): string;
+export declare function getSdkSceneAreaId(api: Pick<KakapoAPI, "getNode">, objectId: number): string;
 export declare function getSdkSceneAreaIds(api: KakapoAPI): string[];
 export declare function hasGeometryOverflow(health: SceneHealth): boolean;
 export declare function hasSceneResourcePressure(health: SceneHealth): boolean;
 export declare function parseSceneHealth(response: unknown, affectedAreaIds: string[]): SceneHealth;
 export declare function readSdkSceneHealth(api: KakapoAPI, affectedAreaIds: string[], signal?: AbortSignal): Promise<SceneHealth>;
-export declare function readStableSdkSceneHealth(api: KakapoAPI, affectedAreaIds: string[], signal?: AbortSignal): Promise<SceneHealth>;

package/dist/scene-health.js

@@ -236,20 +236,3 @@ export async function readSdkSceneHealth(api, affectedAreaIds, signal) {
         removeAbortListener?.();
     }
 }
-export async function readStableSdkSceneHealth(api, affectedAreaIds, signal) {
-    try {
-        signal?.throwIfAborted();
-        const before = await api.getSceneRevision();
-        const health = await readSdkSceneHealth(api, affectedAreaIds, signal);
-        signal?.throwIfAborted();
-        await api.refreshScene();
-        signal?.throwIfAborted();
-        const after = await api.getSceneRevision();
-        if (before === after)
-            return health;
-        return unverifiedSceneHealth(affectedAreaIds, "The scene changed while reading its health.");
-    }
-    catch (error) {
-        return unverifiedSceneHealth(affectedAreaIds, String(error));
-    }
-}

package/dist/scene-operations.d.ts

@@ -1,4 +1,4 @@
-import { type JsonValue, type KakapoAPI, type SceneEdit, type SceneSaveResult } from "@womp/kakapo-sdk";
+import { type JsonValue, type KakapoAPI, type NativeSceneSnapshot, type SceneEdit, type SceneSaveResult } from "@womp/kakapo-sdk";
 export type SceneEditResult = {
     value: JsonValue;
 } | {
@@ -7,8 +7,6 @@ export type SceneEditResult = {
 export type SceneOperation = {
     id: string;
     targetKey: string;
-    expectedRevision: string;
-    resultRevision?: string;
     revision: number;
     status: "started" | "prepared" | "committed" | "rolled_back" | "unknown";
     result?: SceneEditResult;
@@ -24,7 +22,7 @@ export interface SceneOperationStore {
     createSceneOperation(operation: SceneOperation): Promise<boolean>;
     saveSceneOperation(operation: SceneOperation): Promise<SceneOperation>;
 }
-/** Resolve a journaled edit from a fresh renderer snapshot without executing its JavaScript. */
+/** Recover acknowledged/no-op results without replaying or refetching an uncertain edit. */
 export declare function recoverSceneOperation(options: {
     api: KakapoAPI;
     store: SceneOperationStore;
@@ -36,12 +34,14 @@ export declare function recoverSceneOperation(options: {
 export declare function executeSceneOperation<T>(options: {
     api: KakapoAPI;
     store: SceneOperationStore;
-    operation: Pick<SceneOperation, "id" | "targetKey" | "expectedRevision">;
+    operation: Pick<SceneOperation, "id" | "targetKey">;
     assertEditable(): void | Promise<void>;
     edit(draft: SceneEdit): T | Promise<T>;
     prepareCommit?(operation: SceneOperation): Promise<void>;
+    onCommittedScene?(scene: NativeSceneSnapshot): void;
     saveToRenderer?: boolean;
 }): Promise<{
     value: T;
     operation: SceneOperation;
+    reused?: boolean;
 }>;

package/dist/scene-operations.js

@@ -1,5 +1,4 @@
 import { KakapoSceneCommitError } from "@womp/kakapo-sdk";
-import { metadataObject } from "./scene-metadata.js";
 function savedResult(value) {
     if (value === undefined)
         return { empty: true };
@@ -11,9 +10,9 @@ function savedResult(value) {
             return;
         if (typeof item !== "object" || item === null ||
             (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null))
-            throw new Error("scene.edit must return JSON data or undefined");
+            throw new Error("scene.access must return JSON data or undefined");
         if (active.has(item))
-            throw new Error("scene.edit cannot return cyclic data");
+            throw new Error("scene.access cannot return cyclic data");
         active.add(item);
         for (const nested of Object.values(item))
             validate(nested);
@@ -27,26 +26,17 @@ function resultValue(operation) {
         throw new Error("The saved scene operation result is missing");
     return ("value" in operation.result ? structuredClone(operation.result.value) : undefined);
 }
-function committedIds(ext) {
-    const ids = metadataObject(ext.spark).committedSceneEdits;
-    return Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
-}
 function complete(operation, status) {
     return { ...operation, status, completedAt: operation.completedAt ?? new Date().toISOString() };
 }
-/** Resolve a journaled edit from a fresh renderer snapshot without executing its JavaScript. */
+/** 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.api.refreshScene();
-    const ext = options.api.getSceneExt();
-    const revision = await options.api.getSceneRevision();
     await options.assertActive();
-    const matches = previous.resultRevision !== undefined &&
-        previous.resultRevision === revision && committedIds(ext).includes(previous.id);
-    if ((previous.changed === false || matches) && previous.result) {
+    if (previous.changed === false && previous.result) {
         return options.store.saveSceneOperation(complete(previous, "committed"));
     }
     return previous;
@@ -58,19 +48,17 @@ export async function executeSceneOperation(options) {
     await options.assertEditable();
     const previous = await store.getSceneOperation(identity.targetKey, identity.id);
     if (previous) {
-        if (previous.expectedRevision !== identity.expectedRevision)
-            throw new Error("Scene operation identity was reused with a different revision");
         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 };
+            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 };
+            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 = {
@@ -82,33 +70,26 @@ export async function executeSceneOperation(options) {
     try {
         const edit = async (draft) => {
             await options.assertEditable();
-            if (await api.getSceneRevision() !== identity.expectedRevision)
-                throw new Error("Scene changed since inspection. Read the scene again before editing.");
-            const result = savedResult(await options.edit(draft));
-            await options.assertEditable();
-            const changed = await api.getSceneRevision() !== identity.expectedRevision;
-            if (changed) {
-                const spark = metadataObject(draft.getSceneExt().spark);
-                const ids = [...committedIds(api.getSceneExt()), identity.id].slice(-64);
-                draft.patchSceneExt([{ op: "add", path: "/spark", value: { ...spark, committedSceneEdits: ids } }]);
-            }
-            operation = await store.saveSceneOperation({
-                ...operation, status: "prepared", result, changed,
-                ...(changed ? { resultRevision: await api.getSceneRevision() } : {}),
-                ...(savesScene && !changed ? { save: { status: "not_needed" } } : {}),
-            });
-            await options.assertEditable();
-            if (changed)
-                await options.prepareCommit?.(operation);
+            operation = { ...operation, result: savedResult(await options.edit(draft)) };
             await options.assertEditable();
         };
-        if (options.saveToRenderer) {
-            const committed = await api.editSceneAndSave(edit);
+        const committed = await api.accessScene(edit, {
+            save: savesScene,
+            beforeCommit: async (changed) => {
+                await options.assertEditable();
+                operation = await store.saveSceneOperation({
+                    ...operation, status: "prepared", changed,
+                    ...(savesScene && !changed ? { save: { status: "not_needed" } } : {}),
+                });
+                await options.assertEditable();
+                if (changed)
+                    await options.prepareCommit?.(operation);
+            },
+        });
+        if (savesScene)
             operation = { ...operation, save: committed.save };
-        }
-        else {
-            await api.editScene(edit);
-        }
+        if (committed.changed)
+            options.onCommittedScene?.(committed.scene);
     }
     catch (error) {
         const status = error instanceof KakapoSceneCommitError ? error.outcome
@@ -125,7 +106,7 @@ export async function executeSceneOperation(options) {
         }
         throw error;
     }
-    // Recovery requires both the operation marker and the exact prepared scene revision.
+    // A prepared record alone never proves an uncertain commit succeeded.
     operation = await store.saveSceneOperation(complete(operation, "committed"));
     return { value: resultValue(operation), operation };
 }

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

@@ -1,12 +1,12 @@
 import { type SdkSceneEditor } from "./sdk-scene-host.js";
 import type { GeometryHost } from "./capabilities.js";
-import { readStableSdkSceneHealth } from "./scene-health.js";
+import { readSdkSceneHealth } from "./scene-health.js";
 import { type RepairStateStore } from "./repair-state.js";
 export type SdkGeometryHostOptions = {
     editor: SdkSceneEditor;
     repairs: RepairStateStore;
     canGrow?: () => boolean;
-    onHealth?: (health: Awaited<ReturnType<typeof readStableSdkSceneHealth>>) => void;
+    onHealth?: (health: Awaited<ReturnType<typeof readSdkSceneHealth>>) => void;
     onSelect?: (objectId: number) => void | Promise<void>;
 };
 export declare function createSdkGeometryHost(options: SdkGeometryHostOptions): GeometryHost;

package/dist/sdk-geometry-host.js

@@ -2,7 +2,7 @@ import { compileGeometry, migrateGraphExt, readEditableGeometry, } from "./geome
 import { graphExtSchema } from "./geometry/graph.js";
 import { boundedDiagnostics } from "./geometry/diagnostics.js";
 import { migrateParameterOverrides, readParameterOverrides, } from "./geometry/parameters.js";
-import { getSdkSceneAreaId, readStableSdkSceneHealth } from "./scene-health.js";
+import { unverifiedSceneHealth } from "./scene-health.js";
 import { createGeometryRepairTracker, } from "./repair-state.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -57,7 +57,6 @@ async function readTarget(api, objectId, target = resolveTarget(api, objectId))
         instanceId: target.instanceId,
         source: null,
         instances: [],
-        revision: await api.getSceneRevision(),
         diagnostics: [],
     };
     if (target.graphId === undefined || target.graph === undefined)
@@ -93,7 +92,7 @@ function writeGraphStorage(draft, graphId, graph, instances) {
                 path: "/scripts",
                 value: { graphs: {}, instances: {} },
             },
-        ]);
+        ], { returnScene: false });
     }
     else {
         const record = scripts;
@@ -111,7 +110,7 @@ function writeGraphStorage(draft, graphId, graph, instances) {
                 value: {},
             });
         if (additions.length)
-            draft.patchSceneStorage(additions);
+            draft.patchSceneStorage(additions, { returnScene: false });
     }
     draft.patchSceneStorage([
         {
@@ -124,7 +123,7 @@ function writeGraphStorage(draft, graphId, graph, instances) {
             path: `/scripts/instances/${id}`,
             value: instance,
         })),
-    ]);
+    ], { returnScene: false });
 }
 export function createSdkGeometryHost(options) {
     const editor = options.editor;
@@ -134,17 +133,7 @@ export function createSdkGeometryHost(options) {
         read: (objectId, invocation) => editor.read(invocation, (api) => readTarget(api, objectId)),
         write: async (input, invocation) => {
             invocation.signal.throwIfAborted();
-            const inspected = await editor.read(invocation, async (api) => {
-                const current = resolveTarget(api, input.objectId);
-                return {
-                    target: await readTarget(api, input.objectId, current),
-                    current,
-                    graphExt: current.graphId === undefined
-                        ? undefined
-                        : api.getSceneExt().graphsExt?.[current.graphId],
-                };
-            });
-            const { target } = inspected;
+            const target = await editor.read(invocation, api => readTarget(api, input.objectId));
             const pendingKey = target.graphId === undefined
                 ? `object:${input.objectId}`
                 : `graph:${target.graphId}`;
@@ -152,8 +141,6 @@ export function createSdkGeometryHost(options) {
                 throw new Error("This Geometry Nodes target is still being updated. Await its current update first.");
             pendingTargets.add(pendingKey);
             try {
-                if (target.revision !== input.expectedRevision)
-                    throw new Error("The scene changed. Read it again before editing.");
                 const repairingGeometry = target.graphId !== undefined &&
                     (await repairs.isPending(String(target.graphId)));
                 if (target.graphId !== undefined)
@@ -164,39 +151,13 @@ export function createSdkGeometryHost(options) {
                     graphId: target.graphId,
                     instanceId: target.instanceId,
                     affectedObjectIds: [],
-                    revision: target.revision,
                     diagnostics: boundedDiagnostics(diagnostics),
                 });
                 let compiled;
-                let nextExt;
-                const updates = new Map();
                 const diagnostics = [];
                 try {
                     compiled = compileGeometry(input.source);
                     readEditableGeometry(compiled.graph, compiled.graphExt);
-                    if (target.graphId === undefined) {
-                        nextExt = migrateGraphExt({ nodes: {} }, {}, compiled);
-                    }
-                    else {
-                        const { current } = inspected;
-                        if (current.graph === undefined)
-                            throw new Error("The Geometry Nodes graph is missing.");
-                        const ext = graphExtSchema.parse(inspected.graphExt ?? {});
-                        const previous = readEditableGeometry(current.graph, ext);
-                        nextExt = migrateGraphExt(ext, previous.nodeIds, compiled);
-                        for (const [id, instance] of Object.entries(current.scripts.instances)) {
-                            if (instance.graph_id !== target.graphId)
-                                continue;
-                            const old = readParameterOverrides(previous.graph, ext, instance.data ?? {});
-                            const migrated = migrateParameterOverrides(previous.graph, ext, compiled.graph, nextExt, old.data);
-                            updates.set(id, {
-                                graph_id: target.graphId,
-                                data: migrated.data,
-                            });
-                            if (migrated.removed.length)
-                                diagnostics.push(`Instance ${id}: removed or type-changed overrides ${migrated.removed.join(", ")} now use graph defaults where present.`);
-                        }
-                    }
                 }
                 catch (error) {
                     return rejected([errorMessage(error)]);
@@ -209,7 +170,7 @@ export function createSdkGeometryHost(options) {
                 let operationId;
                 let applied;
                 try {
-                    applied = await editor.edit({
+                    applied = await editor.access({
                         capability: "geometry",
                         operation: "write",
                         target: () => receiptTarget,
@@ -220,6 +181,36 @@ export function createSdkGeometryHost(options) {
                             throw new Error("Scene memory limits prevent applying this graph.");
                         if (current.graphId !== target.graphId)
                             throw new Error("The Geometry Nodes target changed. Read it again.");
+                        let nextExt;
+                        const updates = new Map();
+                        try {
+                            if (target.graphId === undefined) {
+                                nextExt = migrateGraphExt({ nodes: {} }, {}, compiled);
+                            }
+                            else {
+                                if (current.graph === undefined)
+                                    throw new Error("The Geometry Nodes graph is missing.");
+                                const graphExt = draft.getSceneExt(["graphsExt"]).graphsExt;
+                                const ext = graphExtSchema.parse(graphExt?.[target.graphId] ?? {});
+                                const previous = readEditableGeometry(current.graph, ext);
+                                nextExt = migrateGraphExt(ext, previous.nodeIds, compiled);
+                                for (const [id, instance] of Object.entries(current.scripts.instances)) {
+                                    if (instance.graph_id !== target.graphId)
+                                        continue;
+                                    const old = readParameterOverrides(previous.graph, ext, instance.data ?? {});
+                                    const migrated = migrateParameterOverrides(previous.graph, ext, compiled.graph, nextExt, old.data);
+                                    updates.set(id, {
+                                        graph_id: target.graphId,
+                                        data: migrated.data,
+                                    });
+                                    if (migrated.removed.length)
+                                        diagnostics.push(`Instance ${id}: removed or type-changed overrides ${migrated.removed.join(", ")} now use graph defaults where present.`);
+                                }
+                            }
+                        }
+                        catch (error) {
+                            return { rejected: [errorMessage(error)] };
+                        }
                         if (current.graphId !== undefined)
                             await repairs.reserve(String(current.graphId), id);
                         let objectId = input.objectId;
@@ -247,34 +238,25 @@ export function createSdkGeometryHost(options) {
                         if (!ext.graphsExt)
                             draft.patchSceneExt([
                                 { op: "add", path: "/graphsExt", value: {} },
-                            ]);
+                            ], { returnScene: false });
                         draft.patchSceneExt([
                             {
                                 op: "add",
                                 path: `/graphsExt/${graphId}`,
                                 value: nextExt,
                             },
-                        ]);
+                        ], { returnScene: false });
                         const affectedObjectIds = Object.entries(scriptStorage(draft).instances)
                             .filter(([, instance]) => instance.graph_id === graphId)
                             .flatMap(([id]) => objectIdsFor(draft, Number(id)));
                         Object.assign(receiptTarget, { objectId, graphId, instanceId });
                         return { objectId, graphId, instanceId, affectedObjectIds };
-                    }, input.expectedRevision, invocation, async (_operation, api) => {
-                        const committed = resolveTarget(api, receiptTarget.objectId);
-                        if (committed.graphId === undefined)
+                    }, invocation, async (operation) => {
+                        const graphId = receiptTarget.graphId;
+                        if (graphId === undefined)
                             return;
-                        const affectedObjectIds = Object.entries(committed.scripts.instances)
-                            .filter(([, instance]) => instance.graph_id === committed.graphId)
-                            .flatMap(([id]) => objectIdsFor(api, Number(id)));
-                        const areaIds = [
-                            ...new Set(affectedObjectIds.map((id) => getSdkSceneAreaId(api, id))),
-                        ];
-                        const sceneHealth = await readStableSdkSceneHealth(api, areaIds, invocation.signal);
-                        options.onHealth?.(sceneHealth);
-                        const recorded = await repairs.record(String(committed.graphId), _operation.id, sceneHealth);
+                        const recorded = await repairs.record(String(graphId), operation.id, unverifiedSceneHealth([], "Health was not requested."));
                         return {
-                            sceneHealth,
                             geometryRepairAttempts: recorded.repairAttempts,
                             geometryRepairLimit: recorded.repairLimit,
                         };
@@ -288,6 +270,8 @@ export function createSdkGeometryHost(options) {
                     }
                     throw error;
                 }
+                if (applied.value.rejected)
+                    return rejected(applied.value.rejected);
                 invocation.signal.throwIfAborted();
                 try {
                     await options.onSelect?.(applied.value.objectId);
@@ -296,7 +280,6 @@ export function createSdkGeometryHost(options) {
                 return {
                     status: "applied",
                     ...applied.value,
-                    revision: applied.operation.resultRevision ?? input.expectedRevision,
                     diagnostics: boundedDiagnostics(diagnostics),
                 };
             }