@qvac/sdk 0.16.0 → 0.17.0

package/dist/scripts/check-resource-collectors-packaging.js

@@ -0,0 +1,136 @@
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bundleSdk } from '../commands/bundle/index.js';
+import { acceptResourceCollectorPackaging, formatResourceCollectorAcceptanceReport } from '../commands/verify/resource-collectors.js';
+import { RequestValidationFailedError } from '../utils/errors-client.js';
+const DESKTOP_HOSTS = [
+    'darwin-arm64',
+    'darwin-x64',
+    'linux-arm64',
+    'linux-x64',
+    'win32-arm64',
+    'win32-x64'
+];
+const DEFAULT_DEPENDENCIES = {
+    createTemporaryProject,
+    removeTemporaryProject,
+    bundleSdk,
+    acceptResourceCollectorPackaging,
+    formatResourceCollectorAcceptanceReport,
+    writeOutput(output) {
+        console.log(output);
+    },
+    writeError(output) {
+        console.error(output);
+    },
+    setExitCode(exitCode) {
+        process.exitCode = exitCode;
+    }
+};
+export function parseResourceCollectorCheckArgs(args) {
+    const hosts = [];
+    const seenHosts = new Set();
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument === '--host') {
+            const host = args[index + 1];
+            if (host === undefined || host.startsWith('--')) {
+                throw new RequestValidationFailedError('--host requires a platform-architecture value');
+            }
+            const desktopHost = validateDesktopHost(host);
+            if (!seenHosts.has(desktopHost)) {
+                seenHosts.add(desktopHost);
+                hosts.push(desktopHost);
+            }
+            index += 1;
+            continue;
+        }
+        throw new RequestValidationFailedError(`Unknown argument: ${argument}`);
+    }
+    return { hosts, json };
+}
+export function resolveDesktopHost(platform, arch) {
+    return validateDesktopHost(`${platform}-${arch}`);
+}
+export async function runResourceCollectorPackagingCheck(options, dependencies = DEFAULT_DEPENDENCIES) {
+    const hosts = options.hosts.length > 0
+        ? options.hosts
+        : [resolveDesktopHost(options.platform ?? process.platform, options.arch ?? process.arch)];
+    const temporaryProjectRoot = await dependencies.createTemporaryProject(options.sdkPackageRoot);
+    try {
+        const bundle = await dependencies.bundleSdk({
+            projectRoot: temporaryProjectRoot,
+            sdkPath: options.sdkPackageRoot,
+            hosts,
+            quiet: true
+        });
+        const report = await dependencies.acceptResourceCollectorPackaging({
+            projectRoot: temporaryProjectRoot,
+            bundlePath: bundle.bundlePath,
+            manifestPath: bundle.manifestPath,
+            hosts
+        });
+        const output = options.json
+            ? JSON.stringify(report, null, 2)
+            : dependencies.formatResourceCollectorAcceptanceReport(report);
+        dependencies.writeOutput(output);
+        if (!report.ok)
+            dependencies.setExitCode(1);
+    }
+    finally {
+        await dependencies.removeTemporaryProject(temporaryProjectRoot);
+    }
+}
+export async function runResourceCollectorPackagingCli(args, options = {}) {
+    const dependencies = options.dependencies ?? DEFAULT_DEPENDENCIES;
+    try {
+        await runResourceCollectorPackagingCheck({
+            sdkPackageRoot: options.sdkPackageRoot ?? resolveSdkPackageRoot(),
+            ...parseResourceCollectorCheckArgs(args)
+        }, dependencies);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const reason = message.split('\n').filter(Boolean).at(-1) ?? message;
+        dependencies.writeError(`Resource collector packaging check failed: ${reason}`);
+        dependencies.setExitCode(1);
+    }
+}
+function validateDesktopHost(host) {
+    const desktopHost = DESKTOP_HOSTS.find((candidate) => candidate === host);
+    if (desktopHost === undefined) {
+        throw new RequestValidationFailedError(`Unsupported host "${host}". Expected one of: ${DESKTOP_HOSTS.join(', ')}`);
+    }
+    return desktopHost;
+}
+async function createTemporaryProject(sdkPackageRoot) {
+    const projectRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'qvac-resource-collectors-packaging-'));
+    try {
+        await fsp.symlink(path.join(sdkPackageRoot, 'node_modules'), path.join(projectRoot, 'node_modules'), process.platform === 'win32' ? 'junction' : 'dir');
+        return projectRoot;
+    }
+    catch (error) {
+        await removeTemporaryProject(projectRoot);
+        throw error;
+    }
+}
+async function removeTemporaryProject(projectRoot) {
+    await fsp.rm(projectRoot, { recursive: true, force: true });
+}
+function resolveSdkPackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+function isMainModule() {
+    const entryPath = process.argv[1];
+    return entryPath !== undefined && path.resolve(entryPath) === fileURLToPath(import.meta.url);
+}
+if (isMainModule()) {
+    await runResourceCollectorPackagingCli(process.argv.slice(2));
+}

