@qvac/sdk 0.9.2 → 0.10.1

package/dist/server/rpc/handlers/load-model/http.js

@@ -2,11 +2,10 @@ import fs, { promises as fsPromises } from "bare-fs";
 import path from "bare-path";
 import { Readable } from "bare-stream";
 import fetch from "bare-fetch";
-import { AbortController } from "bare-abort-controller";
 import { withTimeout } from "../../../../utils/withTimeout.js";
 import { getModelsCacheDir, getShardedModelCacheDir, generateShortHash, detectShardedModel, parsePatternBasedShardUrl, extractTensorsFromShards, calculatePercentage, isArchiveUrl, sanitizePathComponent, extractAndValidateShardedArchive, validateShardedModelCache, checkAllShardsExist, generateShardFilenames, hasValidGGUFHeader, } from "../../../utils/index.js";
 import { getSDKConfig } from "../../../bare/registry/config-registry.js";
-import { getActiveDownload, registerDownload, unregisterDownload, createHttpDownloadKey, shouldClearCache, clearClearCacheFlag, } from "./download-manager.js";
+import { createHttpDownloadKey, startOrJoinDownload, applyJoinedDownloadStats, } from "./download-manager.js";
 import { DownloadCancelledError, HTTPError, NoResponseBodyError, PartialDownloadOfflineError, ResponseBodyNotReadableError, } from "../../../../utils/errors-server.js";
 import { getServerLogger } from "../../../../logging/index.js";
 const logger = getServerLogger();
