@qvac/sdk 0.9.2 → 0.10.0

package/dist/server/bare/plugins/llamacpp-completion/ops/completion-stream.js

@@ -1,19 +1,46 @@
+import { TOOLS_MODE } from "../../../../../schemas/tools.js";
 import { logCacheDisabled, logCacheInit, logCacheSave, logCacheSaveError, logCacheStatus, logMessagesToAddon, } from "./cache-logger.js";
-import { customCacheExists, extractSystemPrompt, findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, markCacheInitialized, renameCacheFile, } from "../../../ops/kv-cache-utils.js";
+import { clearCacheRegistry, customCacheExists, extractSystemPrompt, findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, markCacheInitialized, renameCacheFile, } from "../../../ops/kv-cache-utils.js";
 import { getModel, getModelConfig, } from "../../../registry/model-registry.js";
-import { checkForToolEvents, insertToolsIntoHistory, setupToolGrammar, } from "../../../../utils/tool-integration.js";
-import { parseToolCalls } from "../../../../utils/tool-parser.js";
+import { cachedMessageCounts, clearCachedMessageCounts as clearCachedMessageCountsFromState, decideCachedHistorySlice, noteCancelRequested as noteCancelRequestedFromState, shouldRecordSavedCount, snapshotCancelCount, } from "./kv-cache-state.js";
+import { appendToolsToHistory, detectToolDialect, prependToolsToHistory, } from "../../../../utils/tool-integration.js";
+import { parseToolCalls } from "../../../../utils/tools/index.js";
+import { getResponseFormatJsonSchema } from "../../../../utils/response-format.js";
+import { buildAutoCacheSaveHistory } from "../../../../utils/index.js";
+import { getServerLogger } from "../../../../../logging/index.js";
 import { AttachmentNotFoundError } from "../../../../../utils/errors-server.js";
 import { nowMs } from "../../../../../profiling/index.js";
 import { buildStreamResult, hasDefinedValues, } from "../../../../../profiling/model-execution.js";
