@qvac/sdk 0.9.2 → 0.10.1

package/dist/server/utils/tools/parsers/pythonic.js

@@ -0,0 +1,267 @@
+import { generateStableToolCallId, validateToolArguments, } from "../shared.js";
+// Pythonic `[name(k=v), ...]` arrays. LFM 2.x is auto-routed; Llama-style
+// tokens are kept for callers that opt in via `completion({ toolDialect:
+// "pythonic" })` for a model known to emit Pythonic. Pure string parsing —
+// no eval/vm/Function (untrusted model output).
+const PYTHONIC_LFM_OPEN = "<|tool_call_start|>";
+const PYTHONIC_LFM_CLOSE = "<|tool_call_end|>";
+const PYTHONIC_LLAMA_OPEN = "<|start_header_id|>tool_call<|end_header_id|>";
+const PYTHONIC_LLAMA_CLOSE = "<|eot_id|>";
+function locatePythonicCallList(text) {
+    const lfmStart = text.indexOf(PYTHONIC_LFM_OPEN);
+    if (lfmStart !== -1) {
+        const after = text.slice(lfmStart + PYTHONIC_LFM_OPEN.length);
+        const end = after.indexOf(PYTHONIC_LFM_CLOSE);
+        return end === -1 ? after : after.slice(0, end);
+    }
+    const llamaStart = text.indexOf(PYTHONIC_LLAMA_OPEN);
+    if (llamaStart !== -1) {
+        const after = text.slice(llamaStart + PYTHONIC_LLAMA_OPEN.length);
+        const end = after.indexOf(PYTHONIC_LLAMA_CLOSE);
+        return end === -1 ? after : after.slice(0, end);
+    }
+    // Identifier+`(` requirement rejects JSON arrays and plain bracketed lists.
+    const bareMatch = /\[\s*[A-Za-z_]\w*\s*\(/.exec(text);
+    if (bareMatch)
+        return text.slice(bareMatch.index);
+    return null;
+}
+function pyPeek(s, offset = 0) {
+    return s.text[s.pos + offset] ?? "";
+}
+function pyConsume(s) {
+    const c = s.text[s.pos] ?? "";
+    s.pos++;
+    return c;
+}
+function pySkipWs(s) {
+    while (/\s/.test(pyPeek(s)))
+        s.pos++;
+}
+function pyParseString(s) {
+    const quote = pyConsume(s);
+    let out = "";
+    while (s.pos < s.text.length && pyPeek(s) !== quote) {
+        if (pyPeek(s) === "\\") {
+            s.pos++;
+            const esc = pyConsume(s);
+            switch (esc) {
+                case "n":
+                    out += "\n";
+                    break;
+                case "t":
+                    out += "\t";
+                    break;
+                case "r":
+                    out += "\r";
+                    break;
+                case "\\":
+                    out += "\\";
+                    break;
+                case "'":
+                    out += "'";
+                    break;
+                case '"':
+                    out += '"';
+                    break;
+                case "0":
+                    out += "\0";
+                    break;
+                default:
+                    out += esc;
+                    break;
+            }
+        }
+        else {
+            out += pyConsume(s);
+        }
+    }
+    if (s.pos >= s.text.length) {
+        throw new Error("Unterminated string literal");
+    }
+    pyConsume(s);
+    return out;
+}
+function pyParseNumber(s) {
+    const start = s.pos;
+    if (pyPeek(s) === "-" || pyPeek(s) === "+")
+        s.pos++;
+    while (/\d/.test(pyPeek(s)))
+        s.pos++;
+    if (pyPeek(s) === ".") {
+        s.pos++;
+        while (/\d/.test(pyPeek(s)))
+            s.pos++;
+    }
+    if (pyPeek(s) === "e" || pyPeek(s) === "E") {
+        s.pos++;
+        if (pyPeek(s) === "-" || pyPeek(s) === "+")
+            s.pos++;
+        while (/\d/.test(pyPeek(s)))
+            s.pos++;
+    }
+    const literal = s.text.slice(start, s.pos);
+    const n = Number(literal);
+    if (Number.isNaN(n) || literal.length === 0) {
+        throw new Error(`Invalid number literal: ${JSON.stringify(literal)}`);
+    }
+    return n;
+}
+function pyParseIdentifier(s) {
+    if (!/[A-Za-z_]/.test(pyPeek(s))) {
+        throw new Error(`Expected identifier, got ${JSON.stringify(pyPeek(s))}`);
+    }
+    const start = s.pos;
+    while (/[\w]/.test(pyPeek(s)))
+        s.pos++;
+    return s.text.slice(start, s.pos);
+}
+// Identifier-as-string fallback: any bare word that isn't `True`/`False`/`None`
+// is returned as a string, so `[get_weather(city=Paris)]` still produces
+// `{ city: "Paris" }`. Side-effect: lowercase `null` / `true` / `false` from
+// JS-trained models also coerce to strings — validate against your tool schema.
+function pyParseValue(s) {
+    pySkipWs(s);
+    const c = pyPeek(s);
+    if (c === '"' || c === "'")
+        return pyParseString(s);
+    if (c === "[")
+        return pyParseList(s);
+    if (c === "{")
+        return pyParseDict(s);
+    if (c === "-" || c === "+" || /\d/.test(c))
+        return pyParseNumber(s);
+    if (/[A-Za-z_]/.test(c)) {
+        const id = pyParseIdentifier(s);
+        if (id === "True")
+            return true;
+        if (id === "False")
+            return false;
+        if (id === "None")
+            return null;
+        return id;
+    }
+    throw new Error(`Unexpected character: ${JSON.stringify(c)}`);
+}
+// Drives `parseItem, sep, parseItem, sep, ..., close` loops with trailing-
+// comma tolerance. Assumes the open delimiter was already consumed.
+function pyParseDelimited(s, close, context, parseItem) {
+    pySkipWs(s);
+    if (pyPeek(s) === close) {
+        pyConsume(s);
+        return;
+    }
+    for (;;) {
+        pySkipWs(s);
+        parseItem();
+        pySkipWs(s);
+        const sep = pyPeek(s);
+        if (sep === ",") {
+            pyConsume(s);
+            pySkipWs(s);
+            if (pyPeek(s) === close) {
+                pyConsume(s);
+                return;
+            }
+        }
+        else if (sep === close) {
+            pyConsume(s);
+            return;
+        }
+        else {
+            throw new Error(`Expected , or ${close} in ${context}, got ${JSON.stringify(sep)}`);
+        }
+    }
+}
+function pyParseList(s) {
+    pyConsume(s);
+    const items = [];
+    pyParseDelimited(s, "]", "list", () => {
+        items.push(pyParseValue(s));
+    });
+    return items;
+}
+function pyParseDict(s) {
+    pyConsume(s);
+    const obj = {};
+    pyParseDelimited(s, "}", "dict", () => {
+        const c = pyPeek(s);
+        let key;
+        if (c === '"' || c === "'")
+            key = pyParseString(s);
+        else if (/[A-Za-z_]/.test(c))
+            key = pyParseIdentifier(s);
+        else
+            throw new Error(`Expected dict key, got ${JSON.stringify(c)}`);
+        pySkipWs(s);
+        if (pyConsume(s) !== ":") {
+            throw new Error(`Expected : after dict key "${key}"`);
+        }
+        obj[key] = pyParseValue(s);
+    });
+    return obj;
+}
+function pyParseArgList(s) {
+    const args = {};
+    pyParseDelimited(s, ")", "args", () => {
+        const key = pyParseIdentifier(s);
+        pySkipWs(s);
+        if (pyConsume(s) !== "=") {
+            throw new Error(`Expected = after arg name "${key}"`);
+        }
+        args[key] = pyParseValue(s);
+    });
+    return args;
+}
+function pyParseCallList(text) {
+    const s = { text, pos: 0 };
+    pySkipWs(s);
+    if (pyConsume(s) !== "[") {
+        throw new Error("Expected [ at start of call list");
+    }
+    const calls = [];
+    pyParseDelimited(s, "]", "call list", () => {
+        const name = pyParseIdentifier(s);
+        pySkipWs(s);
+        if (pyConsume(s) !== "(") {
+            throw new Error(`Expected ( after call name "${name}"`);
+        }
+        calls.push({ name, arguments: pyParseArgList(s) });
+    });
+    return calls;
+}
+export function parsePythonicFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    const slice = locatePythonicCallList(text);
+    if (slice === null) {
+        return { matched: false, toolCalls, errors };
+    }
+    let calls;
+    try {
+        calls = pyParseCallList(slice);
+    }
+    catch (error) {
+        errors.push({
+            code: "PARSE_ERROR",
+            message: `Failed to parse Pythonic tool call list: ${error instanceof Error ? error.message : String(error)}`,
+            raw: slice,
+        });
+        return { matched: true, toolCalls, errors };
+    }
+    for (const call of calls) {
+        const raw = `${call.name}(${JSON.stringify(call.arguments)})`;
+        const validation = validateToolArguments(call.name, call.arguments, tools);
+        if (!validation.isValid && validation.error) {
+            errors.push({ ...validation.error, raw });
+            continue;
+        }
+        toolCalls.push({
+            id: generateStableToolCallId(call.name, call.arguments),
+            name: call.name,
+            arguments: call.arguments,
+            raw,
+        });
+    }
+    return { matched: true, toolCalls, errors };
+}

package/dist/server/utils/tools/shared.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, ToolCall, ToolCallError } from "../../../schemas/index";
+export type ParserResult = {
+    matched: boolean;
+    toolCalls: ToolCall[];
+    errors: ToolCallError[];
+};
+export declare function stripThinkingBlocks(text: string): string;
+export declare function generateStableToolCallId(name: string, args: Record<string, unknown>): string;
+export declare function isValidToolCall(obj: unknown): obj is {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+export declare function validateToolArguments(toolName: string, args: Record<string, unknown>, tools: Tool[]): {
+    isValid: boolean;
+    error?: ToolCallError;
+};
+//# sourceMappingURL=shared.d.ts.map

package/dist/server/utils/tools/shared.js

@@ -0,0 +1,54 @@
+export function stripThinkingBlocks(text) {
+    return text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+}
+let toolCallSequence = 0;
+export function generateStableToolCallId(name, args) {
+    const content = `${name}:${JSON.stringify(args)}`;
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    const sequence = toolCallSequence++;
+    return `call_${Math.abs(hash).toString(36)}_${sequence}`;
+}
+export function isValidToolCall(obj) {
+    if (!obj || typeof obj !== "object") {
+        return false;
+    }
+    if (!("name" in obj) || typeof obj.name !== "string") {
+        return false;
+    }
+    if (!("arguments" in obj) ||
+        typeof obj.arguments !== "object" ||
+        obj.arguments === null) {
+        return false;
+    }
+    return true;
+}
+export function validateToolArguments(toolName, args, tools) {
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        return {
+            isValid: false,
+            error: {
+                code: "UNKNOWN_TOOL",
+                message: `Tool "${toolName}" not found in available tools`,
+            },
+        };
+    }
+    const required = tool.parameters.required || [];
+    for (const requiredParam of required) {
+        if (!(requiredParam in args)) {
+            return {
+                isValid: false,
+                error: {
+                    code: "VALIDATION_ERROR",
+                    message: `Missing required parameter "${requiredParam}" for tool "${toolName}"`,
+                },
+            };
+        }
+    }
+    return { isValid: true };
+}