@@ -200,7 +199,7 @@ async function performHttpDownload(url, modelPath, downloadKey, progressCallback
             await new Promise((resolve, reject) => {
                 // Handle abort signal
                 const abortHandler = () => {
-                    const error = new Error("Download cancelled");
+                    const error = new DownloadCancelledError();
                     body.destroy();
                     writeStream.destroy();
                     reject(error);
@@ -324,51 +323,20 @@ export async function downloadModelFromHttp(url, progressCallback, hooks) {
         return downloadShardedModelFromHttp(url, progressCallback, hooks);
     }
     const downloadKey = createHttpDownloadKey(url);
-    const existing = getActiveDownload(downloadKey);
-    if (existing) {
-        logger.info(`📥 Reusing existing download for: ${downloadKey}`);
-        hooks?.markCacheMiss();
-        return existing.promise;
-    }
+    hooks?.onDownloadKey?.(downloadKey);
     const cacheDir = getModelsCacheDir();
     const sourceHash = generateShortHash(url);
     const modelPath = `${cacheDir}/${sourceHash}_${filename}`;
-    // Create managed download with AbortController
-    const abortController = new AbortController();
-    const downloadPromise = (async () => {
+    const result = startOrJoinDownload(downloadKey, async (ctx) => {
         try {
             // Check if already cached
-            const cachedPath = await validateCachedFile(modelPath, url, abortController.signal);
+            const cachedPath = await validateCachedFile(modelPath, url, ctx.signal);
             if (cachedPath) {
-                hooks?.markCacheHit();
-                if (progressCallback) {
-                    try {
-                        const stats = await fsPromises.stat(cachedPath);
-                        progressCallback({
-                            type: "modelProgress",
-                            downloaded: stats.size,
-                            total: stats.size,
-                            percentage: 100,
-                            downloadKey,
-                        });
-                    }
-                    catch (error) {
-                        logger.debug("Failed to get file stats for progress callback", {
-                            path: cachedPath,
-                            error,
-                        });
-                    }
-                }
-                return cachedPath;
-            }
-            // Download the file
-            hooks?.markCacheMiss();
-            await performHttpDownload(url, modelPath, downloadKey, progressCallback, abortController.signal);
-            // Send final 100% progress update
-            if (progressCallback) {
+                hooks?.markCacheHit?.();
+                ctx.setCacheHit(true);
                 try {
-                    const stats = await fsPromises.stat(modelPath);
-                    progressCallback({
+                    const stats = await fsPromises.stat(cachedPath);
+                    ctx.broadcastProgress({
                         type: "modelProgress",
                         downloaded: stats.size,
                         total: stats.size,
@@ -377,19 +345,40 @@ export async function downloadModelFromHttp(url, progressCallback, hooks) {
                     });
                 }
                 catch (error) {
-                    logger.debug("Failed to get file stats for final progress update", {
-                        path: modelPath,
+                    logger.debug("Failed to get file stats for progress callback", {
+                        path: cachedPath,
                         error,
                     });
                 }
+                return cachedPath;
+            }
+            // Download the file
+            hooks?.markCacheMiss?.();
+            ctx.setCacheHit(false);
+            await performHttpDownload(url, modelPath, downloadKey, ctx.broadcastProgress, ctx.signal);
+            try {
+                const stats = await fsPromises.stat(modelPath);
+                ctx.broadcastProgress({
+                    type: "modelProgress",
+                    downloaded: stats.size,
+                    total: stats.size,
+                    percentage: 100,
+                    downloadKey,
+                });
+            }
+            catch (error) {
+                logger.debug("Failed to get file stats for final progress update", {
+                    path: modelPath,
+                    error,
+                });
             }
             return modelPath;
         }
         catch (error) {
             logger.error("❌ Error downloading model:", error instanceof Error ? error.message : String(error));
             // Check if we should delete the partial file (clearCache was requested)
-            if (error instanceof Error && error.message === "Download cancelled") {
-                if (shouldClearCache(downloadKey)) {
+            if (error instanceof DownloadCancelledError) {
+                if (ctx.shouldClearCache()) {
                     logger.info("🗑️ Clearing cache - deleting partial file");
                     try {
                         await fsPromises.unlink(modelPath);
@@ -405,45 +394,22 @@ export async function downloadModelFromHttp(url, progressCallback, hooks) {
                 else {
                     logger.info("📥 Download paused - partial file preserved for resume");
                 }
-                clearClearCacheFlag(downloadKey);
             }
             const errorToThrow = error instanceof Error ? error : new Error(String(error));
             throw errorToThrow;
         }
-        finally {
-            // Cleanup from download manager
-            unregisterDownload(downloadKey);
-        }
-    })();
-    // Register download
-    const downloadEntry = {
-        key: downloadKey,
-        promise: downloadPromise,
-        abortController,
-        startTime: Date.now(),
-        type: "http",
-        url,
-        modelPath,
-        ...(progressCallback && { onProgress: progressCallback }),
-    };
-    registerDownload(downloadKey, downloadEntry);
-    return downloadPromise;
+    }, progressCallback);
+    return applyJoinedDownloadStats(result, hooks);
 }
 async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
     const config = getSDKConfig();
     const concurrency = config.httpDownloadConcurrency ?? DEFAULT_CONCURRENCY;
     const { shardUrls: shardInfos, cacheKey } = parsePatternBasedShardUrl(shardUrl);
     const downloadKey = `http-sharded:${cacheKey}`;
+    hooks?.onDownloadKey?.(downloadKey);
     logger.info(`📥 HTTP sharded download: ${shardInfos.length} shards detected from ${shardUrl}`);
-    const existing = getActiveDownload(downloadKey);
-    if (existing) {
-        logger.info(`📥 Reusing existing sharded download for: ${downloadKey}`);
-        hooks?.markCacheMiss();
-        return existing.promise;
-    }
-    const abortController = new AbortController();
     const shardDir = getShardedModelCacheDir(cacheKey);
-    const downloadPromise = (async () => {
+    const result = startOrJoinDownload(downloadKey, async (ctx) => {
         try {
             const shardStates = await Promise.all(shardInfos.map(async (shard, index) => {
                 const shardPath = path.join(shardDir, shard.filename);
@@ -451,7 +417,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
                 try {
                     const response = await fetch(shard.url, {
                         method: "HEAD",
-                        signal: abortController.signal,
+                        signal: ctx.signal,
                     });
                     expectedSize = parseInt(response.headers.get("content-length") || "0");
                 }
@@ -460,7 +426,6 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
                         url: shard.url,
                         error,
                     });
-                    // expectedSize remains 0, progress percentage will be 0
                 }
                 return {
                     index,
@@ -474,7 +439,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
             const overallTotal = shardStates.reduce((sum, s) => sum + s.expectedSize, 0);
             logger.info(`📏 Total size: ${overallTotal} bytes (${(overallTotal / 1024 / 1024).toFixed(2)} MB)`);
             const cacheChecks = await Promise.all(shardStates.map(async (state) => {
-                const cached = await validateCachedFile(state.shardPath, state.shard.url, abortController.signal);
+                const cached = await validateCachedFile(state.shardPath, state.shard.url, ctx.signal);
                 return { state, isCached: cached !== null };
             }));
             const shardsToDownload = cacheChecks
@@ -488,20 +453,22 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
             }
             logger.info(`📥 ${shardsToDownload.length} of ${shardInfos.length} shards need downloading`);
             if (shardsToDownload.length === 0) {
-                hooks?.markCacheHit();
+                hooks?.markCacheHit?.();
+                ctx.setCacheHit(true);
             }
             else {
-                hooks?.markCacheMiss();
+                hooks?.markCacheMiss?.();
+                ctx.setCacheHit(false);
             }
-            await downloadShardsWithConcurrency(shardsToDownload, shardStates, concurrency, abortController.signal, downloadKey, overallTotal, progressCallback);
+            await downloadShardsWithConcurrency(shardsToDownload, shardStates, concurrency, ctx.signal, downloadKey, overallTotal, ctx.broadcastProgress);
             logger.info(`✅ All ${shardInfos.length} shards downloaded successfully`);
             await extractTensorsFromShards(shardDir, shardInfos[0].filename);
             return path.join(shardDir, shardInfos[0].filename);
         }
         catch (error) {
             logger.error("❌ Error during sharded download:", error instanceof Error ? error.message : String(error));
-            if (error instanceof Error && error.message === "Download cancelled") {
-                if (shouldClearCache(downloadKey)) {
+            if (error instanceof DownloadCancelledError) {
+                if (ctx.shouldClearCache()) {
                     logger.info("🗑️ Clearing cache - deleting partial shard files");
                     try {
                         await fsPromises.rm(shardDir, { recursive: true, force: true });
@@ -517,50 +484,33 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
             }
             throw error;
         }
-        finally {
-            unregisterDownload(downloadKey);
-            clearClearCacheFlag(downloadKey);
-        }
-    })();
-    registerDownload(downloadKey, {
-        key: downloadKey,
-        promise: downloadPromise,
-        abortController,
-        startTime: Date.now(),
-        type: "http",
-        url: shardUrl,
-        modelPath: shardDir,
-    });
-    return downloadPromise;
+    }, progressCallback);
+    return applyJoinedDownloadStats(result, hooks);
 }
 async function downloadShardedModelFromArchive(archiveUrl, progressCallback, hooks) {
     const filename = extractFilenameFromUrl(archiveUrl);
     const sourceHash = generateShortHash(archiveUrl);
     const downloadKey = `http-archive:${sourceHash}`;
+    hooks?.onDownloadKey?.(downloadKey);
     logger.info(`📦 HTTP archive download: ${filename}`);
-    const existing = getActiveDownload(downloadKey);
-    if (existing) {
-        logger.info(`📥 Reusing existing archive download for: ${downloadKey}`);
-        hooks?.markCacheMiss();
-        return existing.promise;
-    }
-    const abortController = new AbortController();
     const extractDir = getShardedModelCacheDir(sourceHash);
     const archivePath = path.join(extractDir, `${sourceHash}_${filename}`);
-    const downloadPromise = (async () => {
+    const result = startOrJoinDownload(downloadKey, async (ctx) => {
         try {
             await fsPromises.mkdir(extractDir, { recursive: true });
             const files = await fsPromises.readdir(extractDir);
             const shardedFile = files.find((f) => detectShardedModel(String(f)).isSharded);
             if (!shardedFile) {
-                hooks?.markCacheMiss();
+                hooks?.markCacheMiss?.();
+                ctx.setCacheHit(false);
                 return downloadAndExtractArchive();
             }
             const shardFilename = String(shardedFile);
             const allShardsExist = await checkAllShardsExist(extractDir, shardFilename);
             if (!allShardsExist) {
                 logger.warn(`⚠️ Incomplete shards found, re-downloading archive`);
-                hooks?.markCacheMiss();
+                hooks?.markCacheMiss?.();
+                ctx.setCacheHit(false);
                 return downloadAndExtractArchive();
             }
             const shardFilenames = generateShardFilenames(shardFilename);
@@ -568,53 +518,67 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback, hoo
             const isComplete = await validateShardedModelCache(extractDir, shardFilename);
             if (isComplete) {
                 logger.info(`✅ Archive already extracted: ${extractDir}`);
-                hooks?.markCacheHit();
-                if (progressCallback) {
-                    progressCallback({
-                        type: "modelProgress",
-                        downloaded: 1,
-                        total: 1,
-                        percentage: 100,
-                        downloadKey,
-                    });
-                }
+                hooks?.markCacheHit?.();
+                ctx.setCacheHit(true);
+                ctx.broadcastProgress({
+                    type: "modelProgress",
+                    downloaded: 1,
+                    total: 1,
+                    percentage: 100,
+                    downloadKey,
+                });
                 return firstShard;
             }
             logger.info(`📝 All shards present but tensors.txt missing, extracting tensors...`);
             try {
                 await extractTensorsFromShards(extractDir, shardFilename);
                 logger.info(`✅ Tensors extracted successfully`);
-                hooks?.markCacheHit();
-                if (progressCallback) {
-                    progressCallback({
-                        type: "modelProgress",
-                        downloaded: 1,
-                        total: 1,
-                        percentage: 100,
-                        downloadKey,
-                    });
-                }
+                hooks?.markCacheHit?.();
+                ctx.setCacheHit(true);
+                ctx.broadcastProgress({
+                    type: "modelProgress",
+                    downloaded: 1,
+                    total: 1,
+                    percentage: 100,
+                    downloadKey,
+                });
                 return firstShard;
             }
             catch (error) {
                 logger.warn(`Failed to extract tensors, will re-download archive`, {
                     error,
                 });
-                hooks?.markCacheMiss();
+                hooks?.markCacheMiss?.();
+                ctx.setCacheHit(false);
                 return downloadAndExtractArchive();
             }
         }
         catch (error) {
             logger.error("❌ Error downloading/extracting archive:", error);
+            if (error instanceof DownloadCancelledError) {
+                if (ctx.shouldClearCache()) {
+                    logger.info("🗑️ Clearing cache - deleting archive extract directory");
+                    try {
+                        await fsPromises.rm(extractDir, {
+                            recursive: true,
+                            force: true,
+                        });
+                        logger.info(`✅ Deleted extract directory: ${extractDir}`);
+                    }
+                    catch (cleanupError) {
+                        logger.debug("Failed to delete extract directory during cleanup", {
+                            path: extractDir,
+                            error: cleanupError,
+                        });
+                    }
+                }
+            }
             throw error;
         }
-        finally {
-            unregisterDownload(downloadKey);
-        }
         async function downloadAndExtractArchive() {
-            await performHttpDownload(archiveUrl, archivePath, downloadKey, progressCallback, abortController.signal);
+            await performHttpDownload(archiveUrl, archivePath, downloadKey, ctx.broadcastProgress, ctx.signal);
             logger.info(`✅ Archive downloaded, extracting to: ${extractDir}`);
-            const firstShardPath = await extractAndValidateShardedArchive(archivePath, extractDir, abortController.signal);
+            const firstShardPath = await extractAndValidateShardedArchive(archivePath, extractDir, ctx.signal);
             try {
                 await fsPromises.unlink(archivePath);
                 logger.info(`🗑️ Cleaned up archive file: ${archivePath}`);
@@ -627,17 +591,8 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback, hoo
             }
             return firstShardPath;
         }
-    })();
-    registerDownload(downloadKey, {
-        key: downloadKey,
-        promise: downloadPromise,
-        abortController,
-        startTime: Date.now(),
-        type: "http",
-        url: archiveUrl,
-        modelPath: archivePath,
-    });
-    return downloadPromise;
+    }, progressCallback);
+    return applyJoinedDownloadStats(result, hooks);
 }
 async function downloadShardsWithConcurrency(shardsToDownload, allShards, concurrency, signal, downloadKey, overallTotal, progressCallback) {
     const queue = [...shardsToDownload];

package/dist/server/rpc/handlers/load-model/hyperdrive.d.ts

@@ -1,5 +1,5 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
-import type { DownloadMetricsHooks } from "./types";
+import type { DownloadHooks } from "./types";
 export declare function deleteCorestoreDirectory(corestoreDir: string): Promise<void>;
-export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, hooks?: DownloadMetricsHooks, expectedChecksum?: string): Promise<string>;
+export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, hooks?: DownloadHooks, expectedChecksum?: string): Promise<string>;
 //# sourceMappingURL=hyperdrive.d.ts.map

package/dist/server/rpc/handlers/load-model/hyperdrive.js

@@ -4,18 +4,17 @@ import Corestore from "corestore";
 import Hyperswarm, {} from "hyperswarm";
 import Hyperdrive from "hyperdrive";
 import {} from "bare-stream";
-import { AbortController } from "bare-abort-controller";
-import { getEnv } from "../../../env.js";
+import { getQvacPath } from "../../../utils/qvac-paths.js";
 import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, measureChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
 import { getModelBySrc } from "../../../../models/registry/index.js";
-import { getActiveDownload, registerDownload, unregisterDownload, createHyperdriveDownloadKey, shouldClearCache, clearClearCacheFlag, } from "./download-manager.js";
+import { createHyperdriveDownloadKey, startOrJoinDownload, applyJoinedDownloadStats, } from "./download-manager.js";
 import { getSDKConfig } from "../../../bare/registry/config-registry.js";
 import { FileNotFoundError, ChecksumValidationFailedError, DownloadCancelledError, HyperdriveDownloadFailedError, ModelLoadFailedError, NoBlobFoundError, } from "../../../../utils/errors-server.js";
 import { getServerLogger } from "../../../../logging/index.js";
 import { registerSwarm, unregisterSwarm, registerCorestore, unregisterCorestore, } from "../../../bare/runtime-lifecycle.js";
 const logger = getServerLogger();
 function getCorestoreDir(hyperdriveKey) {
-    return path.join(getEnv().HOME_DIR, ".qvac", "corestore", hyperdriveKey);
+    return getQvacPath("corestore", hyperdriveKey);
 }
 async function setupHyperdrive(hyperdriveKey, corestoreDir) {
     const corestore = new Corestore(corestoreDir);
@@ -185,7 +184,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
         return null;
     }
 }
-async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal, hooks) {
+async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal, hooks, shouldClearCache) {
     // Check if already aborted
     if (signal?.aborted) {
         throw new DownloadCancelledError();
@@ -231,8 +230,7 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
     }
     catch (error) {
         logger.error("❌ Error during hyperdrive download:", error instanceof Error ? error.message : String(error));
-        // Preserve cancellation errors
-        if (error instanceof Error && error.message === "Download cancelled") {
+        if (error instanceof DownloadCancelledError) {
             throw error;
         }
         throw new HyperdriveDownloadFailedError(`Download failed for ${modelFileName} from hyperdrive: ${hyperdriveKey}`, error);
@@ -247,16 +245,18 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
             }
         }
         // Only delete corestore and partial file if user explicitly requested clearCache
-        if (signal?.aborted && shouldClearCache(downloadKey)) {
+        if (signal?.aborted && shouldClearCache?.()) {
             try {
                 await fsPromises.unlink(modelPath);
             }
-            catch {
-                // no-op
+            catch (cleanupError) {
+                logger.debug("Failed to delete partial model file during cleanup", {
+                    path: modelPath,
+                    error: cleanupError,
+                });
             }
             await deleteCorestoreDirectory(corestoreDir);
         }
-        clearClearCacheFlag(downloadKey);
     }
 }
 async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal, hooks) {
@@ -321,7 +321,7 @@ async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, ex
             writeStream.on("finish", resolve);
             writeStream.on("error", reject);
             readStream.on("error", reject);
-            signal?.addEventListener("abort", () => reject(new Error("Download cancelled")), { once: true });
+            signal?.addEventListener("abort", () => reject(new DownloadCancelledError()), { once: true });
         });
         blobs.core.off("download", progressHandler);
         // Validate file size
@@ -352,31 +352,7 @@ async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, ex
         throw error;
     }
 }
-function createManagedDownload(downloadKey, hyperdriveKey, modelFileName, downloadFn, progressCallback) {
-    const abortController = new AbortController();
-    const downloadPromise = (async () => {
-        try {
-            return await downloadFn(abortController.signal);
-        }
-        finally {
-            unregisterDownload(downloadKey);
-            clearClearCacheFlag(downloadKey);
-        }
-    })();
-    const downloadEntry = {
-        key: downloadKey,
-        promise: downloadPromise,
-        abortController,
-        startTime: Date.now(),
-        type: "hyperdrive",
-        hyperdriveKey,
-        modelFileName,
-        ...(progressCallback && { onProgress: progressCallback }),
-    };
-    registerDownload(downloadKey, downloadEntry);
-    return downloadPromise;
-}
-async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal, hooks) {
+async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal, hooks, shouldClearCache) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
@@ -389,10 +365,10 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     const numberedShardCount = shardInfo.totalShards;
     logger.info(`Downloading sharded model with ${numberedShardCount} numbered shards + ${allFiles.length - numberedShardCount} companion files to ${shardDir}`);
     // Check which files need to be downloaded
-    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata, hooks ? (ms) => hooks.addChecksumValidationTimeMs(ms) : undefined);
+    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata, hooks?.addChecksumValidationTimeMs ? (ms) => hooks.addChecksumValidationTimeMs(ms) : undefined);
     if (invalidIndices.length === 0) {
         logger.info(`✅ All ${allFiles.length} files already downloaded and validated`);
-        hooks?.markCacheHit();
+        hooks?.markCacheHit?.();
         if (progressCallback) {
             const overallTotal = shardMetadata.reduce((sum, shard) => sum + shard.expectedSize, 0);
             const lastFile = allFiles[allFiles.length - 1];
@@ -416,7 +392,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
         return getShardPath(hyperdriveKey, allFiles[0]);
     }
     logger.info(`📥 Need to download ${invalidIndices.length} of ${allFiles.length} files`);
-    hooks?.markCacheMiss();
+    hooks?.markCacheMiss?.();
     // Setup hyperdrive once for all shards
     const corestoreDir = getCorestoreDir(hyperdriveKey);
     const setup = await setupHyperdrive(hyperdriveKey, corestoreDir);
@@ -510,7 +486,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     catch (error) {
         logger.error("❌ Error during sharded hyperdrive download:", error instanceof Error ? error.message : String(error));
         // Preserve cancellation errors
-        if (error instanceof Error && error.message === "Download cancelled") {
+        if (error instanceof DownloadCancelledError) {
             throw error;
         }
         throw new HyperdriveDownloadFailedError(`Sharded download failed for ${firstShardFileName} from hyperdrive: ${hyperdriveKey}`, error);
@@ -525,57 +501,62 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
             }
         }
         // Only delete corestore and partial files if user explicitly requested clearCache
-        const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName);
-        if (signal?.aborted && shouldClearCache(downloadKey)) {
+        if (signal?.aborted && shouldClearCache?.()) {
             await deleteCorestoreDirectory(corestoreDir);
         }
-        clearClearCacheFlag(downloadKey);
     }
     return getShardPath(hyperdriveKey, allFiles[0]);
 }
 export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, hooks, expectedChecksum) {
     const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, modelFileName);
-    // Check if already downloading
-    const existing = getActiveDownload(downloadKey);
-    if (existing) {
-        hooks?.markCacheMiss();
-        return existing.promise;
-    }
+    hooks?.onDownloadKey?.(downloadKey);
     const shardInfo = detectShardedModel(modelFileName);
     const model = getModelBySrc(modelFileName, hyperdriveKey);
-    if (shardInfo.isSharded && model?.shardMetadata) {
-        return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, (signal) => downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, progressCallback, seed, signal, hooks), progressCallback);
-    }
-    // Non-sharded model download
-    const corestoreDir = getCorestoreDir(hyperdriveKey);
-    const cacheDir = getModelsCacheDir();
-    const sourceHash = generateShortHash(`${hyperdriveKey}/${modelFileName}`);
-    const modelPath = path.join(cacheDir, `${sourceHash}_${modelFileName}`);
-    // First, check if we already have a valid cached file (only if we have model metadata)
-    if (model) {
-        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum, hooks);
-        if (cachedPath) {
-            hooks?.markCacheHit();
-            if (progressCallback) {
-                progressCallback({
+    const result = startOrJoinDownload(downloadKey, async (ctx) => {
+        if (shardInfo.isSharded && model?.shardMetadata) {
+            const hooksWithCacheHit = {
+                ...hooks,
+                markCacheHit: () => {
+                    hooks?.markCacheHit?.();
+                    ctx.setCacheHit(true);
+                },
+                markCacheMiss: () => {
+                    hooks?.markCacheMiss?.();
+                    ctx.setCacheHit(false);
+                },
+            };
+            return downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, ctx.broadcastProgress, seed, ctx.signal, hooksWithCacheHit, ctx.shouldClearCache);
+        }
+        // Non-sharded model download
+        const corestoreDir = getCorestoreDir(hyperdriveKey);
+        const cacheDir = getModelsCacheDir();
+        const sourceHash = generateShortHash(`${hyperdriveKey}/${modelFileName}`);
+        const modelPath = path.join(cacheDir, `${sourceHash}_${modelFileName}`);
+        // First, check if we already have a valid cached file (only if we have model metadata)
+        if (model) {
+            const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum, hooks);
+            if (cachedPath) {
+                hooks?.markCacheHit?.();
+                ctx.setCacheHit(true);
+                ctx.broadcastProgress({
                     type: "modelProgress",
                     downloaded: model.expectedSize,
                     total: model.expectedSize,
                     percentage: 100,
                     downloadKey,
                 });
+                // Delete any leftover corestore directory from previous runs (only when not seeding)
+                if (!seed) {
+                    await deleteCorestoreDirectory(corestoreDir);
+                }
+                return cachedPath;
             }
-            // Delete any leftover corestore directory from previous runs (only when not seeding)
-            if (!seed) {
-                await deleteCorestoreDirectory(corestoreDir);
-            }
-            return cachedPath;
         }
-    }
-    hooks?.markCacheMiss();
-    return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, async (signal) => {
+        hooks?.markCacheMiss?.();
+        ctx.setCacheHit(false);
         const checksumToValidate = expectedChecksum || model?.sha256Checksum || "";
-        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal, hooks);
+        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, ctx.broadcastProgress, seed, ctx.signal, hooks, ctx.shouldClearCache);
         return modelPath;
     }, progressCallback);
+    return applyJoinedDownloadStats(result, hooks);
 }

package/dist/server/rpc/handlers/load-model/index.d.ts

@@ -1,4 +1,3 @@
 export { handleLoadModel } from "./handler";
 export { resolveModelPath } from "./resolve";
-export { createCancelFunction } from "./download-manager";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/rpc/handlers/load-model/index.js

@@ -1,3 +1,2 @@
 export { handleLoadModel } from "./handler.js";
 export { resolveModelPath } from "./resolve.js";
-export { createCancelFunction } from "./download-manager.js";