@womp/spark-agent 4.2.0 → 4.2.2

package/README.md

@@ -372,6 +372,27 @@ Releases use a manual package publication; no separate release service is requir
 - Server cancellation waits for active execution to settle before reporting its terminal state.
 - Includes the latest geometry material, scalar-port, and primitive improvements from main.
 
+### 4.2.2
+
+The published 4.2.1 was packed from the 4.2.0 sources and differs from 4.2.0 only in its version
+number, so none of the changes below are in it. Use 4.2.2.
+
+Compatible: both additions are optional, and a host that sets neither behaves as before except that a
+run whose progress cannot be stored now ends instead of staying `running`.
+
+- A run whose stream chunk, `running` status or ending cannot be stored ends `failed` with a sentence
+  instead of staying `running` until a restart. The final status and the conversation release are
+  retried in the background for about five minutes; a message or a Stop for that conversation stores
+  the ending at once.
+- `SparkAgentServiceOptions.endOrphanedRuns` (default `false`): a message or a Stop ends an unfinished
+  active run that no execution in this process holds, with "This run stopped unexpectedly and could
+  not be finished." Turn it on only when one process owns the store; on a shared store it would end
+  another process's live runs.
+- `SparkAgentStore.releaseActiveRun(conversationId, runId, updatedAt)` (optional): clears the active
+  run only while it still names that run. The memory and SQLite stores implement it. A store without
+  it has the read-and-save release serialised against the service's own submits, so a late retry
+  cannot overwrite a newer message.
+
 ### 4.2.0
 
 Incompatible: a color that can only be a 0-1 one is now refused where it used to be stored as

package/dist/server/index.d.ts

@@ -1,8 +1,8 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export type { SparkArtifactStore, StoredSparkArtifact } from "./artifacts.js";
 export { createSparkRunExecutor, type ResolvedSparkModel, type SparkRunExecutorOptions, } from "./executor.js";
-export { SparkAgentService, SparkServiceError } from "./service.js";
-export type { SubmitSparkMessageInput } from "./service.js";
+export { DEFAULT_ENDING_RETRY_DELAYS_MS, RUN_INTERRUPTED_ERROR, RUN_NOT_SAVED_ERROR, SparkAgentService, SparkServiceError, } from "./service.js";
+export type { SparkAgentServiceOptions, SubmitSparkMessageInput } from "./service.js";
 export { MemorySparkAgentStore } from "./store.js";
 export { SqliteSparkStore } from "./sqlite-store.js";
 export { createStandaloneSparkAgentApp, type StandaloneSparkAgentOptions, type StandaloneSparkAgentApp, } from "./standalone.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export { createSparkRunExecutor, } from "./executor.js";
-export { SparkAgentService, SparkServiceError } from "./service.js";
+export { DEFAULT_ENDING_RETRY_DELAYS_MS, RUN_INTERRUPTED_ERROR, RUN_NOT_SAVED_ERROR, SparkAgentService, SparkServiceError, } from "./service.js";
 export { MemorySparkAgentStore } from "./store.js";
 export { SqliteSparkStore } from "./sqlite-store.js";
 export { createStandaloneSparkAgentApp, } from "./standalone.js";

package/dist/server/service.d.ts

@@ -1,5 +1,24 @@
 import { type SparkUIMessage, type StoredSparkChunk } from "../ui.js";
 import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun, SparkRunExecutor, SparkRunSettings } from "./types.js";
