@qvac/sdk 0.10.2 → 0.12.0

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

@@ -1,8 +1,9 @@
 import { TOOLS_MODE } from "../../../../../schemas/tools.js";
-import { logCacheDisabled, logCacheInit, logCacheSave, logCacheSaveError, logCacheStatus, logMessagesToAddon, } from "./cache-logger.js";
-import { clearCacheRegistry, customCacheExists, extractSystemPrompt, findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, markCacheInitialized, renameCacheFile, } from "../../../ops/kv-cache-utils.js";
+import { logCacheDisabled, logCacheInit, logCacheSave, logMessagesToAddon, } from "./cache-logger.js";
+import { extractSystemPrompt, getCurrentCacheInfo, } from "../../../ops/kv-cache-utils.js";
 import { getModel, getModelConfig, } from "../../../registry/model-registry.js";
-import { cachedMessageCounts, clearCachedMessageCounts as clearCachedMessageCountsFromState, decideCachedHistorySlice, noteCancelRequested as noteCancelRequestedFromState, shouldRecordSavedCount, snapshotCancelCount, } from "./kv-cache-state.js";
+import { decideCachedHistorySlice } from "./kv-cache-state.js";
+import { createKvCacheSession, generateConfigHash, } from "./kv-cache-session.js";
 import { appendToolsToHistory, detectToolDialect, prependToolsToHistory, } from "../../../../utils/tool-integration.js";
 import { parseToolCalls } from "../../../../utils/tools/index.js";
 import { getResponseFormatJsonSchema } from "../../../../utils/response-format.js";
@@ -11,37 +12,23 @@ 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, { promises as fsPromises } from "bare-fs";
-import path from "bare-path";
+import fs from "bare-fs";
 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;