package/dist/server/utils/worker-lock.d.ts

@@ -0,0 +1,3 @@
+export declare function acquireWorkerLock(): void;
+export declare function releaseWorkerLock(): void;
+//# sourceMappingURL=worker-lock.d.ts.map

package/dist/server/utils/worker-lock.js

@@ -0,0 +1,67 @@
+import fs from "bare-fs";
+import path from "bare-path";
+import process from "bare-process";
+import { getServerLogger } from "../../logging/index.js";
+import { getQvacPath } from "./qvac-paths.js";
+const logger = getServerLogger();
+const LOCK_FILENAME = ".worker.lock";
+function getLockFilePath() {
+    return getQvacPath(LOCK_FILENAME);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLockFile(lockPath) {
+    try {
+        if (!fs.existsSync(lockPath))
+            return null;
+        const raw = fs.readFileSync(lockPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireWorkerLock() {
+    const lockPath = getLockFilePath();
+    const existing = readLockFile(lockPath);
+    if (existing) {
+        if (isProcessAlive(existing.pid)) {
+            logger.warn(`Another worker (PID ${existing.pid}) is still running — lock file exists at ${lockPath}`);
+        }
+        else {
+            logger.warn(`Stale lock file detected (PID ${existing.pid} is dead, started ${existing.startedAt}). Removing.`);
+        }
+    }
+    const content = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        fs.writeFileSync(lockPath, JSON.stringify(content));
+        logger.debug(`Worker lock acquired (PID ${process.pid})`);
+    }
+    catch (error) {
+        logger.error("Failed to write worker lock file:", error instanceof Error ? error.message : String(error));
+    }
+}
+export function releaseWorkerLock() {
+    const lockPath = getLockFilePath();
+    try {
+        const existing = readLockFile(lockPath);
+        if (existing && existing.pid === process.pid) {
+            fs.unlinkSync(lockPath);
+            logger.debug("Worker lock released");
+        }
+    }
+    catch {
+        // Best-effort — may already be gone
+    }
+}

package/dist/server/worker-core.d.ts

@@ -3,6 +3,21 @@ export declare function initializeWorkerCore(): {
 };
 export declare function ensureRPCSetup(): void;
 export declare function isCoreInitialized(): boolean;
-export type BareDirectShutdownReason = "signal" | "rpc-close";
+export type BareDirectShutdownReason = "signal" | "rpc-close" | "uncaught-exception" | "unhandled-rejection" | "ipc-disconnect";
+/**
+ * Pre-terminate cleanup, callable while the worker is still alive.
+ *
+ * On platforms where the worker lives in the same OS process as the JS host
+ * (i.e. mobile via react-native-bare-kit Worklet), `process.exit()` would
+ * kill the entire app. This path runs the same registry/model cleanup as
+ * `shutdownBareDirectWorker` but skips the lock release + exit, leaving the
+ * caller (typically the SDK client about to call `worklet.terminate()`)
+ * responsible for tearing the worker down.
+ *
+ * Critical for clean termination: addons hold static state with js_ref_t
+ * handles into the current V8 isolate; without this cleanup, those refs
+ * survive into the next worklet's isolate and crash on first access.
+ */
+export declare function cleanupForTerminate(): Promise<void>;
 export declare function shutdownBareDirectWorker(reason: BareDirectShutdownReason): Promise<void>;
 //# sourceMappingURL=worker-core.d.ts.map

package/dist/server/worker-core.js

@@ -9,10 +9,43 @@ import { closeRegistryClient } from "./bare/registry/registry-client.js";
 import { clearAllLoggingStreams, startLogBuffering, } from "./bare/registry/logging-stream-registry.js";
 import { clearAllAddonLoggers, getServerLogger, SDK_LOG_ID } from "../logging/index.js";
 import { clearPlugins } from "./plugins/index.js";
+import { acquireWorkerLock, releaseWorkerLock, } from "./utils/worker-lock.js";
 let coreInitialized = false;
 let rpcInitialized = false;
+// Set true when the cleanup body has run at least once. Lets both
+// cleanupForTerminate (pre-terminate path) and shutdownBareDirectWorker
+// (signal/exit path) call runCleanup() without doing duplicate work.
+let cleanupRan = false;
+// Set true when shutdownBareDirectWorker is in flight. Distinct from
+// cleanupRan: cleanupForTerminate must NOT set this, otherwise a later
+// SIGTERM/SIGINT/uncaught-exception would early-return at the guard
+// in shutdownBareDirectWorker and skip releaseWorkerLock + process.exit.
 let isShuttingDown = false;
 const logger = getServerLogger();
+// Defense-in-depth grace period for the SIGKILL safety net armed before
+// process.exit() in shutdownBareDirectWorker. If process.exit cannot
+// terminate the worker within this window — typically because some path
+// holds a non-cancellable native handle (e.g. a libuv worker thread
+// blocked on flock; see QVAC-18197) — we force-kill the OS process to
+// guarantee bounded shutdown time.
+const FORCE_EXIT_GRACE_MS = 3_000;
+function scheduleForceExit() {
+    const timer = setTimeout(() => {
+        logger.error(`process.exit did not terminate the worker within ${FORCE_EXIT_GRACE_MS}ms — ` +
+            `force-killing self (likely blocked native handle)`);
+        try {
+            process.kill(process.pid, "SIGKILL");
+        }
+        catch {
+            // best-effort — if SIGKILL itself fails, there's nothing more to do
+        }
+    }, FORCE_EXIT_GRACE_MS);
+    // Don't let the safety-net timer keep the process alive on the happy
+    // path. Bare returns an object (not a number) from setTimeout.
+    if (timer && typeof timer === "object" && "unref" in timer) {
+        timer.unref();
+    }
+}
 export function initializeWorkerCore() {
     if (coreInitialized) {
         const validatedEnv = getValidatedEnv();
@@ -20,6 +53,7 @@ export function initializeWorkerCore() {
     }
     startLogBuffering(SDK_LOG_ID);
     const { hasRPCConfig } = initEnv();
+    acquireWorkerLock();
     setupShutdownHandlers();
     coreInitialized = true;
     logger.debug("Worker core initialized");
@@ -37,7 +71,9 @@ export function ensureRPCSetup() {
         const ipcSocketPath = validatedEnv.QVAC_IPC_SOCKET_PATH;
         if (ipcSocketPath) {
             logger.info(`Running in desktop mode, connecting to IPC socket: ${ipcSocketPath}`);
-            const rpc = createIPCClient(ipcSocketPath);
+            const rpc = createIPCClient(ipcSocketPath, {
+                onDisconnect: () => void shutdownBareDirectWorker("ipc-disconnect"),
+            });
             logger.debug("Desktop IPC client created?", !!rpc);
         }
         else {
@@ -61,31 +97,95 @@ function clearRegistries() {
     clearAllAddonLoggers();
     clearPlugins();
 }
+/**
+ * Run the cleanup body shared by terminal and graceful-shutdown paths.
+ * Clears plugin registries (which calls each addon's `releaseLogger` →
+ * frees env-bound js_ref_t state), unloads all loaded models (which calls
+ * each addon's `destroyInstance`), and closes infra (swarm, rag, downloads,
+ * registry client). Does NOT touch the worker lock or call `process.exit`.
+ *
+ * Idempotent: subsequent calls are no-ops via the `cleanupRan` flag. The
+ * underlying clearPlugins / unloadAllModels / closers are also idempotent
+ * on empty registries, but the flag avoids the redundant log noise and
+ * allocator churn.
+ */
+async function runCleanup() {
+    if (cleanupRan)
+        return;
+    cleanupRan = true;
+    clearRegistries();
+    await Promise.allSettled([
+        destroySwarm(),
+        closeAllRagInstances(),
+        cleanupDownloads(),
+        unloadAllModels(),
+        closeRegistryClient(),
+    ]);
+}
+/**
+ * Pre-terminate cleanup, callable while the worker is still alive.
+ *
+ * On platforms where the worker lives in the same OS process as the JS host
+ * (i.e. mobile via react-native-bare-kit Worklet), `process.exit()` would
+ * kill the entire app. This path runs the same registry/model cleanup as
+ * `shutdownBareDirectWorker` but skips the lock release + exit, leaving the
+ * caller (typically the SDK client about to call `worklet.terminate()`)
+ * responsible for tearing the worker down.
+ *
+ * Critical for clean termination: addons hold static state with js_ref_t
+ * handles into the current V8 isolate; without this cleanup, those refs
+ * survive into the next worklet's isolate and crash on first access.
+ */
+export async function cleanupForTerminate() {
+    // Intentionally does NOT set isShuttingDown — that flag is reserved for
+    // shutdownBareDirectWorker so a later SIGTERM/SIGINT still gets to run
+    // the lock release + process.exit path. runCleanup is idempotent on its
+    // own, so a follow-up shutdownBareDirectWorker call won't redo the body.
+    if (cleanupRan)
+        return;
+    logger.info("🧹 Pre-terminate cleanup starting...");
+    try {
+        await runCleanup();
+        logger.info("✅ Pre-terminate cleanup completed");
+    }
+    catch (error) {
+        logger.error("❌ Error during pre-terminate cleanup:", error);
+    }
+}
 export async function shutdownBareDirectWorker(reason) {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
-    const message = reason === "signal"
-        ? "🐻 Bare worker shutdown signal received, cleaning up..."
-        : "🧹 Bare direct mode RPC closed, cleaning up...";
-    logger.info(message);
+    const messages = {
+        signal: "🐻 Bare worker shutdown signal received, cleaning up...",
+        "rpc-close": "🧹 Bare direct mode RPC closed, cleaning up...",
+        "uncaught-exception": "💥 Uncaught exception, cleaning up...",
+        "unhandled-rejection": "💥 Unhandled rejection, cleaning up...",
+        "ipc-disconnect": "🔌 Parent IPC disconnected, cleaning up...",
+    };
+    logger.info(messages[reason]);
     try {
-        clearRegistries();
-        await Promise.allSettled([
-            destroySwarm(),
-            closeAllRagInstances(),
-            cleanupDownloads(),
-            unloadAllModels(),
-            closeRegistryClient(),
-        ]);
+        // Idempotent: if cleanupForTerminate already ran, this is a no-op.
+        await runCleanup();
         logger.info("✅ Cleanup completed successfully");
     }
     catch (error) {
         logger.error("❌ Error during shutdown cleanup:", error);
     }
-    process.exit(0);
+    releaseWorkerLock();
+    scheduleForceExit();
+    const isGraceful = reason === "signal" || reason === "rpc-close";
+    process.exit(isGraceful ? 0 : 1);
 }
 function setupShutdownHandlers() {
     process.once("SIGTERM", () => void shutdownBareDirectWorker("signal"));
     process.once("SIGINT", () => void shutdownBareDirectWorker("signal"));
+    process.on("uncaughtException", (err) => {
+        logger.error("Uncaught exception in worker:", err);
+        void shutdownBareDirectWorker("uncaught-exception");
+    });
+    process.on("unhandledRejection", (reason) => {
+        logger.error("Unhandled rejection in worker:", reason);
+        void shutdownBareDirectWorker("unhandled-rejection");
+    });
 }

package/dist/utils/aggregate-events.d.ts

@@ -0,0 +1,16 @@
+import type { CompletionError, CompletionEvent, CompletionFinal, CompletionStats, ToolCall } from "../schemas/index";
+import { type ToolHandlerMap } from "./tool-helpers";
+export type AggregatedEvents = {
+    contentText: string;
+    thinkingText: string;
+    stats: CompletionStats | undefined;
+    toolCalls: ToolCall[];
+    rawFullText: string | undefined;
+    error: CompletionError | undefined;
+};
+export declare function aggregateEvents(events: CompletionEvent[]): AggregatedEvents;
+export declare function buildFinalFromEvents(events: CompletionEvent[], handlers: ToolHandlerMap): {
+    final: CompletionFinal;
+    error: CompletionError | undefined;
+};
+//# sourceMappingURL=aggregate-events.d.ts.map

package/dist/utils/aggregate-events.js

@@ -0,0 +1,52 @@
+import { normalizeAssistantCacheContent } from "./cache-normalize.js";
+import { attachHandlersToToolCalls, } from "./tool-helpers.js";
+export function aggregateEvents(events) {
+    let contentText = "";
+    let thinkingText = "";
+    let stats;
+    let rawFullText;
+    let error;
+    const toolCalls = [];
+    for (const event of events) {
+        if (event.type === "contentDelta") {
+            contentText += event.text;
+        }
+        else if (event.type === "thinkingDelta") {
+            thinkingText += event.text;
+        }
+        else if (event.type === "completionStats") {
+            stats = event.stats;
+        }
+        else if (event.type === "toolCall") {
+            toolCalls.push(event.call);
+        }
+        else if (event.type === "completionDone") {
+            if ("raw" in event && event.raw) {
+                rawFullText = event.raw.fullText;
+            }
+            if (event.stopReason === "error" && "error" in event) {
+                error = event.error;
+            }
+        }
+    }
+    return { contentText, thinkingText, stats, toolCalls, rawFullText, error };
+}
+export function buildFinalFromEvents(events, handlers) {
+    const { contentText, thinkingText, stats, toolCalls, rawFullText, error } = aggregateEvents(events);
+    const attachedToolCalls = attachHandlersToToolCalls(toolCalls, handlers);
+    const fullText = rawFullText ?? contentText;
+    const cacheableAssistantContent = attachedToolCalls.length === 0
+        ? normalizeAssistantCacheContent(fullText)
+        : undefined;
+    const final = {
+        contentText,
+        ...(thinkingText && { thinkingText }),
+        toolCalls: attachedToolCalls,
+        ...(stats && { stats }),
+        raw: { fullText },
+        ...(cacheableAssistantContent !== undefined && {
+            cacheableAssistantContent,
+        }),
+    };
+    return { final, error };
+}

package/dist/utils/cache-normalize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonicalize assistant message text for the auto-cache key.
+ *
+ * The server saves raw stream text (with think tags when `captureThinking` is
+ * on), while `final.contentText` only aggregates `contentDelta` events.
+ * Stripping think blocks (paired and unclosed-trailing) and trimming lets
+ * callers push back either shape and still hit the cache.
+ */
+export declare function normalizeAssistantCacheContent(content: string): string;
+//# sourceMappingURL=cache-normalize.d.ts.map