+/** Why a run ended when its progress could not be stored. */
+export declare const RUN_NOT_SAVED_ERROR = "This run was stopped because its progress could not be saved.";
+/** Why a run ended that no execution in this process was running any more. */
+export declare const RUN_INTERRUPTED_ERROR = "This run stopped unexpectedly and could not be finished.";
+/** How long to wait before each further attempt to store a run's ending. About 5 minutes in all. */
+export declare const DEFAULT_ENDING_RETRY_DELAYS_MS: readonly number[];
+export type SparkAgentServiceOptions = {
+    store: SparkAgentStore;
+    executeRun: SparkRunExecutor;
+    /**
+     * Ends, with `RUN_INTERRUPTED_ERROR`, an unfinished active run that no
+     * execution in this process is running, when a message is submitted to its
+     * conversation or it is cancelled. Only for a host that is the only process
+     * running runs from its store: another process's live run would be ended.
+     */
+    endOrphanedRuns?: boolean;
+    /** Delays between the attempts to store an ending that could not be stored. */
+    endingRetryDelaysMs?: readonly number[];
+};
 export declare class SparkServiceError extends Error {
     readonly statusCode: number;
     constructor(statusCode: number, message: string);
@@ -18,10 +37,15 @@ export declare class SparkAgentService {
     private readonly controllers;
     private readonly listeners;
     private readonly executions;
-    constructor(options: {
-        store: SparkAgentStore;
-        executeRun: SparkRunExecutor;
-    });
+    /** Runs this process started and has not finished ending. */
+    private readonly live;
+    /** Runs whose execution is over but whose ending is still being stored. */
+    private readonly ending;
+    private readonly endOrphanedRuns;
+    /** Per conversation: the tail of its read-modify-write sections in this process. */
+    private readonly conversationTurns;
+    private readonly endingRetryDelaysMs;
+    constructor(options: SparkAgentServiceOptions);
     createConversation(ownerId: string, input?: {
         id?: string;
         title?: string;
@@ -36,9 +60,45 @@ export declare class SparkAgentService {
     recoverInterruptedRun(runId: string): Promise<void>;
     close(): Promise<void>;
     submitMessage(input: SubmitSparkMessageInput): Promise<SparkRun>;
+    private submitInTurn;
     cancelRun(ownerId: string, runId: string): Promise<SparkRun>;
     streamRun(ownerId: string, runId: string, afterSequence: number, signal: AbortSignal): AsyncGenerator<StoredSparkChunk>;
     private runInBackground;
+    /** Ends a run whose execution, or whose own bookkeeping, failed. */
+    private endAfterError;
+    /**
+     * The last resort when a run's ending could not be written in full: the run
+     * row gets its terminal status and the conversation lets go of the run, so
+     * it is not left unfinished. Its stored chunks may lack the ending. A store
+     * that is still failing is retried in the background with backoff
+     * (`endingRetryDelaysMs`); until then, a message or a Stop for the
+     * conversation ends the run at once (`endIfNotRunning`).
+     */
+    private endWithoutHistory;
+    /** `storeEnding`, answering whether it was stored rather than throwing. */
+    private tryStoreEnding;
+    /**
+     * Runs `action` after every earlier section for the conversation in this
+     * process has finished, so a read-modify-write of it (a submit, a released
+     * run) never saves back a copy another one has since replaced.
+     */
+    private inConversationTurn;
+    /**
+     * Writes a run's terminal status unless the stored run has already ended,
+     * then clears the conversation's active run while it still names the run.
+     * Read back first, so a late write never replaces a newer ending or a
+     * newer active run.
+     */
+    private storeEnding;
+    /** Clears the conversation's active run while it is still `runId`, and nothing else. */
+    private releaseRun;
+    /**
+     * Ends an unfinished run that is not being executed: one whose ending this
+     * process is still retrying, or, with `endOrphanedRuns`, one no execution in
+     * this process is running at all (its process stopped). Answers whether it
+     * was ended; throws when the store is still failing.
+     */
+    private endIfNotRunning;
     private finishRun;
     private materializeMessage;
     private appendStatus;

package/dist/server/service.js

@@ -7,6 +7,23 @@ const TERMINAL_STATUSES = new Set([
     "cancelled",
     "incomplete",
 ]);
+/** Why a run ended when its progress could not be stored. */
+export const RUN_NOT_SAVED_ERROR = "This run was stopped because its progress could not be saved.";
+/** Why a run ended that no execution in this process was running any more. */
+export const RUN_INTERRUPTED_ERROR = "This run stopped unexpectedly and could not be finished.";
+/** How long to wait before each further attempt to store a run's ending. About 5 minutes in all. */
+export const DEFAULT_ENDING_RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000, 60_000, 60_000, 60_000, 60_000];
+/** Waits without keeping the process alive. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (typeof timer === "object" && timer !== null && "unref" in timer)
+            timer.unref();
+    });
+}
+function runNotSaved(cause) {
+    return new Error(RUN_NOT_SAVED_ERROR, { cause });
+}
 export class SparkServiceError extends Error {
     statusCode;
     constructor(statusCode, message) {
@@ -70,9 +87,19 @@ export class SparkAgentService {
     controllers = new Map();
     listeners = new Map();
     executions = new Map();
+    /** Runs this process started and has not finished ending. */
+    live = new Set();
+    /** Runs whose execution is over but whose ending is still being stored. */
+    ending = new Map();
+    endOrphanedRuns;
+    /** Per conversation: the tail of its read-modify-write sections in this process. */
+    conversationTurns = new Map();
+    endingRetryDelaysMs;
     constructor(options) {
         this.store = options.store;
         this.executeRun = options.executeRun;
+        this.endOrphanedRuns = options.endOrphanedRuns ?? false;
+        this.endingRetryDelaysMs = options.endingRetryDelaysMs ?? DEFAULT_ENDING_RETRY_DELAYS_MS;
     }
     async createConversation(ownerId, input) {
         const createdAt = now();
@@ -142,12 +169,18 @@ export class SparkAgentService {
         await Promise.all([...this.executions.values()]);
     }
     async submitMessage(input) {
+        return this.inConversationTurn(input.conversationId, () => this.submitInTurn(input));
+    }
+    async submitInTurn(input) {
         const conversation = await this.getConversation(input.ownerId, input.conversationId);
         const activeRun = conversation.activeRunId === undefined
             ? undefined
             : await this.store.getRun(conversation.activeRunId);
         if (activeRun !== undefined && TERMINAL_STATUSES.has(activeRun.status) === false) {
-            throw new SparkServiceError(409, "This conversation already has an active run.");
+            if (!(await this.endIfNotRunning(activeRun, true)))
+                throw new SparkServiceError(409, "This conversation already has an active run.");
+            if (conversation.activeRunId === activeRun.id)
+                conversation.activeRunId = undefined;
         }
         let inputMessage;
         if (input.trigger === "regenerate-message") {
@@ -193,25 +226,47 @@ export class SparkAgentService {
         };
         conversation.activeRunId = run.id;
         conversation.updatedAt = createdAt;
-        await this.store.saveConversation(conversation);
-        await this.store.createRun(run);
-        await this.appendChunk(run, {
-            type: "start",
-            messageId: run.assistantMessageId,
-            messageMetadata: {
-                createdAt,
-                runId: run.id,
-                runStatus: "queued",
-                modelId: run.settings.modelId,
-            },
-        });
-        await this.appendStatus(run, "queued");
+        this.live.add(run.id);
+        try {
+            await this.store.saveConversation(conversation);
+            await this.store.createRun(run);
+        }
+        catch (error) {
+            this.live.delete(run.id);
+            throw error;
+        }
+        try {
+            await this.appendChunk(run, {
+                type: "start",
+                messageId: run.assistantMessageId,
+                messageMetadata: {
+                    createdAt,
+                    runId: run.id,
+                    runStatus: "queued",
+                    modelId: run.settings.modelId,
+                },
+            });
+            await this.appendStatus(run, "queued");
+        }
+        catch (error) {
+            // The run exists and the conversation names it, so it is ended here
+            // rather than left `queued` with the conversation refusing every later
+            // message.
+            const failure = runNotSaved(error);
+            const diagnostics = sparkErrorDiagnostics(failure);
+            await this.endWithoutHistory(run, { status: "failed", error: diagnostics.message, errorDiagnostics: diagnostics }, error, true);
+            throw failure;
+        }
         const controller = new AbortController();
         this.controllers.set(run.id, controller);
         const execution = this.runInBackground(run, conversation, controller);
         this.executions.set(run.id, execution);
         void execution
-            .finally(() => this.executions.delete(run.id))
+            .finally(() => {
+            this.executions.delete(run.id);
+            if (!this.ending.has(run.id))
+                this.live.delete(run.id);
+        })
             .catch((error) => {
             console.error("Spark run persistence failed", error);
         });
@@ -223,8 +278,11 @@ export class SparkAgentService {
             return run;
         const controller = this.controllers.get(run.id);
         const execution = this.executions.get(run.id);
-        if (!controller || !execution)
+        if (!controller || !execution) {
+            if (await this.endIfNotRunning(run))
+                return this.getRun(ownerId, runId);
             throw new Error("The run's executor is unavailable; cancellation could not be confirmed.");
+        }
         controller.abort(new Error("Run cancelled by the user."));
         // Drain receipts and pending host work before publishing a terminal state.
         await execution;
@@ -287,21 +345,26 @@ export class SparkAgentService {
         }
     }
     async runInBackground(run, conversation, controller) {
-        const startedAt = now();
-        run = {
-            ...run,
-            status: "running",
-            startedAt,
-            updatedAt: startedAt,
-        };
-        await this.store.saveRun(run);
-        const runningChunk = {
-            type: "data-run-status",
-            id: `run-status-${run.id}`,
-            data: { runId: run.id, status: "running" },
-        };
-        await this.appendChunk(run, runningChunk);
+        // Aborts the execution when its progress cannot be stored. Unlike
+        // `controller`, it does not mean the user cancelled.
+        const unsaved = new AbortController();
+        // A terminal status already in the run's chunks; a later failure keeps it.
+        let written;
         try {
+            const startedAt = now();
+            run = {
+                ...run,
+                status: "running",
+                startedAt,
+                updatedAt: startedAt,
+            };
+            await this.store.saveRun(run);
+            const runningChunk = {
+                type: "data-run-status",
+                id: `run-status-${run.id}`,
+                data: { runId: run.id, status: "running" },
+            };
+            await this.appendChunk(run, runningChunk);
             const execution = await this.executeRun({
                 ownerId: conversation.ownerId,
                 conversationId: conversation.id,
@@ -309,13 +372,33 @@ export class SparkAgentService {
                 assistantMessageId: run.assistantMessageId,
                 uiMessages: conversation.messages,
                 settings: run.settings,
-                signal: controller.signal,
+                signal: AbortSignal.any([controller.signal, unsaved.signal]),
             });
+            // A chunk that cannot be stored aborts the execution, and the stream is
+            // still read to its end: an execution settles its result only once its
+            // stream has been read, so a reader that stopped here would leave the
+            // run waiting on its result for good.
+            let persistError;
             const consume = (async () => {
-                for await (const chunk of execution.stream) {
-                    if (chunk.type === "start")
-                        continue;
-                    await this.appendChunk(run, chunk);
+                const reader = execution.stream.getReader();
+                try {
+                    for (;;) {
+                        const next = await reader.read();
+                        if (next.done)
+                            return;
+                        if (next.value.type === "start" || persistError !== undefined)
+                            continue;
+                        try {
+                            await this.appendChunk(run, next.value);
+                        }
+                        catch (error) {
+                            persistError = error;
+                            unsaved.abort(runNotSaved(error));
+                        }
+                    }
+                }
+                finally {
+                    reader.releaseLock();
                 }
             })().then(() => undefined, (error) => error);
             let executionError;
@@ -327,27 +410,42 @@ export class SparkAgentService {
                 executionError = error;
             }
             const streamError = await consume;
+            if (persistError !== undefined)
+                throw runNotSaved(persistError);
             if (executionError !== undefined)
                 throw executionError;
             if (streamError !== undefined)
                 throw streamError;
-            if (controller.signal.aborted) {
-                await this.appendStatus(run, "cancelled");
-                await this.finishRun(run, conversation, "cancelled");
-                return;
-            }
-            const status = result?.status ?? "incomplete";
+            const status = controller.signal.aborted ? "cancelled" : (result?.status ?? "incomplete");
             await this.appendStatus(run, status);
+            written = status;
             await this.finishRun(run, conversation, status);
         }
         catch (error) {
-            if (controller.signal.aborted) {
+            if (written !== undefined)
+                await this.endWithoutHistory(run, { status: written }, error);
+            else
+                await this.endAfterError(run, conversation, controller, error);
+        }
+        finally {
+            this.controllers.delete(run.id);
+        }
+    }
+    /** Ends a run whose execution, or whose own bookkeeping, failed. */
+    async endAfterError(run, conversation, controller, error) {
+        if (controller.signal.aborted) {
+            try {
                 await this.appendStatus(run, "cancelled");
                 await this.finishRun(run, conversation, "cancelled");
-                return;
             }
-            const diagnostics = sparkErrorDiagnostics(error);
-            const message = diagnostics.message;
+            catch (endingError) {
+                await this.endWithoutHistory(run, { status: "cancelled" }, endingError);
+            }
+            return;
+        }
+        const diagnostics = sparkErrorDiagnostics(error);
+        const message = diagnostics.message;
+        try {
             const failedChunk = {
                 type: "data-run-status",
                 id: `run-status-${run.id}`,
@@ -357,9 +455,134 @@ export class SparkAgentService {
             await this.appendChunk(run, failedChunk);
             await this.finishRun(run, conversation, "failed", message, diagnostics);
         }
+        catch (endingError) {
+            await this.endWithoutHistory(run, { status: "failed", error: message, errorDiagnostics: diagnostics }, endingError);
+        }
+    }
+    /**
+     * The last resort when a run's ending could not be written in full: the run
+     * row gets its terminal status and the conversation lets go of the run, so
+     * it is not left unfinished. Its stored chunks may lack the ending. A store
+     * that is still failing is retried in the background with backoff
+     * (`endingRetryDelaysMs`); until then, a message or a Stop for the
+     * conversation ends the run at once (`endIfNotRunning`).
+     */
+    async endWithoutHistory(run, ending, cause, inTurn = false) {
+        console.error("Spark run ending could not be stored in full", cause);
+        this.ending.set(run.id, ending);
+        if (await this.tryStoreEnding(run, ending, inTurn)) {
+            this.ending.delete(run.id);
+            return;
+        }
+        void (async () => {
+            for (const delay of this.endingRetryDelaysMs) {
+                await sleep(delay);
+                // Ended meanwhile by a message or a Stop (`endIfNotRunning`).
+                if (!this.ending.has(run.id))
+                    break;
+                if (await this.tryStoreEnding(run, ending))
+                    break;
+            }
+            this.ending.delete(run.id);
+            if (!this.executions.has(run.id))
+                this.live.delete(run.id);
+        })();
+    }
+    /** `storeEnding`, answering whether it was stored rather than throwing. */
+    async tryStoreEnding(run, ending, inTurn = false) {
+        try {
+            await this.storeEnding(run.id, ending, inTurn);
+            return true;
+        }
+        catch (error) {
+            console.error("Spark run ending could not be stored", error);
+            return false;
+        }
+    }
+    /**
+     * Runs `action` after every earlier section for the conversation in this
+     * process has finished, so a read-modify-write of it (a submit, a released
+     * run) never saves back a copy another one has since replaced.
+     */
+    async inConversationTurn(conversationId, action) {
+        const previous = this.conversationTurns.get(conversationId) ?? Promise.resolve();
+        let done = () => undefined;
+        const turn = new Promise((resolve) => {
+            done = resolve;
+        });
+        const tail = previous.then(() => turn);
+        this.conversationTurns.set(conversationId, tail);
+        await previous;
+        try {
+            return await action();
+        }
         finally {
-            this.controllers.delete(run.id);
+            done();
+            if (this.conversationTurns.get(conversationId) === tail)
+                this.conversationTurns.delete(conversationId);
+        }
+    }
+    /**
+     * Writes a run's terminal status unless the stored run has already ended,
+     * then clears the conversation's active run while it still names the run.
+     * Read back first, so a late write never replaces a newer ending or a
+     * newer active run.
+     */
+    async storeEnding(runId, ending, inTurn = false) {
+        const stored = await this.store.getRun(runId);
+        if (stored === undefined)
+            return;
+        const completedAt = now();
+        if (!TERMINAL_STATUSES.has(stored.status)) {
+            await this.store.saveRun({
+                ...stored,
+                status: ending.status,
+                ...(ending.error === undefined ? {} : { error: ending.error }),
+                ...(ending.errorDiagnostics === undefined ? {} : { errorDiagnostics: ending.errorDiagnostics }),
+                updatedAt: completedAt,
+                completedAt,
+            });
+        }
+        await this.releaseRun(stored.conversationId, runId, completedAt, inTurn);
+        this.ending.delete(runId);
+        this.wakeRun(runId);
+    }
+    /** Clears the conversation's active run while it is still `runId`, and nothing else. */
+    async releaseRun(conversationId, runId, at, inTurn) {
+        if (this.store.releaseActiveRun !== undefined) {
+            await this.store.releaseActiveRun(conversationId, runId, at);
+            return;
+        }
+        const release = async () => {
+            const conversation = await this.store.getConversation(conversationId);
+            if (conversation === undefined || conversation.activeRunId !== runId)
+                return;
+            conversation.activeRunId = undefined;
+            conversation.updatedAt = at;
+            await this.store.saveConversation(conversation);
+        };
+        if (inTurn)
+            await release();
+        else
+            await this.inConversationTurn(conversationId, release);
+    }
+    /**
+     * Ends an unfinished run that is not being executed: one whose ending this
+     * process is still retrying, or, with `endOrphanedRuns`, one no execution in
+     * this process is running at all (its process stopped). Answers whether it
+     * was ended; throws when the store is still failing.
+     */
+    async endIfNotRunning(run, inTurn = false) {
+        const pending = this.ending.get(run.id);
+        if (pending !== undefined) {
+            await this.storeEnding(run.id, pending, inTurn);
+            return true;
         }
+        if (!this.endOrphanedRuns || this.live.has(run.id))
+            return false;
+        const diagnostics = sparkErrorDiagnostics(RUN_INTERRUPTED_ERROR);
+        await this.storeEnding(run.id, { status: "failed", error: diagnostics.message, errorDiagnostics: diagnostics }, inTurn);
+        return true;
     }
     async finishRun(run, conversation, status, error, errorDiagnostics) {
         const completedAt = now();

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

@@ -21,6 +21,7 @@ export declare class SqliteSparkStore implements SparkAgentStore, SparkArtifactS
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     saveConversation(value: SparkConversation): Promise<void>;
+    releaseActiveRun(conversationId: string, runId: string, updatedAt: string): Promise<void>;
     saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
     deleteConversation(id: string): Promise<boolean>;
     createRun(value: SparkRun): Promise<void>;

package/dist/server/sqlite-store.js

@@ -163,6 +163,9 @@ export class SqliteSparkStore {
         if (result.changes === 0)
             throw new Error(`Conversation ${value.id} does not exist.`);
     }
+    async releaseActiveRun(conversationId, runId, updatedAt) {
+        this.database.prepare("UPDATE conversations SET updated_at = ?, data = json_set(json_remove(data, '$.activeRunId'), '$.updatedAt', ?) WHERE id = ? AND json_extract(data, '$.activeRunId') = ?").run(updatedAt, updatedAt, conversationId, runId);
+    }
     async saveConversationSettings(id, settings) {
         const result = this.database.prepare("UPDATE conversations SET data = json_set(data, '$.settings', json(?)) WHERE id = ?").run(JSON.stringify(settings), id);
         if (result.changes === 0)

package/dist/server/store.d.ts

@@ -8,6 +8,7 @@ export declare class MemorySparkAgentStore implements SparkAgentStore {
     getConversation(id: string): Promise<SparkConversation | undefined>;
     listConversations(ownerId: string): Promise<SparkConversationSummary[]>;
     saveConversation(conversation: SparkConversation): Promise<void>;
+    releaseActiveRun(conversationId: string, runId: string, updatedAt: string): Promise<void>;
     saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
     deleteConversation(id: string): Promise<boolean>;
     createRun(run: SparkRun): Promise<void>;

package/dist/server/store.js

@@ -32,6 +32,13 @@ export class MemorySparkAgentStore {
         const settings = this.conversations.get(conversation.id).settings;
         this.conversations.set(conversation.id, copy({ ...history, ...(settings ? { settings } : {}) }));
     }
+    async releaseActiveRun(conversationId, runId, updatedAt) {
+        const conversation = this.conversations.get(conversationId);
+        if (conversation === undefined || conversation.activeRunId !== runId)
+            return;
+        conversation.activeRunId = undefined;
+        conversation.updatedAt = updatedAt;
+    }
     async saveConversationSettings(id, settings) {
         const conversation = this.conversations.get(id);
         if (conversation === undefined)

package/dist/server/types.d.ts

@@ -57,4 +57,11 @@ export interface SparkAgentStore {
     saveRun(run: SparkRun): Promise<void>;
     appendRunChunk(runId: string, conversationId: string, chunk: StoredSparkChunk["chunk"]): Promise<StoredSparkChunk>;
     listRunChunks(runId: string, afterSequence: number): Promise<StoredSparkChunk[]>;
+    /**
+     * Clears the conversation's active run only while it is still `runId`,
+     * touching nothing else on it. Optional: without it, the service releases
+     * a run by reading the conversation and saving it back, serialised against
+     * its own submits in this process.
+     */
+    releaseActiveRun?(conversationId: string, runId: string, updatedAt: string): Promise<void>;
 }

package/package.json

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