-    }
-    catch (err) {
-        cachedMessageCounts.delete(cachePath);
-        logCacheSaveError(cachePath, err);
-        return false;
-    }
+/**
+ * Decide whether a completed turn earned the right to record its kv-cache
+ * boundary. A `savedCount` is only safe to write when the turn ran to
+ * completion AND produced at least one token — anything else (cancelled
+ * mid-decode, zero-token reply, early EOS) leaves the on-disk cache file
+ * in an unknown state relative to `history.length + 1`, and a stale entry
+ * would slice the next turn's history down to an empty payload.
+ *
+ * Replaces the pre-0.11.0 `shouldRecordSavedCount(wasCancelled, ...)` with
+ * a signal-driven check that reads directly from the request's
+ * `AbortSignal`. The local helper keeps the call sites in
+ * `completion-stream.ts` honest without importing the registry every time.
+ */
+function shouldCommitTurn(signal, producedTokens) {
+    return !signal.aborted && producedTokens;
 }
 function transformMessage(message) {
     const transformed = [];
@@ -100,9 +87,7 @@ async function initSystemPromptCache(model, cachePathToUse, systemPromptToUse, c
     const primeResponse = await runModel(model, primeMessages, {
         cacheKey: cachePathToUse,
         saveCacheToDisk: true,
-    });
-    primeResponse.once("output", () => {
-        void primeResponse.cancel();
+        prefill: true,
     });
     await primeResponse.await();
 }
@@ -117,7 +102,8 @@ async function initSystemPromptCache(model, cachePathToUse, systemPromptToUse, c
  *     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.
+ *     non-system history. The session is told (`dropStaleSavedCount`) so
+ *     the bad boundary doesn't propagate into the next turn.
  *
  * Dynamic mode (`tools` argument set):
  *   - The addon anchors the tool block after the last user message and
@@ -133,7 +119,7 @@ async function initSystemPromptCache(model, cachePathToUse, systemPromptToUse, c
  *         the new prompt, then re-anchor the tool block.
  *       * otherwise: send just the last message + tool block.
  */
-function prepareMessagesForCache(cachePathToUse, cacheExists, history, tools) {
+function prepareMessagesForCache(session, turn, cacheExists, history, tools) {
     const addTools = tools?.length ? transformMessages(tools) : [];
     const dynamic = addTools.length > 0;
     if (!(cacheExists && history.length > 0)) {
@@ -141,16 +127,18 @@ function prepareMessagesForCache(cachePathToUse, cacheExists, history, tools) {
         return [...transformMessages(historyWithoutSystem), ...addTools];
     }
     if (!dynamic) {
-        // Static path — slice from the recorded `savedCount` so callers can
+        // Static path — slice from the turn's `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 { messages, clearStaleCount } = decideCachedHistorySlice(savedCount, cacheExists, history);
+        // The session owns the entry; `dropStaleSavedCount` clears it
+        // without touching the on-disk file (the file is still trustworthy
+        // — only the boundary count is wrong).
+        const { messages, clearStaleCount } = decideCachedHistorySlice(turn.savedCount, cacheExists, history);
         if (clearStaleCount) {
-            cachedMessageCounts.delete(cachePathToUse);
+            session.dropStaleSavedCount(turn);
         }
         return transformMessages(messages);
     }
@@ -217,6 +205,9 @@ async function* processModelResponse(model, messagesToSend, tools, generationPar
         ...(responseWithStats.stats?.CacheTokens !== undefined && {
             cacheTokens: responseWithStats.stats.CacheTokens,
         }),
+        ...(responseWithStats.stats?.promptTokens !== undefined && {
+            promptTokens: responseWithStats.stats.promptTokens,
+        }),
         ...(responseWithStats.stats?.generatedTokens !== undefined && {
             generatedTokens: responseWithStats.stats.generatedTokens,
         }),
@@ -231,8 +222,10 @@ async function* processModelResponse(model, messagesToSend, tools, generationPar
         producedTokens,
     };
 }
-export async function* completion(params) {
+export async function* completion(params, opts) {
     const { history, modelId, kvCache, tools, generationParams, responseFormat } = params;
+    const { signal, scope } = opts;
+    const requestLogger = opts.logger ?? logger;
     const modelConfig = getModelConfig(modelId);
     const toolsEnabled = modelConfig.tools === true;
     const toolsMode = modelConfig.toolsMode;
@@ -259,136 +252,45 @@ export async function* completion(params) {
         }
     }
     const model = getModel(modelId);
-    if (kvCache) {
-        const systemPromptFromHistory = extractSystemPrompt(history);
-        // 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.";
-        let cachePathToUse;
-        if (typeof kvCache === "string") {
-            cachePathToUse = await getCacheFilePath(modelId, configHash, kvCache);
-            let cacheExists = await customCacheExists(modelId, configHash, kvCache);
-            logCacheStatus(kvCache, cacheExists);
-            if (!cacheExists) {
-                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, dynamicTools ? tools : undefined);
-            logMessagesToAddon(messagesToSend, "PROMPT_SEND");
-            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 {
-            // Auto-generate cache key based on conversation history
-            const cacheMessages = history.map((msg) => ({
-                role: msg.role,
-                content: msg.content,
-                attachments: msg.attachments ?? undefined,
-            }));
-            const existingCache = await findMatchingCache(modelId, configHash, cacheMessages);
-            const preResponseCacheInfo = await getCurrentCacheInfo(modelId, configHash, cacheMessages);
-            cachePathToUse =
-                existingCache !== null
-                    ? existingCache.cachePath
-                    : preResponseCacheInfo.cachePath;
-            let cacheExists = existingCache !== null;
-            logCacheStatus("auto", cacheExists);
-            if (!cacheExists) {
-                await initSystemPromptCache(model, cachePathToUse, systemPromptToUse, "auto", staticTools ? tools : undefined);
-                markCacheInitialized(modelId, configHash, preResponseCacheInfo.cacheKey);
-                cacheExists = true;
-            }
-            const messagesToSend = prepareMessagesForCache(cachePathToUse, cacheExists, history, dynamicTools ? tools : undefined);
-            logMessagesToAddon(messagesToSend, "PROMPT_SEND");
-            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;
+    // Hard-cancel wiring: when the registry aborts the request's signal,
+    // forward to the addon so the C++ work stops as soon as it can. The
+    // SDK still treats `signal.aborted` as the truth for cancel detection
+    // (post-completion bookkeeping below) — this listener only shortens
+    // the latency between "user clicked stop" and "addon stops decoding".
+    //
+    // Fire-and-forget by construction (event listeners can't `await`), but
+    // `addon.cancel()` returns a Promise — if it ever rejects the bare
+    // `void` would leak it as an unhandledRejection. Attach `.catch(...)`
+    // so a rejection is logged and the process stays clean; the iterator
+    // below still sees EOF/empty tokens via the addon's normal cancel path
+    // so callers aren't affected.
+    const onAbort = () => {
+        const addon = model.addon;
+        if (addon?.cancel) {
+            addon.cancel.call(addon).catch((err) => {
+                requestLogger.warn(`[cancel] addon.cancel() rejected during abort for modelId=${modelId}: ${err instanceof Error ? err.message : String(err)}`);
+            });
         }
-    }
-    else {
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    // `addEventListener("abort", ..., { once: true })` does *not* fire if
+    // the signal is already aborted at register time — but the registry
+    // synchronously aborts a fresh controller when `parentSignal` was
+    // already aborted at `begin(...)`. Without this fall-through, the
+    // addon would keep decoding until the post-loop check notices.
+    // Re-using `onAbort` here keeps the listener body as the single
+    // source of truth for "what cancel does."
+    if (signal.aborted)
+        onAbort();
+    // Detach the abort listener on every exit path (happy, throw, generator
+    // `return()` from upstream). `{ once: true }` already removes the
+    // listener if the signal fires, so the `removeEventListener` here is
+    // the cleanup hook for the signal-never-fired path.
+    scope.defer(() => {
+        signal.removeEventListener("abort", onAbort);
+    });
+    if (!kvCache) {
+        // KV-cache disabled — straight passthrough, no session involvement.
         let historyWithTools = history;
         if (staticTools && tools) {
             historyWithTools = prependToolsToHistory(history, tools);
@@ -401,4 +303,103 @@ export async function* completion(params) {
         logMessagesToAddon(transformedHistory, "NO_CACHE");
         return yield* processModelResponse(model, transformedHistory, tools, mergedGenerationParams, undefined, dialect);
     }
+    // ---- KV-cache path. The session owns all three bookkeeping layers
+    // (on-disk `.bin`, `initializedCaches`, `cachedMessageCounts`). The
+    // handler asks for a turn, registers rollback on the scope, and on
+    // the happy path calls `commitTurn` which short-circuits the deferred
+    // rollback. Cancellations / zero-token replies / rename failures all
+    // unwind through the same `scope.defer` hook. ----
+    const session = createKvCacheSession(modelId, { logger: requestLogger });
+    const systemPromptFromHistory = extractSystemPrompt(history);
+    // 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.";
+    const primeIfMissing = async (cachePath) => {
+        await initSystemPromptCache(model, cachePath, systemPromptToUse, typeof kvCache === "string" ? kvCache : "auto", 
+        // 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);
+    };
+    let turn;
+    if (typeof kvCache === "string") {
+        turn = await session.beginTurn({
+            kind: "custom",
+            customKey: kvCache,
+            configHash,
+            primeIfMissing,
+        });
+    }
+    else {
+        const cacheMessages = history.map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+            attachments: msg.attachments ?? undefined,
+        }));
+        turn = await session.beginTurn({
+            kind: "auto",
+            configHash,
+            history: cacheMessages,
+            primeIfMissing,
+        });
+    }
+    // Single cleanup hook for every non-success exit path. `commitTurn`
+    // flips the turn's internal `committed` flag so this becomes a no-op
+    // on the happy path. Scope unwinding is LIFO — registered after the
+    // `removeEventListener` defer above so rollback runs before the
+    // listener detach.
+    scope.defer(() => session.rollback(turn));
+    // `cacheExists` is implied by `beginTurn` — the session either found
+    // an existing cache or just primed one. Pass `true` to the message
+    // selector so the slicing branches engage.
+    const messagesToSend = prepareMessagesForCache(session, turn, 
+    /* cacheExists */ true, history, dynamicTools ? tools : undefined);
+    logMessagesToAddon(messagesToSend, "PROMPT_SEND");
+    const result = yield* processModelResponse(model, messagesToSend, tools, mergedGenerationParams, { cacheKey: turn.cachePath, saveCacheToDisk: true }, dialect);
+    if (typeof kvCache === "string") {
+        // Custom-key path: the addon wrote the new cache state inline at
+        // the same path. Either commit (records the boundary, suppresses
+        // rollback) or fall through to the deferred rollback.
+        if (shouldCommitTurn(signal, result.producedTokens)) {
+            await session.commitTurn(turn, {
+                kind: "static",
+                messageCount: history.length + 1,
+            });
+        }
+        return result;
+    }
+    // Auto-cache path.
+    //
+    // Tool-call turns: the auto-cache key is derived from
+    // `result.responseText`, which here is raw tool-call markup rather
+    // than a clean assistant message. There's no safe post-response key
+    // to rename to, so we let the deferred rollback drop the file. Once
+    // the SDK supports auto-cache for structured assistant/tool turns,
+    // this becomes a normal commit path.
+    if (result.toolCalls.length > 0) {
+        logger.warn(`[kv-cache] Auto cache tool-call turn; rolling back to avoid disk leak. path=${turn.cachePath}`);
+        return result;
+    }
+    if (!shouldCommitTurn(signal, result.producedTokens)) {
+        // Cancelled or zero-token turn — the addon wrote the file but its
+        // contents don't correspond to a clean turn boundary. Let the
+        // deferred rollback unlink it.
+        return result;
+    }
+    const savedHistory = buildAutoCacheSaveHistory(history.map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+        attachments: msg.attachments ?? undefined,
+    })), result.responseText);
+    const postResponseCacheInfo = await getCurrentCacheInfo(modelId, configHash, savedHistory);
+    await session.commitTurn(turn, {
+        kind: "autoRename",
+        targetCachePath: postResponseCacheInfo.cachePath,
+        messageCount: savedHistory.length,
+    });
+    return result;
 }

package/dist/server/bare/plugins/llamacpp-completion/ops/context-overflow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Helpers for detecting and parsing the llama.cpp addon's
+ * `ContextOverflow` status error (`LlmErrors.hpp::ContextOverflow = 14`).
+ *
+ * The addon's JS-facing throw goes through `js_throw_error(env, code,
+ * msg)` (see `JsUtils.hpp::JSCATCH`) where `code` comes from
+ * `qvac_errors::StatusError::codeString()` and formats as
+ * `"[ <addonId> :: ContextOverflow ]"`. The message carries the
+ * C++-formatted detail (which may include the prompt/ctx sizes).
+ *
+ * These helpers let the plugin handler convert that addon error into a
+ * typed `ContextOverflowError` and let unit tests assert the detection
+ * + extraction logic without a real model load.
+ */
+export declare function isAddonContextOverflowError(err: unknown): boolean;
+/**
+ * Best-effort extraction of `promptTokens` / `ctxSize` from the addon
+ * error message. The C++ paths in `TextLlmContext.cpp` and
+ * `MtmdLlmContext.cpp` format both numbers into the message; the
+ * `LlamaModel::processPromptImpl` fallback path emits a bare
+ * `"<func>: context overflow\n"` with neither number. Returning
+ * `undefined` for either field is fine — `ContextOverflowError` holds
+ * them as optional and the message factory degrades gracefully.
+ */
+export declare function parseContextOverflowMessage(message: string): {
+    promptTokens?: number;
+    ctxSize?: number;
+};
+//# sourceMappingURL=context-overflow.d.ts.map

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

@@ -0,0 +1,65 @@
+/**
+ * Helpers for detecting and parsing the llama.cpp addon's
+ * `ContextOverflow` status error (`LlmErrors.hpp::ContextOverflow = 14`).
+ *
+ * The addon's JS-facing throw goes through `js_throw_error(env, code,
+ * msg)` (see `JsUtils.hpp::JSCATCH`) where `code` comes from
+ * `qvac_errors::StatusError::codeString()` and formats as
+ * `"[ <addonId> :: ContextOverflow ]"`. The message carries the
+ * C++-formatted detail (which may include the prompt/ctx sizes).
+ *
+ * These helpers let the plugin handler convert that addon error into a
+ * typed `ContextOverflowError` and let unit tests assert the detection
+ * + extraction logic without a real model load.
+ */
+export function isAddonContextOverflowError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    // Anchor to the codeString tail (`[ <addonId> :: ContextOverflow ]`)
+    // so we don't false-positive on a hypothetical sibling like
+    // `ContextOverflowRecovered` or `PostContextOverflow` after an
+    // addon-side rename.
+    if (typeof code === "string" && /::\s*ContextOverflow\s*\]/.test(code)) {
+        return true;
+    }
+    // Message-substring fallback for the bare `LlamaModel::processPromptImpl`
+    // path, which doesn't go through `StatusError::codeString()`. Match the
+    // two known C++-emitted formats only — broader substring would catch
+    // wrapper / cause-chain text that mentions overflow without being one.
+    const message = err.message;
+    return (typeof message === "string" &&
+        /(?:context overflow at prefill step|processPromptImpl: context overflow)/i.test(message));
+}
+/**
+ * Best-effort extraction of `promptTokens` / `ctxSize` from the addon
+ * error message. The C++ paths in `TextLlmContext.cpp` and
+ * `MtmdLlmContext.cpp` format both numbers into the message; the
+ * `LlamaModel::processPromptImpl` fallback path emits a bare
+ * `"<func>: context overflow\n"` with neither number. Returning
+ * `undefined` for either field is fine — `ContextOverflowError` holds
+ * them as optional and the message factory degrades gracefully.
+ */
+export function parseContextOverflowMessage(message) {
+    // "[TextLlm] context overflow at prefill step: prompt tokens N, max context tokens M\n"
+    // Same-clause separator (no `[^]*?` cross-newline walk) so a future
+    // wrapper that pastes overflow text alongside unrelated numbers can't
+    // produce a mismatched pair.
+    const longForm = message.match(/prompt tokens (\d+)[,\s]+max context tokens (\d+)/i);
+    if (longForm?.[1] && longForm[2]) {
+        return {
+            promptTokens: Number(longForm[1]),
+            ctxSize: Number(longForm[2]),
+        };
+    }
+    // "[TextLlm] context overflow at prefill step (N tokens, max M)\n"
+    // "[MtmdLlm] context overflow at prefill step (N tokens, max M)\n"
+    const shortForm = message.match(/\((\d+)\s+tokens,\s*max\s+(\d+)\)/i);
+    if (shortForm?.[1] && shortForm[2]) {
+        return {
+            promptTokens: Number(shortForm[1]),
+            ctxSize: Number(shortForm[2]),
+        };
+    }
+    return {};
+}