@womp/spark-agent 4.2.1 → 4.3.0

package/dist/server/message-fold.js

@@ -0,0 +1,345 @@
+// A run's assistant message, rebuilt from its stored chunks a step at a time.
+//
+// WHY. The AI SDK's `readUIMessageStream` deep-copies (`structuredClone`) the
+// whole message on every chunk it writes, so replaying a long run in one pass
+// costs chunks x message size, all of it in already-resolved promises that
+// never yield. `SparkAgentService.finishRun` did exactly that once per run: a
+// 150-step run with 20 KB tool outputs held the process's event loop for
+// 10-13 s as it ended, and a host that serves other requests (crow) went
+// silent for everyone while a thread write in flight timed out.
+//
+// HOW. The fold keeps a SETTLED message: the result of every chunk up to a
+// sequence at which a new step starts and no text, reasoning or tool input is
+// open. Each read folds only the chunks after that sequence onto it, with the
+// same SDK reader, and moves the settled point to the last such step start it
+// sees. `foldAllChunks` reads a whole run that way, one step start at a time,
+// and yields to the event loop as it goes.
+//
+// A PART LEFT OPEN ACROSS STEPS (a provider that never ends a text, reasoning
+// or tool input) means nothing settles until it closes. `foldAllChunks` then
+// reads only where a step starts with nothing open, so the rest of the run is
+// folded in one pass, as a full replay is; a live reader (`read` after every
+// chunk) re-folds a long unsettled tail only after it has grown by a quarter
+// (`UNSETTLED_TAIL_THROTTLE`); and the reader is fed through a stream that
+// gives the event loop back every `FOLD_YIELD_MS`, so even that one pass never
+// holds the loop for its whole length.
+//
+// WHY THE RESULT IS THE SAME AS A FULL REPLAY. The SDK reader cannot resume
+// inside an open part: the open text, reasoning and tool input ids live in
+// reader state, not in the message. At a `start-step` chunk with nothing open
+// that state is empty in a full replay too, and the reader's "current step"
+// (the parts after the last `step-start` part) begins at that chunk in both.
+// The only other things a chunk can reach in earlier parts are:
+//   - a tool part by `toolCallId` (an output for a call from an earlier step),
+//   - a tool part by approval id (`tool-approval-response`),
+//   - a data part with the same type and id (it is updated in place),
+//   - the message metadata (merged).
+// So each read hands the reader the settled metadata plus a copy of exactly
+// the earlier parts the new chunks name, then puts the updated copies back at
+// their places and appends the new parts. A seeded property test
+// (test/message-fold.test.ts) holds it to a full replay after every chunk.
+import { readUIMessageStream, UIMessageStreamError } from "ai";
+/** One of a chunk's string fields, or `undefined`. */
+function stringField(chunk, name) {
+    const value = chunk[name];
+    return typeof value === "string" ? value : undefined;
+}
+function isToolPart(part) {
+    return "toolCallId" in part && typeof part.toolCallId === "string";
+}
+function approvalIdOf(part) {
+    if (!("approval" in part))
+        return undefined;
+    const approval = part.approval;
+    if (approval === null || typeof approval !== "object")
+        return undefined;
+    const id = approval.id;
+    return typeof id === "string" ? id : undefined;
+}
+/** A chunk type the reader treats as a data part. */
+function isDataChunk(chunk) {
+    return chunk.type.startsWith("data-");
+}
+/**
+ * The indexes of the settled parts that `chunks` may reach, chosen the way the
+ * reader looks them up: a tool part by call id takes the LAST match (the reader
+ * scans the whole message backwards once the current step has none), a data
+ * part the FIRST (`parts.find`), a tool part by approval id the first.
+ */
+function reachedParts(parts, chunks) {
+    // EVERY call id the chunks name, including one a `tool-input-start` in these
+    // chunks opens again: if that new part is later removed (`reset-step`), the
+    // reader's backward scan finds the earlier step's part for the same id.
+    const callIds = new Set();
+    const approvalIds = new Set();
+    const dataKeys = new Set();
+    for (const chunk of chunks) {
+        const callId = stringField(chunk, "toolCallId");
+        if (callId !== undefined)
+            callIds.add(callId);
+        if (chunk.type === "tool-approval-response") {
+            const approvalId = stringField(chunk, "approvalId");
+            if (approvalId !== undefined)
+                approvalIds.add(approvalId);
+        }
+        const id = stringField(chunk, "id");
+        if (isDataChunk(chunk) && id !== undefined && chunk.transient !== true) {
+            dataKeys.add(`${chunk.type}\u0000${id}`);
+        }
+    }
+    if (callIds.size === 0 && approvalIds.size === 0 && dataKeys.size === 0)
+        return [];
+    const reached = new Set();
+    const lastByCall = new Map();
+    const firstByData = new Map();
+    parts.forEach((part, index) => {
+        if (isToolPart(part) && callIds.has(part.toolCallId))
+            lastByCall.set(part.toolCallId, index);
+        const approvalId = approvalIdOf(part);
+        if (isToolPart(part) && approvalId !== undefined && approvalIds.has(approvalId))
+            reached.add(index);
+        if ("id" in part && "data" in part && typeof part.id === "string") {
+            const key = `${part.type}\u0000${part.id}`;
+            if (dataKeys.has(key) && !firstByData.has(key))
+                firstByData.set(key, index);
+        }
+    });
+    lastByCall.forEach((index) => reached.add(index));
+    firstByData.forEach((index) => reached.add(index));
+    return Array.from(reached).sort((left, right) => left - right);
+}
+/**
+ * The last index in `chunks` at which a step starts with no text, reasoning or
+ * tool input open, or 0 for none. The chunks before it can be settled.
+ */
+function lastCut(chunks) {
+    const open = new Set();
+    let cut = 0;
+    chunks.forEach((chunk, index) => {
+        if (chunk.type === "start-step" && open.size === 0 && index > 0)
+            cut = index;
+        trackOpenParts(open, chunk);
+    });
+    return cut;
+}
+/** Updates `open`, the text, reasoning and tool-input parts open, for one chunk. */
+function trackOpenParts(open, chunk) {
+    const id = stringField(chunk, "id");
+    const callId = stringField(chunk, "toolCallId");
+    switch (chunk.type) {
+        case "text-start":
+        case "reasoning-start":
+            if (id !== undefined)
+                open.add(`${chunk.type.slice(0, -6)}\u0000${id}`);
+            break;
+        case "text-end":
+        case "reasoning-end":
+            if (id !== undefined)
+                open.delete(`${chunk.type.slice(0, -4)}\u0000${id}`);
+            break;
+        case "tool-input-start":
+            if (callId !== undefined)
+                open.add(`tool\u0000${callId}`);
+            break;
+        case "tool-input-available":
+        case "tool-input-error":
+            if (callId !== undefined)
+                open.delete(`tool\u0000${callId}`);
+            break;
+        case "reset-step":
+            open.clear();
+            break;
+        default:
+            break;
+    }
+}
+/**
+ * The chunks as a stream the reader pulls one at a time, giving the event loop
+ * back every `FOLD_YIELD_MS` of reading. The reader copies its whole message on
+ * every chunk it writes, so a pass over a long unsettled tail (a part left
+ * open across steps) is still expensive; this spreads it across turns rather
+ * than holding the loop for its whole length.
+ */
+/** How many chunks the reader is handed per pull. */
+const CHUNKS_PER_PULL = 16;
+function chunkStream(chunks) {
+    let next = 0;
+    let worked = performance.now();
+    return new ReadableStream({
+        async pull(controller) {
+            // Pulled once the reader has taken the previous chunk, so the time
+            // since the last yield includes its work on the chunks before.
+            if (performance.now() - worked >= FOLD_YIELD_MS) {
+                await new Promise((resolve) => setImmediate(resolve));
+                worked = performance.now();
+            }
+            // A few at a time: a pull per chunk costs more than a short pass.
+            const end = Math.min(next + CHUNKS_PER_PULL, chunks.length);
+            for (; next < end; next += 1) {
+                const chunk = chunks[next];
+                if (chunk !== undefined)
+                    controller.enqueue(chunk);
+            }
+            if (next >= chunks.length)
+                controller.close();
+        },
+    }, { highWaterMark: 1 });
+}
+/** `base` with the reached parts replaced by the first of `folded`'s parts, and
+ *  the rest of `folded`'s parts appended. */
+function merge(base, reached, folded) {
+    const parts = base.slice();
+    reached.forEach((index, position) => {
+        const part = folded.parts[position];
+        if (part !== undefined)
+            parts[index] = part;
+    });
+    parts.push(...folded.parts.slice(reached.length));
+    return { ...folded, parts };
+}
+/**
+ * Folds `chunks` onto `base` with the SDK reader. `base` is never mutated: the
+ * reader is given copies of the parts it may reach, and the result shares the
+ * other parts with `base`.
+ */
+async function fold(base, chunks) {
+    const parts = base?.state.parts ?? [];
+    const reached = reachedParts(parts, chunks);
+    // The reader keeps THIS object as its message and mutates it in place, so
+    // once the stream is read it holds the state after the last chunk.
+    // In the reader's own key order (`createStreamingUIMessageState`), so the
+    // message serialises byte for byte as a full replay's does.
+    const working = {
+        id: base?.state.id ?? "",
+        metadata: base?.state.metadata === undefined ? undefined : structuredClone(base.state.metadata),
+        role: "assistant",
+        parts: reached.flatMap((index) => {
+            const part = parts[index];
+            return part === undefined ? [] : [structuredClone(part)];
+        }),
+    };
+    // A chunk the reader cannot apply ends its stream, and it reports that
+    // through `onError`, as it reports an `error` chunk. An `error` chunk comes as
+    // a plain `Error`; a chunk it cannot apply as a `UIMessageStreamError` (or,
+    // for a fault inside the reader, some other error class). Counting `error`
+    // chunks instead would miss a stop followed by an `error` chunk the reader
+    // never reached.
+    let stopped = false;
+    let lastWritten;
+    for await (const current of readUIMessageStream({
+        message: working,
+        stream: chunkStream(chunks),
+        terminateOnError: false,
+        onError: (error) => {
+            if (UIMessageStreamError.isInstance(error) ||
+                !(error instanceof Error) ||
+                Object.getPrototypeOf(error) !== Error.prototype) {
+                stopped = true;
+            }
+        },
+    })) {
+        lastWritten = current;
+    }
+    return {
+        state: merge(parts, reached, working),
+        written: lastWritten === undefined ? base?.written : merge(parts, reached, lastWritten),
+        stopped: (base?.stopped ?? false) || stopped,
+    };
+}
+/** How many step starts may pass with a part still open before it is logged. */
+export const UNSETTLED_STEPS_LOGGED = 10;
+/** An unsettled tail this long is re-folded only after it grows by a quarter. */
+export const UNSETTLED_TAIL_THROTTLE = 400;
+export function createRunMessageFold(options = {}) {
+    let unsettledLogged = false;
+    // The last fold of the unsettled tail, and how long that tail was: reset
+    // whenever the settled point moves.
+    let tailFold;
+    let settled;
+    let settledSequence = 0;
+    let folded = 0;
+    return {
+        async read(list, readOptions = {}) {
+            const stored = await list(settledSequence);
+            // A reader that stopped at a chunk it could not apply ignores every later
+            // chunk in a full replay too, so nothing after it changes the message.
+            if (settled?.stopped === true)
+                return settled.written;
+            const chunks = stored.map(({ chunk }) => chunk);
+            const cut = lastCut(chunks);
+            let base = settled;
+            if (cut > 0) {
+                base = await fold(settled, chunks.slice(0, cut));
+                folded += cut;
+                settled = base;
+                settledSequence = stored[cut - 1]?.sequence ?? settledSequence;
+                tailFold = undefined;
+                if (base.stopped)
+                    return base.written;
+            }
+            const tail = chunks.slice(cut);
+            if (!unsettledLogged && options.onUnsettled !== undefined) {
+                const steps = tail.filter((chunk) => chunk.type === "start-step").length;
+                if (steps >= UNSETTLED_STEPS_LOGGED) {
+                    unsettledLogged = true;
+                    options.onUnsettled({ steps, chunks: tail.length });
+                }
+            }
+            if (tail.length === 0)
+                return base?.written;
+            if (readOptions.complete !== true &&
+                tailFold !== undefined &&
+                tail.length >= UNSETTLED_TAIL_THROTTLE &&
+                tail.length < tailFold.length * 1.25) {
+                return tailFold.written ?? base?.written;
+            }
+            const current = await fold(base, tail);
+            folded += tail.length;
+            tailFold = { length: tail.length, written: current.written };
+            return current.written;
+        },
+        foldedChunks: () => folded,
+    };
+}
+/** How long `foldAllChunks` works before it lets other callbacks run. */
+export const FOLD_YIELD_MS = 10;
+/**
+ * The message a full replay of `chunks` builds (the last message
+ * `readUIMessageStream` yields, with `terminateOnError: false`), folded a step
+ * at a time and giving the event loop back every `FOLD_YIELD_MS`. The reader
+ * only ever sees about one step's chunks and the parts they name; with a part
+ * left open across steps, one pass over the rest of the run.
+ */
+export async function foldAllChunks(chunks, options = {}) {
+    const yieldMs = options.yieldMs ?? FOLD_YIELD_MS;
+    // Sequence n is index n - 1, so "after sequence s" is `slice(s)`.
+    const stored = chunks.map((chunk, index) => ({
+        sequence: index + 1,
+        conversationId: "",
+        runId: "",
+        createdAt: "",
+        chunk,
+    }));
+    const fold = options.fold ?? createRunMessageFold();
+    // Only where a step starts with nothing open does a read settle anything
+    // (`lastCut`'s rule); a read anywhere else would fold the whole unsettled
+    // tail again. So a part left open makes this one pass over the rest of the
+    // run, as a full replay is, and never one pass per step.
+    const open = new Set();
+    let worked = performance.now();
+    for (let index = 0; index < stored.length; index += 1) {
+        const chunk = stored[index]?.chunk;
+        if (chunk === undefined)
+            continue;
+        if (chunk.type === "start-step" && index > 0 && open.size === 0) {
+            const end = index + 1;
+            await fold.read(async (after) => stored.slice(after, end));
+            if (performance.now() - worked >= yieldMs) {
+                await new Promise((resolve) => setImmediate(resolve));
+                worked = performance.now();
+            }
+        }
+        trackOpenParts(open, chunk);
+    }
+    return fold.read(async (after) => stored.slice(after), { complete: true });
+}

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,44 @@
+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();
+}

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;
@@ -32,13 +56,66 @@ export declare class SparkAgentService {
     deleteConversation(ownerId: string, id: string): Promise<void>;
     getRun(ownerId: string, id: string): Promise<SparkRun>;
     getActiveRun(ownerId: string, conversationId: string): Promise<SparkRun | undefined>;
-    /** The host must establish exclusive ownership before recovering abandoned runs. */
+    /**
+     * The host must establish exclusive ownership before recovering abandoned runs.
+     *
+     * The ending this writes spans event-loop turns: the run's message is folded
+     * a step at a time and yields as it goes (`finishRun`). The recovered run is
+     * not one this process is running, so nothing here keeps a submit to its
+     * conversation out meanwhile; `finishRun` then saves the conversation as it
+     * read it, over anything that submit wrote. Recover before accepting
+     * requests, as the standalone server does.
+     */
     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;
+    /**
+     * Writes a run's ending: its message, rebuilt from every stored chunk, onto
+     * the conversation, then the run's terminal state. The rebuild is folded a
+     * step at a time and gives the event loop back as it goes (./message-fold.ts),
+     * so the ending spans event-loop turns; for a run this process is running, it
+     * is still in `live` throughout, so a submit to its conversation is refused
+     * until it has ended.
+     */
     private finishRun;
     private materializeMessage;
     private appendStatus;