@qvac/sdk 0.16.0 → 0.17.1

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

@@ -1,7 +1,7 @@
 import type { AbortSignal } from 'bare-abort-controller';
-import type { CompletionParams, CompletionStats, GenerationParams, ResponseFormat, Tool, ToolCall, ToolDialect } from '../../../../../schemas/index';
-import type { DisposableScope } from '../../../runtime/disposable-scope';
-import type { Logger } from '../../../../../logging/types';
+import type { CompletionParams, CompletionStats, GenerationParams, ResponseFormat, Tool, ToolCall, ToolDialect } from '../../../../../schemas/index.js';
+import type { DisposableScope } from '../../../../../server/bare/runtime/disposable-scope.js';
+import type { Logger } from '../../../../../logging/types.js';
 interface CompletionResult {
     modelExecutionMs: number;
     stats?: CompletionStats;

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

@@ -1,18 +1,18 @@
 import { TOOLS_MODE } from '../../../../../schemas/tools.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 { decideCachedHistorySlice, shouldCommitCachedTurn } 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';
-import { buildAutoCacheSaveHistory } from '../../../../utils/index.js';
+import { logCacheDisabled, logCacheInit, logCacheSave, logMessagesToAddon } from '../../../../../server/bare/plugins/llamacpp-completion/ops/cache-logger.js';
+import { extractSystemPrompt, getCurrentCacheInfo } from '../../../../../server/bare/ops/kv-cache-utils.js';
+import { getModel, getModelConfig } from '../../../../../server/bare/registry/model-registry.js';
+import { decideCachedHistorySlice, shouldCommitCachedTurn } from '../../../../../server/bare/plugins/llamacpp-completion/ops/kv-cache-state.js';
+import { createKvCacheSession, generateConfigHash } from '../../../../../server/bare/plugins/llamacpp-completion/ops/kv-cache-session.js';
+import { appendToolsToHistory, detectToolDialect, prependToolsToHistory } from '../../../../../server/utils/tool-integration.js';
+import { parseToolCalls } from '../../../../../server/utils/tools/index.js';
+import { getResponseFormatJsonSchema } from '../../../../../server/utils/response-format.js';
+import { buildAutoCacheSaveHistory } from '../../../../../server/utils/index.js';
 import { getServerLogger } from '../../../../../logging/index.js';
 import { AttachmentNotFoundError } from '../../../../../utils/errors-server.js';
 import { nowMs } from '../../../../../profiling/index.js';
 import { buildStreamResult } from '../../../../../profiling/model-execution.js';
-import { normalizeCompletionStats } from './completion-stats.js';
+import { normalizeCompletionStats, withEmittedTokens } from '../../../../../server/bare/plugins/llamacpp-completion/ops/completion-stats.js';
 import fs from 'bare-fs';
 const logger = getServerLogger();
 function transformMessage(message) {
@@ -47,8 +47,7 @@ function transformMessage(message) {
     return transformed;
 }
 function runModel(model, prompt, opts) {
-    const run = model.run.bind(model);
-    return run(prompt, opts);
+    return model.run(prompt, opts);
 }
 export function transformMessages(messages) {
     const transformed = [];
@@ -161,11 +160,14 @@ async function* processModelResponse(model, messagesToSend, tools, generationPar
     const response = await runModel(model, messagesToSend, hasRunOptions ? runOptions : undefined);
     let accumulatedText = '';
     let producedTokens = false;
+    let emittedPieces = 0;
     let toolCallsResult = [];
     for await (const token of response.iterate()) {
         const tokenStr = token;
-        if (tokenStr.length > 0)
+        if (tokenStr.length > 0) {
             producedTokens = true;
+            emittedPieces++;
+        }
         accumulatedText += tokenStr;
         yield { token: tokenStr };
     }
@@ -178,7 +180,7 @@ async function* processModelResponse(model, messagesToSend, tools, generationPar
         toolCallsResult = toolCalls;
     }
     const responseWithStats = response;
-    const stats = normalizeCompletionStats(responseWithStats.stats);
+    const stats = withEmittedTokens(normalizeCompletionStats(responseWithStats.stats), emittedPieces);
     return {
         ...buildStreamResult(modelExecutionMs, stats),
         toolCalls: toolCallsResult,

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

@@ -1,4 +1,4 @@
-import type { FinetuneRunParams, FinetuneRunRequest, FinetuneProgress, FinetuneRequest, FinetuneResult, FinetuneStatus, FinetuneGetStateRequest } from '../../../../../schemas/index';
+import type { FinetuneRunParams, FinetuneRunRequest, FinetuneProgress, FinetuneRequest, FinetuneResult, FinetuneStatus, FinetuneGetStateRequest } from '../../../../../schemas/index.js';
 type FinetuneOptions = FinetuneRunParams['options'];
 export declare function clearFinetuneRuntimeState(modelId: string): void;
 export declare function getFinetuneStateFromCheckpoints(options: FinetuneOptions): FinetuneStatus;

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

@@ -51,10 +51,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import fs from 'bare-fs';
-import { getModel } from '../../../registry/model-registry.js';
+import { getModel } from '../../../../../server/bare/registry/model-registry.js';
 import { CompletionFailedError } from '../../../../../utils/errors-server.js';
-import { getRequestRegistry, withRequestContext } from '../../../runtime/index.js';
-import { generateServerRequestId } from '../../../runtime/request-id.js';
+import { getRequestRegistry, withRequestContext } from '../../../../../server/bare/runtime/index.js';
+import { generateServerRequestId } from '../../../../../server/bare/runtime/request-id.js';
 import { getServerLogger } from '../../../../../logging/index.js';
 const PAUSE_CHECKPOINT_PREFIX = 'pause_checkpoint_step_';
 const finetuneRuntimeState = new Set();

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

@@ -1,6 +1,6 @@
-import { generateConfigHash } from '../../../ops/kv-cache-utils';
-import type { CacheMessage } from '../../../../utils/index';
-import type { Logger } from '../../../../../logging/types';
+import { generateConfigHash } from '../../../../../server/bare/ops/kv-cache-utils.js';
+import { type CacheMessage } from '../../../../../server/utils/index.js';
+import type { Logger } from '../../../../../logging/types.js';
 export interface TurnHandle {
     /** Resolved on-disk cache file path the addon will read from / write to. */
     readonly cachePath: string;
@@ -59,7 +59,8 @@ export interface KvCacheSession {
      * primes the system-prompt cache if needed (delegated to
      * `input.primeIfMissing`), marks the cache initialized, and returns a
      * `TurnHandle` the handler attaches to `ctx.scope.defer(...)` for the
-     * rollback hook.
+     * rollback hook. Auto-cache path resolution is serialized with
+     * retention deletion before the handle is returned.
      */
     beginTurn(input: BeginTurnInput): Promise<TurnHandle>;
     /**
@@ -72,12 +73,13 @@ export interface KvCacheSession {
     commitTurn(turn: TurnHandle, result: CommitResult): Promise<void>;
     /**
      * Roll back an in-flight turn — atomically deletes the on-disk cache
-     * file, clears the in-memory `initializedCaches` entry, and forgets
-     * the `cachedMessageCounts` entry. **All three layers, always, in
-     * one place.** Idempotent: a turn that has already been committed
-     * or rolled back is a no-op on subsequent calls. Handlers register
-     * this via `ctx.scope.defer(...)` so it runs regardless of how the
-     * handler exits (success branch removes itself via `commitTurn`).
+     * file, clears the in-memory `initializedCaches` entry, forgets the
+     * `cachedMessageCounts` entry, releases the active-path ref, and
+     * removes orphaned marker metadata. Idempotent: a turn that has
+     * already been committed or rolled back is a no-op on subsequent
+     * calls. Handlers register this via `ctx.scope.defer(...)` so it
+     * runs regardless of how the handler exits (success branch removes
+     * itself via `commitTurn`).
      */
     rollback(turn: TurnHandle): Promise<void>;
     /**
@@ -148,7 +150,15 @@ export declare const __kvCacheSessionTestHooks: {
     setSavedCountForTest(cachePath: string, count: number): void;
     hasInitializedKey(modelId: string, configHash: string, cacheKey: string): boolean;
     markInitializedForTest(modelId: string, configHash: string, cacheKey: string): void;
+    getLastAutoCacheSweepMsForTest(): number;
+    setLastAutoCacheSweepMsForTest(value: number): void;
     resetForTest(): void;
+    waitForAutoCacheSweepForTest(): Promise<void>;
+    sweepAutoCachesForTest(options: {
+        maxBytes: number;
+        maxIdleMs: number;
+        nowMs: number;
+    }): Promise<void>;
 };
 export { generateConfigHash };
 //# sourceMappingURL=kv-cache-session.d.ts.map

package/dist/server/bare/plugins/llamacpp-completion/ops/kv-cache-session.js

@@ -1,54 +1,27 @@
 import { promises as fsPromises } from 'bare-fs';
 import path from 'bare-path';
-import { findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, renameCacheFile, deleteCache as deleteCacheUtil } from '../../../ops/kv-cache-utils.js';
-import { logCacheSaveError, logCacheStatus } from './cache-logger.js';
+import { findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, pruneEmptyCacheDirectories, renameCacheFile, deleteCache as deleteCacheUtil } from '../../../../../server/bare/ops/kv-cache-utils.js';
+import { isCachePathWithinDirectory, markAutoCacheKey, planAutoCacheEvictions, removeAutoCacheMarker, removeAutoCacheMarkerIfMissing } from '../../../../../server/bare/ops/kv-cache-retention.js';
+import { isMobile } from '../../../../../server/bare/registry/runtime-context-registry.js';
+import { getKVCacheDir } from '../../../../../server/utils/index.js';
+import { logCacheSaveError, logCacheStatus } from '../../../../../server/bare/plugins/llamacpp-completion/ops/cache-logger.js';
 import { getServerLogger } from '../../../../../logging/index.js';
 // Used by cross-model paths that have no `RequestContext` (e.g.
 // `deleteKvCacheState`). Per-session call sites receive a logger from
 // the caller — typically `withRequestContext(...)`.
 const moduleLogger = getServerLogger();
 /**
- * Single owner of the three KV-cache bookkeeping layers.
+ * Coordinates five KV-cache state layers:
  *
- * The llama.cpp completion handler has three independent layers it must
- * keep consistent across every cancel/error branch:
+ * 1. `cachedMessageCounts` — saved message boundaries.
+ * 2. `initializedCaches` — caches primed in this worker.
+ * 3. On-disk `.bin` files written by the addon.
+ * 4. `activeCachePaths` — per-path refs that block in-flight eviction.
+ * 5. `.auto-cache-<key>` markers — SDK-generated cache ownership.
  *
- *   1. `cachedMessageCounts: Map<path, count>` — the "n messages
- *      currently on disk" tracker.
- *   2. `initializedCaches: Set<key>` — the "addon defers disk writes;
- *      we know this cache is primed" tracker.
- *   3. On-disk `.bin` files written by the addon.
- *
- * Without a single owner, every cancel / zero-token / rename-failed /
- * tool-call exit would need to touch all three; any branch that forgets
- * a layer produces three-layer drift bugs.
- *
- * `KvCacheSession` collapses the three layers behind one object with
- * three operations:
- *
- *   - `beginTurn` — resolves the cache file path, primes the system
- *     prompt cache if missing (delegated to a caller-supplied closure
- *     so the session doesn't depend on the model addon), marks the
- *     cache initialized, and returns a `TurnHandle` carrying the
- *     resolved path + the snapshot of the on-disk saved count.
- *   - `commitTurn` — records the new saved count (for custom-key
- *     turns) or renames the addon's pre-response file to the
- *     post-response path and records the count there (for auto-cache
- *     turns). Flips the turn's internal `committed` flag so the
- *     deferred `rollback` becomes a no-op on the happy path.
- *   - `rollback` — atomically deletes the on-disk file, clears the
- *     in-memory init entry, and forgets the saved count. **All three
- *     layers, always, in one place.** Handlers call it once via
- *     `ctx.scope.defer(() => session.rollback(turn))`; `commitTurn`
- *     short-circuits it on success.
- *
- * The module-level `deleteKvCacheState(...)` function (below) provides
- * an administrative cross-model delete API for the
- * `handleDeleteCache` RPC handler.
- *
- * The module-scoped `cachedMessageCounts` and `initializedCaches` maps
- * are *private* to this file — no other module reaches into them.
- * Callers that need cache-status info do so through the session API.
+ * Every turn must finish through `commitTurn` or `rollback` so all
+ * inference state stays aligned, the active-path ref is released, and
+ * marker metadata follows the cache directory lifecycle.
  */
 // ----- module-scoped state. The session is the single mutation point
 // for the in-memory KV-cache bookkeeping. -----
@@ -70,9 +43,101 @@ const cachedMessageCounts = new Map();
  * older worker runs still hit the lazy-load path in `beginTurn`.
  */
 const initializedCaches = new Set();
+const activeCachePaths = new Map();
+const DESKTOP_AUTO_CACHE_MAX_BYTES = 4 * 1024 * 1024 * 1024;
+const MOBILE_AUTO_CACHE_MAX_BYTES = 512 * 1024 * 1024;
+const AUTO_CACHE_MAX_IDLE_MS = 24 * 60 * 60 * 1000;
+const AUTO_CACHE_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+let lastAutoCacheSweepMs = 0;
+let autoCacheSweepInFlight = null;
+let cacheStateLockTail = Promise.resolve();
 function initRegistryKey(modelId, configHash, cacheKey) {
     return `${modelId}:${configHash}:${cacheKey}`;
 }
+function markCachePathActive(cachePath) {
+    activeCachePaths.set(cachePath, (activeCachePaths.get(cachePath) ?? 0) + 1);
+}
+function releaseCachePath(cachePath) {
+    const count = activeCachePaths.get(cachePath);
+    if (count === undefined)
+        return;
+    if (count === 1) {
+        activeCachePaths.delete(cachePath);
+        return;
+    }
+    activeCachePaths.set(cachePath, count - 1);
+}
+function isCacheKeyActive(cacheKey) {
+    const cacheDirectory = path.join(getKVCacheDir(), cacheKey);
+    return Array.from(activeCachePaths.keys()).some((cachePath) => isCachePathWithinDirectory(cacheDirectory, cachePath));
+}
+function getAutoCacheMaxBytes() {
+    return isMobile() ? MOBILE_AUTO_CACHE_MAX_BYTES : DESKTOP_AUTO_CACHE_MAX_BYTES;
+}
+async function withCacheStateLock(operation) {
+    const previous = cacheStateLockTail;
+    let releaseLock = () => { };
+    cacheStateLockTail = new Promise((resolve) => {
+        releaseLock = resolve;
+    });
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        releaseLock();
+    }
+}
+async function maybeSweepAutoCaches(logger, overrides) {
+    const nowMs = overrides?.nowMs ?? Date.now();
+    if (autoCacheSweepInFlight !== null) {
+        await autoCacheSweepInFlight;
+        if (!overrides?.force)
+            return;
+        return maybeSweepAutoCaches(logger, overrides);
+    }
+    if (!overrides?.force && nowMs - lastAutoCacheSweepMs < AUTO_CACHE_SWEEP_INTERVAL_MS)
+        return;
+    lastAutoCacheSweepMs = nowMs;
+    const sweep = async () => {
+        try {
+            const cacheKeys = await planAutoCacheEvictions({
+                activeCachePaths: Array.from(activeCachePaths.keys()),
+                maxBytes: overrides?.maxBytes ?? getAutoCacheMaxBytes(),
+                maxIdleMs: overrides?.maxIdleMs ?? AUTO_CACHE_MAX_IDLE_MS,
+                nowMs
+            });
+            let evictionCount = 0;
+            await withCacheStateLock(async () => {
+                for (const cacheKey of cacheKeys) {
+                    if (isCacheKeyActive(cacheKey))
+                        continue;
+                    await deleteKvCacheState({ kvCacheKey: cacheKey });
+                    evictionCount++;
+                }
+            });
+            if (evictionCount > 0) {
+                logger.debug(`[kv-cache] Evicted ${evictionCount} inactive auto-cache entries`);
+            }
+        }
+        catch (error) {
+            logger.warn(`[kv-cache] Auto-cache retention sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const sweepPromise = sweep();
+    autoCacheSweepInFlight = sweepPromise;
+    try {
+        await sweepPromise;
+    }
+    finally {
+        autoCacheSweepInFlight = null;
+    }
+}
+function scheduleAutoCacheSweep(logger) {
+    void maybeSweepAutoCaches(logger).catch((error) => {
+        logger.warn(`[kv-cache] Failed to schedule auto-cache retention sweep: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
 // ----- factory -----
 /**
  * Construct a session bound to one `(modelId, turn-owning request)`
@@ -86,7 +151,7 @@ export function createKvCacheSession(modelId, options) {
     // WeakMap so handles drop their state once the handler scope releases
     // the reference; the module-scoped maps above survive.
     const turnState = new WeakMap();
-    function makeHandle(cachePath, registryKey) {
+    function makeHandle(cachePath, registryKey, autoCacheKey) {
         const handle = {
             cachePath,
             savedCount: cachedMessageCounts.get(cachePath) ?? 0
@@ -94,36 +159,45 @@ export function createKvCacheSession(modelId, options) {
         turnState.set(handle, {
             cachePath,
             registryKey,
+            ...(autoCacheKey !== undefined && { autoCacheKey }),
             committed: false,
             rolledBack: false
         });
+        markCachePathActive(cachePath);
         return handle;
     }
     async function beginCustom(input) {
         const cachePath = await getCacheFilePath(modelId, input.configHash, input.customKey);
         const registryKey = initRegistryKey(modelId, input.configHash, input.customKey);
-        // In-memory registry check first — the addon defers disk writes, so
-        // a freshly-primed cache may not yet exist on disk. If the
-        // in-memory flag isn't set, fall back to a filesystem probe so
-        // caches surviving across worker restarts still hit the reuse path.
-        let exists = initializedCaches.has(registryKey);
-        if (!exists) {
-            try {
-                await fsPromises.access(cachePath);
-                exists = true;
-                initializedCaches.add(registryKey);
+        const handle = makeHandle(cachePath, registryKey);
+        try {
+            // In-memory registry check first — the addon defers disk writes, so
+            // a freshly-primed cache may not yet exist on disk. If the
+            // in-memory flag isn't set, fall back to a filesystem probe so
+            // caches surviving across worker restarts still hit the reuse path.
+            let exists = initializedCaches.has(registryKey);
+            if (!exists) {
+                try {
+                    await fsPromises.access(cachePath);
+                    exists = true;
+                    initializedCaches.add(registryKey);
+                }
+                catch {
+                    exists = false;
+                }
             }
-            catch {
-                exists = false;
+            logCacheStatus(input.customKey, exists);
+            if (!exists) {
+                await input.primeIfMissing(cachePath);
+                await verifyPrimedFile(cachePath, logger);
+                initializedCaches.add(registryKey);
             }
+            return handle;
         }
-        logCacheStatus(input.customKey, exists);
-        if (!exists) {
-            await input.primeIfMissing(cachePath);
-            await verifyPrimedFile(cachePath, logger);
-            initializedCaches.add(registryKey);
+        catch (error) {
+            releaseCachePath(cachePath);
+            throw error;
         }
-        return makeHandle(cachePath, registryKey);
     }
     async function beginAuto(input) {
         // The pre-response cache key is derived from
@@ -131,19 +205,34 @@ export function createKvCacheSession(modelId, options) {
         // internally. The post-response key (used after a successful turn)
         // is computed by the caller and passed to `commitTurn` as
         // `targetCachePath`.
-        const existingCache = await findMatchingCache(modelId, input.configHash, input.history);
-        const preResponseCacheInfo = await getCurrentCacheInfo(modelId, input.configHash, input.history);
-        const cachePath = existingCache !== null ? existingCache.cachePath : preResponseCacheInfo.cachePath;
-        const cacheKeyForRegistry = existingCache !== null ? existingCache.cacheKey : preResponseCacheInfo.cacheKey;
-        const registryKey = initRegistryKey(modelId, input.configHash, cacheKeyForRegistry);
-        const cacheExists = existingCache !== null;
+        const setup = await withCacheStateLock(async () => {
+            const existingCache = await findMatchingCache(modelId, input.configHash, input.history);
+            const cacheInfo = existingCache ?? (await getCurrentCacheInfo(modelId, input.configHash, input.history));
+            const registryKey = initRegistryKey(modelId, input.configHash, cacheInfo.cacheKey);
+            return {
+                cacheExists: existingCache !== null,
+                cachePath: cacheInfo.cachePath,
+                cacheKey: cacheInfo.cacheKey,
+                registryKey,
+                handle: makeHandle(cacheInfo.cachePath, registryKey, cacheInfo.cacheKey)
+            };
+        });
+        const { cacheExists, cachePath, cacheKey, registryKey, handle } = setup;
         logCacheStatus('auto', cacheExists);
-        if (!cacheExists) {
-            await input.primeIfMissing(cachePath);
-            await verifyPrimedFile(cachePath, logger);
-            initializedCaches.add(registryKey);
+        try {
+            if (!cacheExists) {
+                await input.primeIfMissing(cachePath);
+                await verifyPrimedFile(cachePath, logger);
+                initializedCaches.add(registryKey);
+            }
+            return handle;
+        }
+        catch (error) {
+            releaseCachePath(cachePath);
+            await pruneEmptyCacheDirectories(cachePath);
+            await removeAutoCacheMarkerIfMissing(cacheKey);
+            throw error;
         }
-        return makeHandle(cachePath, registryKey);
     }
     async function beginTurn(input) {
         if (input.kind === 'custom')
@@ -174,24 +263,42 @@ export function createKvCacheSession(modelId, options) {
                 return;
             }
             state.committed = true;
+            releaseCachePath(state.cachePath);
             return;
         }
-        // Auto-rename path: the pre-response file is now stale (its key
-        // refers to history minus the last user turn). Rename it to the
-        // post-response key and record the new count there.
-        if (!(await renameCacheFile(state.cachePath, result.targetCachePath))) {
-            logger.warn(`[kv-cache] Auto cache rename failed; rolling back. from=${state.cachePath} to=${result.targetCachePath}`);
+        const sourceCachePath = state.cachePath;
+        const sourceCacheKey = state.autoCacheKey;
+        const targetCacheKey = path.basename(path.dirname(path.dirname(result.targetCachePath)));
+        const renamed = await withCacheStateLock(async () => {
+            markCachePathActive(result.targetCachePath);
+            await fsPromises.mkdir(path.dirname(result.targetCachePath), { recursive: true });
+            await markAutoCacheKey(targetCacheKey);
+            if (!(await renameCacheFile(sourceCachePath, result.targetCachePath))) {
+                releaseCachePath(result.targetCachePath);
+                await pruneEmptyCacheDirectories(result.targetCachePath);
+                await removeAutoCacheMarkerIfMissing(targetCacheKey);
+                return false;
+            }
+            releaseCachePath(sourceCachePath);
+            state.cachePath = result.targetCachePath;
+            state.autoCacheKey = targetCacheKey;
+            await pruneEmptyCacheDirectories(sourceCachePath);
+            if (sourceCacheKey !== undefined) {
+                await removeAutoCacheMarkerIfMissing(sourceCacheKey);
+            }
+            cachedMessageCounts.delete(sourceCachePath);
+            initializedCaches.delete(state.registryKey);
+            return true;
+        });
+        if (!renamed) {
+            logger.warn(`[kv-cache] Auto cache rename failed; rolling back. from=${sourceCachePath} to=${result.targetCachePath}`);
             await runRollback(state);
             return;
         }
-        // The source path's entry is gone (the file moved). Drop it and
-        // record the new count at the rename target.
-        cachedMessageCounts.delete(state.cachePath);
         const ok = await verifySaveAndRecord(result.targetCachePath, result.messageCount);
         if (!ok) {
             // Rename succeeded but the file isn't where we expected. Roll
             // back via the target path instead of the (now-empty) source.
-            state.cachePath = result.targetCachePath;
             await runRollback(state);
             return;
         }
@@ -200,6 +307,8 @@ export function createKvCacheSession(modelId, options) {
         // is committed and won't roll back. Future turns compute fresh
         // paths.
         state.committed = true;
+        releaseCachePath(state.cachePath);
+        scheduleAutoCacheSweep(logger);
     }
     async function rollback(turn) {
         const state = turnState.get(turn);
@@ -220,9 +329,16 @@ export function createKvCacheSession(modelId, options) {
         catch (unlinkError) {
             logger.warn(`[kv-cache] Failed to remove cache file during rollback; next turn may load stale KV state. path=${state.cachePath} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
         }
+        await pruneEmptyCacheDirectories(state.cachePath);
+        if (state.autoCacheKey !== undefined) {
+            await removeAutoCacheMarkerIfMissing(state.autoCacheKey);
+        }
         initializedCaches.delete(state.registryKey);
         cachedMessageCounts.delete(state.cachePath);
+        releaseCachePath(state.cachePath);
         state.rolledBack = true;
+        if (state.autoCacheKey !== undefined)
+            scheduleAutoCacheSweep(logger);
     }
     function dropStaleSavedCount(turn) {
         const state = turnState.get(turn);
@@ -282,6 +398,9 @@ export async function deleteKvCacheState(target) {
         kvCacheKey: target.kvCacheKey,
         ...(target.modelId !== undefined && { modelId: target.modelId })
     });
+    if (target.modelId === undefined) {
+        await removeAutoCacheMarker(target.kvCacheKey);
+    }
     // Prefix-cleanup the in-memory counts. The on-disk directory tree
     // is `{kvCacheRoot}/{kvCacheKey}[/{modelId}]/`, so every entry in
     // `cachedMessageCounts` whose key is the removed directory itself
@@ -335,6 +454,7 @@ async function verifyPrimedFile(cachePath, logger) {
     catch (statError) {
         // ENOENT is the common case here — addon prime returned without
         // calling save (most often: signal abort during prefill).
+        await pruneEmptyCacheDirectories(cachePath);
         throw new Error(`[kv-cache] prime closure resolved but no cache file was written. path=${cachePath} cause=${statError instanceof Error ? statError.message : String(statError)}`);
     }
     if (stats.size === 0) {
@@ -343,6 +463,7 @@ async function verifyPrimedFile(cachePath, logger) {
         // primary "prime didn't persist" condition.
         try {
             await fsPromises.unlink(cachePath);
+            await pruneEmptyCacheDirectories(cachePath);
         }
         catch (unlinkError) {
             logger.warn(`[kv-cache] Failed to remove empty primed cache file. path=${cachePath} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
@@ -432,9 +553,25 @@ export const __kvCacheSessionTestHooks = {
     markInitializedForTest(modelId, configHash, cacheKey) {
         initializedCaches.add(initRegistryKey(modelId, configHash, cacheKey));
     },
+    getLastAutoCacheSweepMsForTest() {
+        return lastAutoCacheSweepMs;
+    },
+    setLastAutoCacheSweepMsForTest(value) {
+        lastAutoCacheSweepMs = value;
+    },
     resetForTest() {
         cachedMessageCounts.clear();
         initializedCaches.clear();
+        activeCachePaths.clear();
+        lastAutoCacheSweepMs = 0;
+        autoCacheSweepInFlight = null;
+        cacheStateLockTail = Promise.resolve();
+    },
+    waitForAutoCacheSweepForTest() {
+        return autoCacheSweepInFlight ?? Promise.resolve();
+    },
+    sweepAutoCachesForTest(options) {
+        return maybeSweepAutoCaches(moduleLogger, { ...options, force: true });
     }
 };
 // Re-export `generateConfigHash` from the path utilities so callers of