package/dist/scripts/contract/build-contract.d.ts

@@ -20,7 +20,7 @@ export declare function buildContract(): {
                 condition: string;
                 responseSchema: string;
             };
-            name: "cancel" | "transcribe" | "translate" | "finetune" | "loadModel" | "downloadAsset" | "rag" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "deleteCache" | "heartbeat" | "unloadModel" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "textToSpeech" | "textToSpeechStream" | "provide" | "stopProvide" | "getModelInfo" | "getLoadedModelInfo" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "resume" | "suspend" | "state" | "classify";
+            name: "cancel" | "transcribe" | "translate" | "finetune" | "loadModel" | "downloadAsset" | "rag" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "deleteCache" | "audioGenStream" | "heartbeat" | "unloadModel" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "textToSpeech" | "textToSpeechStream" | "provide" | "stopProvide" | "getModelInfo" | "getLoadedModelInfo" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "resume" | "suspend" | "state" | "getSystemResources" | "classify";
             callShape: "duplex" | "request-reply" | "server-stream";
             requestSchema: string;
             responseSchema: string;

package/dist/scripts/contract/build-models-registry.d.ts

@@ -1,4 +1,4 @@
-import type { ModelConstant } from '../../models/registry/index';
+import type { ModelConstant } from '../../models/registry/index.js';
 /**
  * JSON export of every named model constant in `@/models/registry`
  * (`QWEN3_600M_INST_Q4`, `BCI_EMBEDDER`, ...) — the same constants JS

package/dist/scripts/contract/plugin-contract.d.ts

@@ -1,4 +1,4 @@
-import type { QvacPlugin } from '../../schemas/index';
+import type { QvacPlugin } from '../../schemas/index.js';
 export interface PluginHandlerContract {
     name: string;
     streaming: boolean;

package/dist/scripts/contract/plugin-contract.js

@@ -1,4 +1,4 @@
-import { toWireJsonSchema } from './build-contract.js';
+import { toWireJsonSchema } from '../../scripts/contract/build-contract.js';
 /**
  * Wire contract of one registered plugin: JSON Schema per handler, in the
  * same wire shape the built-in contract export uses (requests as input

package/dist/scripts/export-contract.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { contractDir, renderContractFiles } from './contract/build-contract.js';
+import { contractDir, renderContractFiles } from '../scripts/contract/build-contract.js';
 const checkOnly = process.argv.includes('--check');
 const files = await renderContractFiles();
 await mkdir(contractDir, { recursive: true });

package/dist/scripts/export-plugin-contract.js

@@ -1,6 +1,6 @@
 import { writeFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
-import { buildPluginContract } from './contract/plugin-contract.js';
+import { buildPluginContract } from '../scripts/contract/plugin-contract.js';
 // Usage: tsx scripts/export-plugin-contract.ts <plugin-module> <out.json>
 // The plugin module's default export must be a definePlugin(...) value.
 const [modulePath, outPath] = process.argv.slice(2);

package/dist/server/bare/delegate-rpc-client.d.ts

@@ -1,5 +1,5 @@
 import RPC from 'bare-rpc';
-import type { RPCOptions } from '../../schemas/index';
+import type { RPCOptions } from '../../schemas/index.js';
 export declare function getRPC(publicKey: string, options?: RPCOptions): Promise<RPC>;
 /**
  * Remove a stale RPC connection for a peer.

package/dist/server/bare/delegate-rpc-client.js

@@ -1,13 +1,13 @@
 import { getSwarm } from './hyperswarm.js';
-import { getSDKConfig } from './registry/config-registry.js';
+import { getSDKConfig } from '../../server/bare/registry/config-registry.js';
 import { ensureDhtBootstrapped, describeConnectFailure } from './delegate-connect-diagnostics.js';
 import RPC from 'bare-rpc';
 import { withTimeout } from '../../utils/withTimeout.js';
 import { DelegateConnectionFailedError } from '../../utils/errors-server.js';
 import { getServerLogger } from '../../logging/index.js';
 import { nowMs } from '../../profiling/index.js';
-import { cacheDelegationConnectionTime, clearPeerConnectionTracking } from '../rpc/profiling/delegation-profiler.js';
-import { getNextCommandId } from '../rpc/rpc-utils.js';
+import { cacheDelegationConnectionTime, clearPeerConnectionTracking } from '../../server/rpc/profiling/delegation-profiler.js';
+import { getNextCommandId } from '../../server/rpc/rpc-utils.js';
 import { Buffer } from 'bare-buffer';
 const logger = getServerLogger();
 const activeRPCs = new Map();

package/dist/server/bare/hyperswarm.d.ts

@@ -1,5 +1,5 @@
 import Hyperswarm from 'hyperswarm';
-import { type FirewallConfig } from '../../schemas/provide';
+import { type FirewallConfig } from '../../schemas/provide.js';
 export declare function getSwarm({ firewallConfig }?: {
     firewallConfig?: FirewallConfig | undefined;
 }): Hyperswarm;

package/dist/server/bare/hyperswarm.js

@@ -2,8 +2,8 @@ import env from 'bare-env';
 import Hyperswarm from 'hyperswarm';
 import crypto from 'bare-crypto';
 import { envSchema } from '../../schemas/provide.js';
-import { getSDKConfig } from './registry/config-registry.js';
-import { registerSwarm, unregisterSwarm } from './runtime-lifecycle.js';
+import { getSDKConfig } from '../../server/bare/registry/config-registry.js';
+import { registerSwarm, unregisterSwarm } from '../../server/bare/runtime-lifecycle.js';
 import { getServerLogger } from '../../logging/index.js';
 import { Buffer } from 'bare-buffer';
 const logger = getServerLogger();

package/dist/server/bare/ops/bci-transcribe.d.ts

@@ -1,4 +1,4 @@
-import { type BciStreamOpts, type BciTranscribeParams, type TranscribeSegment, type TranscribeStats } from '../../../schemas/index';
+import { type BciStreamOpts, type BciTranscribeParams, type TranscribeSegment, type TranscribeStats } from '../../../schemas/index.js';
 type BciTranscribeReturn = {
     modelExecutionMs: number;
     stats?: TranscribeStats;

package/dist/server/bare/ops/bci-transcribe.js

@@ -50,15 +50,15 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { getModel } from '../registry/model-registry.js';
+import { getModel } from '../../../server/bare/registry/model-registry.js';
 import {} from '../../../schemas/index.js';
 import { getServerLogger } from '../../../logging/index.js';
 import { TranscriptionFailedError } from '../../../utils/errors-server.js';
 import { nowMs } from '../../../profiling/index.js';
 import { buildStreamResult } from '../../../profiling/model-execution.js';
-import { toTranscribeSegment } from '../utils/transcribe-metadata.js';
-import { getRequestRegistry, withRequestContext } from '../runtime/index.js';
-import { generateServerRequestId } from '../runtime/request-id.js';
+import { toTranscribeSegment } from '../../../server/bare/utils/transcribe-metadata.js';
+import { getRequestRegistry, withRequestContext } from '../../../server/bare/runtime/index.js';
+import { generateServerRequestId } from '../../../server/bare/runtime/request-id.js';
 async function runBci(model, input) {
     switch (input.type) {
         case 'base64':

package/dist/server/bare/ops/cancel.d.ts

@@ -1,5 +1,5 @@
-import { type CancelInferenceBaseParams } from '../../../schemas/index';
-import type { RequestKind } from '../runtime/index';
+import { type CancelInferenceBaseParams } from '../../../schemas/index.js';
+import type { RequestKind } from '../../../server/bare/runtime/index.js';
 /**
  * Broad cancel: abort every in-flight request matching `modelId` (and
  * optionally a `kind`). Maps onto `RequestRegistry.cancel({ modelId })`

package/dist/server/bare/ops/cancel.js

@@ -1,7 +1,7 @@
-import { getModel } from '../registry/model-registry.js';
+import { getModel } from '../../../server/bare/registry/model-registry.js';
 import { cancelInferenceBaseSchema } from '../../../schemas/index.js';
 import { ModelNotLoadedError } from '../../../utils/errors-server.js';
-import { getRequestRegistry } from '../runtime/index.js';
+import { getRequestRegistry } from '../../../server/bare/runtime/index.js';
 import { getServerLogger } from '../../../logging/index.js';
 const logger = getServerLogger();
 /**

package/dist/server/bare/ops/embed.d.ts

@@ -1,4 +1,4 @@
-import { type EmbedParams, type EmbedStats } from '../../../schemas/index';
+import { type EmbedParams, type EmbedStats } from '../../../schemas/index.js';
 export interface EmbedResult {
     embedding: number[] | number[][];
     stats?: EmbedStats;

package/dist/server/bare/ops/embed.js

@@ -50,13 +50,13 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { getModel } from '../registry/model-registry.js';
+import { getModel } from '../../../server/bare/registry/model-registry.js';
 import { embedParamsSchema } from '../../../schemas/index.js';
 import { buildUnaryResult } from '../../../profiling/model-execution.js';
 import { EmbedNoEmbeddingsError, EmbedFailedError, InferenceCancelledError } from '../../../utils/errors-server.js';
 import { nowMs } from '../../../profiling/index.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';
 export async function embed(params, requestId) {
     const env_1 = { stack: [], error: void 0, hasError: false };

package/dist/server/bare/ops/kv-cache-retention.d.ts

@@ -0,0 +1,12 @@
+export interface AutoCacheRetentionOptions {
+    activeCachePaths: string[];
+    maxBytes: number;
+    maxIdleMs: number;
+    nowMs: number;
+}
+export declare function markAutoCacheKey(cacheKey: string): Promise<void>;
+export declare function removeAutoCacheMarker(cacheKey: string): Promise<void>;
+export declare function removeAutoCacheMarkerIfMissing(cacheKey: string): Promise<void>;
+export declare function isCachePathWithinDirectory(directoryPath: string, cachePath: string): boolean;
+export declare function planAutoCacheEvictions(options: AutoCacheRetentionOptions): Promise<string[]>;
+//# sourceMappingURL=kv-cache-retention.d.ts.map

package/dist/server/bare/ops/kv-cache-retention.js

@@ -0,0 +1,121 @@
+import { promises as fsPromises } from 'bare-fs';
+import path from 'bare-path';
+import { getKVCacheDir } from '../../../server/utils/index.js';
+import { getServerLogger } from '../../../logging/index.js';
+const logger = getServerLogger();
+const AUTO_CACHE_MARKER_PREFIX = '.auto-cache-';
+const AUTO_CACHE_MARKER_PATTERN = /^\.auto-cache-([a-f0-9]{16})$/;
+function getAutoCacheMarkerPath(cacheKey) {
+    return path.join(getKVCacheDir(), `${AUTO_CACHE_MARKER_PREFIX}${cacheKey}`);
+}
+export async function markAutoCacheKey(cacheKey) {
+    try {
+        await fsPromises.writeFile(getAutoCacheMarkerPath(cacheKey), '');
+    }
+    catch (error) {
+        logger.warn(`[kv-cache] Failed to write auto-cache retention marker. key=${cacheKey} error=${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function removeAutoCacheMarker(cacheKey) {
+    try {
+        await fsPromises.unlink(getAutoCacheMarkerPath(cacheKey));
+    }
+    catch {
+        // The marker is best-effort cleanup metadata and may already be absent.
+    }
+}
+export async function removeAutoCacheMarkerIfMissing(cacheKey) {
+    try {
+        await fsPromises.access(path.join(getKVCacheDir(), cacheKey));
+    }
+    catch {
+        await removeAutoCacheMarker(cacheKey);
+    }
+}
+export function isCachePathWithinDirectory(directoryPath, cachePath) {
+    const prefix = `${directoryPath}${path.sep}`;
+    return cachePath === directoryPath || cachePath.startsWith(prefix);
+}
+async function readDirectory(directoryPath) {
+    try {
+        return await fsPromises.readdir(directoryPath);
+    }
+    catch {
+        return null;
+    }
+}
+async function inspectAutoCacheEntry(cacheKey, activeCachePaths) {
+    const directoryPath = path.join(getKVCacheDir(), cacheKey);
+    const modelDirectories = await readDirectory(directoryPath);
+    if (modelDirectories === null)
+        return null;
+    let size = 0;
+    let lastModifiedMs = 0;
+    for (const modelDirectory of modelDirectories) {
+        const modelPath = path.join(directoryPath, modelDirectory.toString());
+        const fileNames = await readDirectory(modelPath);
+        if (fileNames === null)
+            continue;
+        for (const fileName of fileNames) {
+            try {
+                const stats = await fsPromises.stat(path.join(modelPath, fileName.toString()));
+                if (!stats.isFile())
+                    continue;
+                size += stats.size;
+                lastModifiedMs = Math.max(lastModifiedMs, stats.mtime.getTime());
+            }
+            catch {
+                // The cache may have moved or been rolled back while the sweep was inspecting it.
+            }
+        }
+    }
+    return {
+        cacheKey,
+        directoryPath,
+        size,
+        lastModifiedMs,
+        active: activeCachePaths.some((cachePath) => isCachePathWithinDirectory(directoryPath, cachePath))
+    };
+}
+export async function planAutoCacheEvictions(options) {
+    const rootEntries = await readDirectory(getKVCacheDir());
+    if (rootEntries === null)
+        return [];
+    const entries = [];
+    for (const rootEntry of rootEntries) {
+        const markerMatch = AUTO_CACHE_MARKER_PATTERN.exec(rootEntry.toString());
+        if (markerMatch === null)
+            continue;
+        const cacheKey = markerMatch[1];
+        if (cacheKey === undefined)
+            continue;
+        const entry = await inspectAutoCacheEntry(cacheKey, options.activeCachePaths);
+        if (entry === null) {
+            await removeAutoCacheMarker(cacheKey);
+            continue;
+        }
+        entries.push(entry);
+    }
+    let retainedBytes = entries.reduce((total, entry) => total + entry.size, 0);
+    const evictions = new Set();
+    for (const entry of entries) {
+        if (entry.active)
+            continue;
+        const expired = entry.lastModifiedMs === 0 ||
+            (options.maxIdleMs > 0 && options.nowMs - entry.lastModifiedMs > options.maxIdleMs);
+        if (!expired)
+            continue;
+        evictions.add(entry.cacheKey);
+        retainedBytes -= entry.size;
+    }
+    const oldestFirst = entries
+        .filter((entry) => !entry.active && !evictions.has(entry.cacheKey))
+        .sort((a, b) => a.lastModifiedMs - b.lastModifiedMs);
+    for (const entry of oldestFirst) {
+        if (retainedBytes <= options.maxBytes)
+            break;
+        evictions.add(entry.cacheKey);
+        retainedBytes -= entry.size;
+    }
+    return Array.from(evictions);
+}

package/dist/server/bare/ops/kv-cache-utils.d.ts

@@ -1,4 +1,4 @@
-import { type CacheMessage } from '../../utils/index';
+import { type CacheMessage } from '../../../server/utils/index.js';
 export declare function extractSystemPrompt(messages: CacheMessage[]): string | null;
 export declare function generateConfigHash(systemPrompt: string | null, tools?: unknown): string;
 export declare function generateCacheKey(messages: CacheMessage[]): string;
@@ -12,6 +12,7 @@ export declare function getCurrentCacheInfo(modelId: string, configHash: string,
     cachePath: string;
 }>;
 export declare function renameCacheFile(oldPath: string, newPath: string): Promise<boolean>;
+export declare function pruneEmptyCacheDirectories(cacheFilePath: string): Promise<void>;
 export declare function deleteCache(options: {
     all: true;
 } | {

package/dist/server/bare/ops/kv-cache-utils.js

@@ -1,9 +1,10 @@
 import crypto from 'bare-crypto';
 import { promises as fsPromises } from 'bare-fs';
 import path from 'bare-path';
-import { getAutoCacheLookupHistory, getKVCacheDir, validateAndJoinPath } from '../../utils/index.js';
+import { getAutoCacheLookupHistory, getKVCacheDir, validateAndJoinPath } from '../../../server/utils/index.js';
 import { getServerLogger } from '../../../logging/index.js';
 import { Buffer } from 'bare-buffer';
+import { markAutoCacheKey } from '../../../server/bare/ops/kv-cache-retention.js';
 const logger = getServerLogger();
 // In-memory KV-cache state lives in `KvCacheSession` (the single
 // mutation point for all three KV-cache bookkeeping layers). This
@@ -37,18 +38,22 @@ export function generateCacheKey(messages) {
     const hashString = hash.digest('hex');
     return hashString.substring(0, 16);
 }
-export async function getCacheFilePath(modelId, configHash, cacheKey) {
+function resolveCacheFilePath(modelId, configHash, cacheKey) {
     const cacheDir = getKVCacheDir();
     const sessionCacheDir = validateAndJoinPath(cacheDir, cacheKey);
     const modelCacheDir = validateAndJoinPath(sessionCacheDir, modelId);
+    return path.join(modelCacheDir, `${configHash}.bin`);
+}
+export async function getCacheFilePath(modelId, configHash, cacheKey) {
+    const cachePath = resolveCacheFilePath(modelId, configHash, cacheKey);
+    const modelCacheDir = path.dirname(cachePath);
     try {
-        await fsPromises.mkdir(sessionCacheDir, { recursive: true });
         await fsPromises.mkdir(modelCacheDir, { recursive: true });
     }
     catch {
         // Ignore if directories already exist
     }
-    return path.join(modelCacheDir, `${configHash}.bin`);
+    return cachePath;
 }
 // Used for auto-generated cache key
 export async function findMatchingCache(modelId, configHash, currentHistory) {
@@ -57,9 +62,10 @@ export async function findMatchingCache(modelId, configHash, currentHistory) {
     }
     const previousHistory = getAutoCacheLookupHistory(currentHistory);
     const cacheKey = generateCacheKey(previousHistory);
-    const cachePath = await getCacheFilePath(modelId, configHash, cacheKey);
+    const cachePath = resolveCacheFilePath(modelId, configHash, cacheKey);
     try {
         await fsPromises.access(cachePath);
+        await markAutoCacheKey(cacheKey);
         return { cacheKey, cachePath };
     }
     catch {
@@ -68,6 +74,7 @@ export async function findMatchingCache(modelId, configHash, currentHistory) {
 }
 export async function getCurrentCacheInfo(modelId, configHash, currentHistory) {
     const cacheKey = generateCacheKey(currentHistory);
+    await markAutoCacheKey(cacheKey);
     const cachePath = await getCacheFilePath(modelId, configHash, cacheKey);
     return { cacheKey, cachePath };
 }
@@ -81,6 +88,20 @@ export async function renameCacheFile(oldPath, newPath) {
         return false;
     }
 }
+export async function pruneEmptyCacheDirectories(cacheFilePath) {
+    const cacheDir = getKVCacheDir();
+    const cacheDirPrefix = `${cacheDir}${path.sep}`;
+    let currentDirectory = path.dirname(cacheFilePath);
+    while (currentDirectory.startsWith(cacheDirPrefix)) {
+        try {
+            await fsPromises.rmdir(currentDirectory);
+        }
+        catch {
+            return;
+        }
+        currentDirectory = path.dirname(currentDirectory);
+    }
+}
 // Cache-existence probing (in-memory registry first, fall back to
 // `fs.access`) lives in `KvCacheSession.beginTurn(...)`. Keeping the
 // in-memory `initializedCaches` set private to the session module

package/dist/server/bare/ops/load-model.d.ts

@@ -1,5 +1,5 @@
-import { type LoadModelServerParams } from '../../../schemas/index';
-import type { LoadTimingStats } from '../../../profiling/types';
+import { type LoadModelServerParams } from '../../../schemas/index.js';
+import type { LoadTimingStats } from '../../../profiling/types.js';
 export interface LoadModelResult {
     timing?: LoadTimingStats;
 }

package/dist/server/bare/ops/load-model.js

@@ -1,10 +1,11 @@
 import { loadModelServerParamsSchema, normalizeModelType } from '../../../schemas/index.js';
 import { nowMs } from '../../../profiling/clock.js';
-import { isModelLoaded, registerModel } from '../registry/model-registry.js';
-import { startLogBuffering, stopLogBufferingWithTimeout } from '../registry/logging-stream-registry.js';
-import { detectShardedModel, generateShardFilenames, validateShardedModelCache } from '../../utils/index.js';
+import { forwardBackendDiagnostics } from '../../../profiling/backend-diagnostics.js';
+import { isModelLoaded, registerModel } from '../../../server/bare/registry/model-registry.js';
+import { startLogBuffering, stopLogBufferingWithTimeout } from '../../../server/bare/registry/logging-stream-registry.js';
+import { detectShardedModel, generateShardFilenames, validateShardedModelCache } from '../../../server/utils/index.js';
 import { PluginNotFoundError, ModelFileNotFoundError, ModelFileNotFoundInDirError, ModelFileLocateFailedError } from '../../../utils/errors-server.js';
-import { getPlugin } from '../../plugins/index.js';
+import { getPlugin } from '../../../server/plugins/index.js';
 import { promises as fsPromises } from 'bare-fs';
 import path from 'bare-path';
 import { getServerLogger } from '../../../logging/index.js';
@@ -72,7 +73,8 @@ export async function loadModel(params, options) {
             modelType: modelType,
             name: modelName
         });
-        return modelInitializationTimeMs !== undefined ? { timing: { modelInitializationTimeMs } } : {};
+        const loadResult = modelInitializationTimeMs !== undefined ? { timing: { modelInitializationTimeMs } } : {};
+        return forwardBackendDiagnostics(loadResult, result);
     }
     finally {
         stopLogBufferingWithTimeout(modelId);

package/dist/server/bare/ops/transcribe.d.ts

@@ -1,5 +1,5 @@
-import { type TranscribeParams, type TranscribeSegment, type TranscribeStats, type TranscribeStreamEvent, type ParakeetStreamingRunConfig } from '../../../schemas/index';
-import { assertMetadataSupported, toTranscribeSegment, type WhisperAddonSegment } from '../utils/transcribe-metadata';
+import { type TranscribeParams, type TranscribeSegment, type TranscribeStats, type TranscribeStreamEvent, type ParakeetStreamingRunConfig } from '../../../schemas/index.js';
+import { assertMetadataSupported, toTranscribeSegment, type WhisperAddonSegment } from '../../../server/bare/utils/transcribe-metadata.js';
 export { assertMetadataSupported, toTranscribeSegment, type WhisperAddonSegment };
 type TranscribeReturn = {
     modelExecutionMs: number;