-import fs from "bare-fs";
-const cachedMessageCounts = new Map();
-export function clearCachedMessageCounts(cachePath) {
-    if (cachePath) {
-        cachedMessageCounts.delete(cachePath);
+import fs, { promises as fsPromises } from "bare-fs";
+import path from "bare-path";
+const logger = getServerLogger();
+// Re-export so existing callers keep their import surface intact. The pure
+// state module has no `bare-*` imports, so we inject the platform path
+// separator here — without this, prefix-based clears would miss entries
+// under directory keys on Windows.
+export function clearCachedMessageCounts(prefix) {
+    clearCachedMessageCountsFromState(prefix, path.sep);
+}
+export const noteCancelRequested = noteCancelRequestedFromState;
+// Verify the addon actually persisted the cache file before recording its
+// message count. The addon currently swallows write errors silently, so a
+// missing file means the next turn must resend the full history rather than
+// slicing against a stale `savedCount`.
+//
+// TODO: once the addon surfaces save failures (e.g. throws
+// `UnableToSaveSessionFile` when `llama_state_save_file` returns false),
+// drop the `access()` probe and wrap the `model.run()` call in a real
+// try/catch that forwards the error to `logCacheSaveError`.
+async function recordCacheSaveCount(cachePath, messageCount) {
+    try {
+        await fsPromises.access(cachePath);
+        cachedMessageCounts.set(cachePath, messageCount);
+        return true;
     }
-    else {
-        cachedMessageCounts.clear();
+    catch (err) {
+        cachedMessageCounts.delete(cachePath);
+        logCacheSaveError(cachePath, err);
+        return false;
     }
 }
 function transformMessage(message) {
@@ -47,6 +74,10 @@ function transformMessage(message) {
     });
     return transformed;
 }
+function runModel(model, prompt, opts) {
+    const run = model.run.bind(model);
+    return run(prompt, opts);
+}
 function transformMessages(messages) {
     const transformed = [];
     for (const message of messages) {
@@ -56,7 +87,6 @@ function transformMessages(messages) {
 }
 async function initSystemPromptCache(model, cachePathToUse, systemPromptToUse, cacheKey, tools) {
     const primeMessages = [
-        { role: "session", content: cachePathToUse },
         { role: "system", content: systemPromptToUse },
     ];
     let toolCount = 0;
@@ -67,76 +97,115 @@ async function initSystemPromptCache(model, cachePathToUse, systemPromptToUse, c
     }
     logCacheInit(cacheKey, systemPromptToUse, toolCount);
     logMessagesToAddon(primeMessages, "CACHE_INIT");
-    const primeResponse = await model.run(primeMessages);
+    const primeResponse = await runModel(model, primeMessages, {
+        cacheKey: cachePathToUse,
+        saveCacheToDisk: true,
+    });
     primeResponse.once("output", () => {
         void primeResponse.cancel();
     });
     await primeResponse.await();
 }
-function prepareMessagesForCache(cachePathToUse, cacheExists, history) {
-    if (cacheExists && history.length > 0) {
+/**
+ * Pick the messages that need to reach the model for the next turn.
+ *
+ * Static mode (no `tools` argument):
+ *   - Cache miss: send the whole history minus the system message (which
+ *     was primed during cache init).
+ *   - Cache hit with a recorded `savedCount`: send only the unsaved tail
+ *     (`history.slice(savedCount)`), so a multi-message turn (e.g. a
+ *     consumer pushing both an assistant transcript and a follow-up user
+ *     message between completions) all reaches the model.
+ *   - Cache hit with a stale/missing `savedCount`: fall back to the full
+ *     non-system history.
+ *
+ * Dynamic mode (`tools` argument set):
+ *   - The addon anchors the tool block after the last user message and
+ *     trims tools + the assistant's tool-call output from the cache once
+ *     the chain resolves. After that trim, the cache only holds messages
+ *     up to the last user turn, so the SDK has to ship the right slice
+ *     plus the (possibly new) tool set:
+ *       * tool-chain continuation (last role is "tool"): send the trailing
+ *         consecutive tool messages, no tool block — tools are still
+ *         anchored in the cache from the previous round.
+ *       * new user turn after a chain (prev role is "assistant"): send
+ *         [assistant, user] so the model sees its own final reply before
+ *         the new prompt, then re-anchor the tool block.
+ *       * otherwise: send just the last message + tool block.
+ */
+function prepareMessagesForCache(cachePathToUse, cacheExists, history, tools) {
+    const addTools = tools?.length ? transformMessages(tools) : [];
+    const dynamic = addTools.length > 0;
+    if (!(cacheExists && history.length > 0)) {
+        const historyWithoutSystem = history.filter((msg) => msg.role !== "system");
+        return [...transformMessages(historyWithoutSystem), ...addTools];
+    }
+    if (!dynamic) {
+        // Static path — slice from the recorded `savedCount` so callers can
+        // stage multiple messages between completions. `decideCachedHistorySlice`
+        // also guards against the QVAC-17780 stale-count regression: if the
+        // saved boundary would slice the history down to an empty payload
+        // (e.g. after a cancelled mid-decode), it falls back to the full
+        // non-system history and signals the caller to drop the bad entry.
         const savedCount = cachedMessageCounts.get(cachePathToUse) ?? 0;
-        const canSlice = savedCount > 0 && savedCount <= history.length;
-        const newMessages = canSlice
-            ? history.slice(savedCount)
-            : history.filter((msg) => msg.role !== "system");
-        if (!canSlice && savedCount > 0) {
+        const { messages, clearStaleCount } = decideCachedHistorySlice(savedCount, cacheExists, history);
+        if (clearStaleCount) {
             cachedMessageCounts.delete(cachePathToUse);
         }
-        const transformedNewMessages = transformMessages(newMessages);
-        return [
-            { role: "session", content: cachePathToUse },
-            ...transformedNewMessages,
-        ];
-    }
-    const historyWithoutSystem = history.filter((msg) => msg.role !== "system");
-    const transformedHistoryWithoutSystem = transformMessages(historyWithoutSystem);
-    return [
-        { role: "session", content: cachePathToUse },
-        ...transformedHistoryWithoutSystem,
-    ];
+        return transformMessages(messages);
+    }
+    // Dynamic path. The addon trimmed tools after the previous round, so the
+    // cache no longer holds the saved-count we'd rely on for slicing — pick
+    // the right fragment based on the role of the last history message.
+    const lastMsg = history[history.length - 1];
+    if (lastMsg.role === "tool") {
+        const trailingTools = [];
+        for (let i = history.length - 1; i >= 0; i--) {
+            const msg = history[i];
+            if (msg.role !== "tool")
+                break;
+            trailingTools.unshift(msg);
+        }
+        return transformMessages(trailingTools);
+    }
+    if (lastMsg.role === "user") {
+        const prevMsg = history[history.length - 2];
+        const tail = prevMsg?.role === "assistant" ? [prevMsg, lastMsg] : [lastMsg];
+        return [...transformMessages(tail), ...addTools];
+    }
+    return [...transformMessages([lastMsg]), ...addTools];
 }
-async function* processModelResponse(model, messagesToSend, shouldSaveCache, tools, generationParams) {
-    const runFn = model.run.bind(model);
-    const runOptions = generationParams ? { generationParams } : undefined;
+async function* processModelResponse(model, messagesToSend, tools, generationParams, cacheOptions, dialect) {
+    const runOptions = {
+        ...(generationParams && { generationParams }),
+        ...(cacheOptions?.cacheKey !== undefined && {
+            cacheKey: cacheOptions.cacheKey,
+        }),
+        ...(cacheOptions?.saveCacheToDisk !== undefined && {
+            saveCacheToDisk: cacheOptions.saveCacheToDisk,
+        }),
+    };
+    const hasRunOptions = Object.keys(runOptions).length > 0;
     const modelStart = nowMs();
-    const response = await runFn(messagesToSend, runOptions);
+    const response = await runModel(model, messagesToSend, hasRunOptions ? runOptions : undefined);
     let accumulatedText = "";
-    const emittedToolCallPositions = new Set();
+    let producedTokens = false;
     let toolCallsResult = [];
     for await (const token of response.iterate()) {
         const tokenStr = token;
+        if (tokenStr.length > 0)
+            producedTokens = true;
         accumulatedText += tokenStr;
         yield { token: tokenStr };
-        if (tools && tools.length > 0) {
-            const toolEvents = checkForToolEvents(accumulatedText, tokenStr, tools, emittedToolCallPositions);
-            for (const toolEvent of toolEvents) {
-                yield { token: "", toolCallEvent: toolEvent };
-            }
-        }
     }
     const modelExecutionMs = nowMs() - modelStart;
+    if (cacheOptions?.saveCacheToDisk && cacheOptions.cacheKey) {
+        logCacheSave(cacheOptions.cacheKey);
+    }
     if (tools && tools.length > 0) {
-        const { toolCalls } = parseToolCalls(accumulatedText, tools);
+        const { toolCalls } = parseToolCalls(accumulatedText, tools, dialect);
         toolCallsResult = toolCalls;
     }
-    if (shouldSaveCache) {
-        const sessionMsg = messagesToSend.find((m) => m.role === "session");
-        if (sessionMsg?.content) {
-            logCacheSave(sessionMsg.content);
-            const cachePath = sessionMsg.content;
-            const saveResp = await model.run([
-                { role: "session", content: cachePath },
-                { role: "session", content: "save" },
-            ]);
-            try {
-                await saveResp.await();
-            }
-            catch (err) {
-                logCacheSaveError(cachePath, err);
-            }
-        }
-    }
     const responseWithStats = response;
     const stats = {
         ...(responseWithStats.stats?.TTFT !== undefined && {
@@ -148,6 +217,9 @@ async function* processModelResponse(model, messagesToSend, shouldSaveCache, too
         ...(responseWithStats.stats?.CacheTokens !== undefined && {
             cacheTokens: responseWithStats.stats.CacheTokens,
         }),
+        ...(responseWithStats.stats?.generatedTokens !== undefined && {
+            generatedTokens: responseWithStats.stats.generatedTokens,
+        }),
         ...(responseWithStats.stats?.backendDevice !== undefined && {
             backendDevice: responseWithStats.stats.backendDevice,
         }),
@@ -155,23 +227,44 @@ async function* processModelResponse(model, messagesToSend, shouldSaveCache, too
     return {
         ...buildStreamResult(modelExecutionMs, hasDefinedValues(stats) ? stats : undefined),
         toolCalls: toolCallsResult,
+        responseText: accumulatedText,
+        producedTokens,
     };
 }
 export async function* completion(params) {
-    const { history, modelId, kvCache, tools, generationParams } = params;
+    const { history, modelId, kvCache, tools, generationParams, responseFormat } = params;
     const modelConfig = getModelConfig(modelId);
     const toolsEnabled = modelConfig.tools === true;
-    let historyWithTools = history;
-    if (tools && tools.length > 0 && toolsEnabled) {
-        historyWithTools = insertToolsIntoHistory(history, tools);
-        setupToolGrammar(modelConfig, tools);
+    const toolsMode = modelConfig.toolsMode;
+    const dynamicTools = !!tools?.length && toolsEnabled && toolsMode === TOOLS_MODE.dynamic;
+    const staticTools = !!tools?.length && toolsEnabled && !dynamicTools;
+    const dialect = tools && tools.length > 0
+        ? (params.toolDialect ?? detectToolDialect(modelId))
+        : undefined;
+    // `responseFormat` is forwarded to the addon as a per-request
+    // `generationParams.json_schema`, which the addon converts to GBNF and
+    // applies for the duration of the request only. This avoids mutating
+    // the shared `modelConfig` and is therefore safe under concurrent
+    // completions on the same model. `tools` still constrain output through
+    // their parameter schema and the dialect-specific parser chain (mutually
+    // exclusive with a non-text `responseFormat` at the schema layer).
+    let mergedGenerationParams = generationParams;
+    if (responseFormat && !(tools && tools.length > 0)) {
+        const jsonSchema = getResponseFormatJsonSchema(responseFormat);
+        if (jsonSchema !== undefined) {
+            mergedGenerationParams = {
+                ...(generationParams ?? {}),
+                json_schema: jsonSchema,
+            };
+        }
     }
-    const transformedHistory = transformMessages(historyWithTools);
     const model = getModel(modelId);
     if (kvCache) {
-        const modelConfig = getModelConfig(modelId);
         const systemPromptFromHistory = extractSystemPrompt(history);
-        const configHash = generateConfigHash(systemPromptFromHistory, tools);
+        // Dynamic mode lets each turn carry its own tool set, so the cache
+        // hash must not depend on the tool list — otherwise a tool change
+        // would force a fresh cache file and defeat the whole optimisation.
+        const configHash = generateConfigHash(systemPromptFromHistory, dynamicTools ? undefined : tools);
         const systemPromptToUse = systemPromptFromHistory ||
             modelConfig.system_prompt ||
             "You are a helpful assistant.";
@@ -181,14 +274,43 @@ export async function* completion(params) {
             let cacheExists = await customCacheExists(modelId, configHash, kvCache);
             logCacheStatus(kvCache, cacheExists);
             if (!cacheExists) {
-                await initSystemPromptCache(model, cachePathToUse, systemPromptToUse, kvCache, tools && toolsEnabled ? tools : undefined);
+                await initSystemPromptCache(model, cachePathToUse, systemPromptToUse, kvCache, 
+                // Static-mode tools are baked into the system-prompt cache so
+                // they're shared across the session. Dynamic-mode tools belong
+                // to a per-turn anchor and must not enter the system cache.
+                staticTools ? tools : undefined);
                 markCacheInitialized(modelId, configHash, kvCache);
                 cacheExists = true;
             }
-            const messagesToSend = prepareMessagesForCache(cachePathToUse, cacheExists, history);
+            const messagesToSend = prepareMessagesForCache(cachePathToUse, cacheExists, history, dynamicTools ? tools : undefined);
             logMessagesToAddon(messagesToSend, "PROMPT_SEND");
-            const result = yield* processModelResponse(model, messagesToSend, true, tools, generationParams);
-            cachedMessageCounts.set(cachePathToUse, history.length + 1);
+            const cancelCountBefore = snapshotCancelCount(modelId);
+            const result = yield* processModelResponse(model, messagesToSend, tools, mergedGenerationParams, { cacheKey: cachePathToUse, saveCacheToDisk: true }, dialect);
+            const wasCancelled = snapshotCancelCount(modelId) > cancelCountBefore;
+            if (shouldRecordSavedCount(wasCancelled, result.producedTokens)) {
+                // Turn ran to completion and produced content — record the new
+                // boundary so the next turn can slice its history.
+                await recordCacheSaveCount(cachePathToUse, history.length + 1);
+            }
+            else {
+                // The addon writes the cache file unconditionally on
+                // `saveCacheToDisk` turns, including cancellations and zero-token
+                // exits, so what's left on disk holds partial decode state that
+                // does not correspond to a clean turn boundary. Mirror the
+                // auto-key handling: drop the file, clear the in-memory init
+                // flag (otherwise `customCacheExists` would still report true),
+                // and forget the saved count. Next turn re-primes the system
+                // prompt cleanly — a one-turn perf hit, but no risk of the
+                // addon loading the stale KV state.
+                try {
+                    await fsPromises.unlink(cachePathToUse);
+                }
+                catch (unlinkError) {
+                    logger.warn(`[kv-cache] Failed to remove cache file after cancelled or empty custom-key turn; next turn may load stale KV state. path=${cachePathToUse} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+                }
+                clearCacheRegistry({ cacheKey: kvCache, modelId });
+                cachedMessageCounts.delete(cachePathToUse);
+            }
             return result;
         }
         else {
@@ -199,34 +321,84 @@ export async function* completion(params) {
                 attachments: msg.attachments ?? undefined,
             }));
             const existingCache = await findMatchingCache(modelId, configHash, cacheMessages);
-            const currentCacheInfo = await getCurrentCacheInfo(modelId, configHash, cacheMessages);
+            const preResponseCacheInfo = await getCurrentCacheInfo(modelId, configHash, cacheMessages);
             cachePathToUse =
                 existingCache !== null
                     ? existingCache.cachePath
-                    : currentCacheInfo.cachePath;
+                    : preResponseCacheInfo.cachePath;
             let cacheExists = existingCache !== null;
             logCacheStatus("auto", cacheExists);
             if (!cacheExists) {
-                await initSystemPromptCache(model, cachePathToUse, systemPromptToUse, "auto", tools && toolsEnabled ? tools : undefined);
-                markCacheInitialized(modelId, configHash, currentCacheInfo.cacheKey);
+                await initSystemPromptCache(model, cachePathToUse, systemPromptToUse, "auto", staticTools ? tools : undefined);
+                markCacheInitialized(modelId, configHash, preResponseCacheInfo.cacheKey);
                 cacheExists = true;
             }
-            const messagesToSend = prepareMessagesForCache(cachePathToUse, cacheExists, history);
+            const messagesToSend = prepareMessagesForCache(cachePathToUse, cacheExists, history, dynamicTools ? tools : undefined);
             logMessagesToAddon(messagesToSend, "PROMPT_SEND");
-            const result = yield* processModelResponse(model, messagesToSend, true, tools, generationParams);
-            cachedMessageCounts.set(cachePathToUse, history.length + 1);
-            if (existingCache !== null &&
-                existingCache.cachePath !== currentCacheInfo.cachePath) {
-                cachedMessageCounts.delete(existingCache.cachePath);
-                cachedMessageCounts.set(currentCacheInfo.cachePath, history.length + 1);
-                await renameCacheFile(existingCache.cachePath, currentCacheInfo.cachePath);
+            const cancelCountBefore = snapshotCancelCount(modelId);
+            const result = yield* processModelResponse(model, messagesToSend, tools, mergedGenerationParams, { cacheKey: cachePathToUse, saveCacheToDisk: true }, dialect);
+            const wasCancelled = snapshotCancelCount(modelId) > cancelCountBefore;
+            // TODO: support auto-cache for tool-call turns by keying off the
+            // structured assistant/tool messages callers push into history,
+            // not result.responseText (which is raw tool-call markup here).
+            // Until then, remove any cache file the addon wrote so it doesn't
+            // leak on disk (the next turn would compute a different key and
+            // never reach it).
+            if (result.toolCalls.length > 0) {
+                logger.warn(`[kv-cache] Auto cache tool-call turn; removing orphaned cache to avoid disk leak. path=${cachePathToUse}`);
+                try {
+                    await fsPromises.unlink(cachePathToUse);
+                }
+                catch (unlinkError) {
+                    logger.warn(`[kv-cache] Failed to remove orphaned tool-turn cache file; disk leak likely. path=${cachePathToUse} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+                }
+                cachedMessageCounts.delete(cachePathToUse);
+                return result;
+            }
+            // A cancelled or zero-token turn cannot be promoted to a post-response
+            // cache: the post-response key is derived from `result.responseText`,
+            // which is empty/partial in those cases, and the on-disk cache the
+            // addon wrote is not aligned with the current-history hash. Treat it
+            // like the tool-call branch — drop the cache file and clear the count.
+            if (!shouldRecordSavedCount(wasCancelled, result.producedTokens)) {
+                try {
+                    await fsPromises.unlink(cachePathToUse);
+                }
+                catch (unlinkError) {
+                    logger.warn(`[kv-cache] Failed to remove cache file after cancelled or empty turn; disk leak possible. path=${cachePathToUse} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+                }
+                cachedMessageCounts.delete(cachePathToUse);
+                return result;
+            }
+            const savedHistory = buildAutoCacheSaveHistory(cacheMessages, result.responseText);
+            const postResponseCacheInfo = await getCurrentCacheInfo(modelId, configHash, savedHistory);
+            if (!(await renameCacheFile(cachePathToUse, postResponseCacheInfo.cachePath))) {
+                logger.warn(`[kv-cache] Auto cache rename failed; removing stale cache to avoid disk leak. from=${cachePathToUse} to=${postResponseCacheInfo.cachePath}`);
+                try {
+                    await fsPromises.unlink(cachePathToUse);
+                }
+                catch (unlinkError) {
+                    logger.warn(`[kv-cache] Failed to remove stale cache file; disk leak likely. path=${cachePathToUse} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+                }
+                cachedMessageCounts.delete(cachePathToUse);
+                return result;
             }
+            cachedMessageCounts.delete(cachePathToUse);
+            await recordCacheSaveCount(postResponseCacheInfo.cachePath, savedHistory.length);
             return result;
         }
     }
     else {
+        let historyWithTools = history;
+        if (staticTools && tools) {
+            historyWithTools = prependToolsToHistory(history, tools);
+        }
+        else if (dynamicTools && tools) {
+            historyWithTools = appendToolsToHistory(history, tools);
+        }
+        const transformedHistory = transformMessages(historyWithTools);
         logCacheDisabled();
         logMessagesToAddon(transformedHistory, "NO_CACHE");
-        return yield* processModelResponse(model, transformedHistory, false, tools, generationParams);
+        return yield* processModelResponse(model, transformedHistory, tools, mergedGenerationParams, undefined, dialect);
     }
 }

package/dist/server/bare/plugins/llamacpp-completion/ops/kv-cache-state.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure state + decision helpers for kv-cache bookkeeping used by
+ * `completion-stream.ts`.
+ *
+ * This module intentionally has **no** `bare-*` imports so it can be
+ * exercised directly from unit tests running under `bun` without pulling
+ * in the Bare runtime (which is not available in that environment).
+ * The file-system-dependent pieces (e.g. `recordCacheSaveCount`) live in
+ * `completion-stream.ts` and consume the state exported here.
+ */
+/**
+ * Number of chat messages the kv-cache file on disk is known to cover, keyed
+ * by cache path. Written after a successful completion records a save, read
+ * by `prepareMessagesForCache` to slice the history on the next turn so a
+ * consumer can stage multiple messages between completions (e.g. an
+ * `[assistant, user]` recovery sequence) without resending the whole history.
+ *
+ * INVARIANT: an entry is only present if the corresponding kv-cache file is
+ * considered trustworthy. On any turn where the SDK cannot prove the saved
+ * count reflects the on-disk state (cancellation mid-decode, zero-token
+ * reply, cache file missing after a save attempt), the entry MUST be
+ * deleted; a stale entry causes the next turn to slice its history down to
+ * an empty payload and the model returns zero tokens.
+ *
+ * Mode notes:
+ *   - Static-mode turns are the only readers of this map. `clearStaleCount`
+ *     in `decideCachedHistorySlice` exists so a stale-but-non-zero entry
+ *     can be detected and dropped on the next read.
+ *   - Dynamic-mode turns do NOT consume this map — the addon trims tools
+ *     and the chain output from the kv-cache after each round, so the
+ *     SDK falls back to role-based dispatch in `prepareMessagesForCache`.
+ *     Writes still happen on dynamic-mode turns, but the recorded count
+ *     reflects the messages the SDK shipped, not the (possibly trimmed)
+ *     on-disk cache shape. The map is internally consistent within a
+ *     single mode; a `kvCache` key should not be reused across modes.
+ */
+export declare const cachedMessageCounts: Map<string, number>;
+/**
+ * Clear bookkeeping entries. With no argument, clears the whole map. With a
+ * `prefix`, removes any entry whose path is equal to it OR sits beneath it
+ * as a directory (i.e. `key.startsWith(prefix + sep)`).
+ *
+ * Runtime callers MUST pass the platform path separator (e.g. `path.sep`
+ * from `bare-path`) so directory-prefix matches are correct on every
+ * target. The "/" default exists only for unit tests under `bun`, where
+ * cache paths are POSIX-shaped and importing `bare-path` would pull in
+ * the Bare runtime. The exported wrapper in `completion-stream.ts`
+ * injects the real separator for in-process use.
+ */
+export declare function clearCachedMessageCounts(prefix?: string, sep?: string): void;
+/**
+ * Called from `server/bare/ops/cancel.ts` right before `addon.cancel()` so
+ * that the in-flight `completion()` for this model can detect that its
+ * current turn is being cancelled and skip poisoning `cachedMessageCounts`
+ * with a `history.length + 1` entry that does not correspond to a real
+ * assistant reply.
+ */
+export declare function noteCancelRequested(modelId: string): void;
+export declare function snapshotCancelCount(modelId: string): number;
+/** Test-only. */
+export declare function _resetCancelCountersForTest(): void;
+/**
+ * A completion's `savedCount` should only be recorded when the turn ran to
+ * completion AND produced at least one token. Any other outcome —
+ * cancelled mid-decode, legitimate zero-token reply, or an early EOS — must
+ * clear the entry instead, because there is no guarantee that the kv-cache
+ * file on disk matches the `history.length + 1` boundary the SDK would
+ * otherwise record.
+ */
+export declare function shouldRecordSavedCount(wasCancelled: boolean, producedTokens: boolean): boolean;
+export interface HistoryMessage {
+    role: string;
+    content: string;
+    attachments?: {
+        path: string;
+    }[] | undefined;
+}
+export interface HistorySliceDecision {
+    /** Messages to send to the model on the next turn. */
+    messages: HistoryMessage[];
+    /**
+     * True when the decision path proves the current `savedCount` is stale
+     * and the caller should `cachedMessageCounts.delete(cachePath)` to avoid
+     * propagating the bad count to the next turn.
+     */
+    clearStaleCount: boolean;
+}
+/**
+ * Pure slice decision for `prepareMessagesForCache`.
+ *
+ * Mirrors the shape of the logic in `completion-stream.ts` but without
+ * calling `transformMessages` (which depends on `bare-fs` for attachment
+ * probing). Kept here so the decision can be unit-tested in isolation.
+ *
+ * The key regression guard: when a non-zero `savedCount` would slice the
+ * history down to an empty array, it is treated as stale — the caller
+ * falls back to sending the system-stripped full history rather than
+ * handing the model an empty payload.
+ */
+export declare function decideCachedHistorySlice(savedCount: number, cacheExists: boolean, history: HistoryMessage[]): HistorySliceDecision;
+//# sourceMappingURL=kv-cache-state.d.ts.map