Find GGUF models in publisher/model subfolders, and resume interrupted downloads

- listModels() only ever read files directly inside the configured folder.
  Tools like LM Studio organize downloads as <publisher>/<model>-GGUF/<file>.gguf
  one level deeper than that, so pointing the llama.cpp model storage
  location at a shared root (e.g. an existing Ollama/LM Studio models
  directory) found nothing. Now walks subfolders (bounded to 6 levels) and
  reports each model's path relative to the configured root. Sharded models
  are still grouped correctly per-folder, so two different publishers'
  same-named shard files no longer collide into one entry.

- LocalGgufModel now separates the real relative path (name, used for
  load/delete) from a display label, since a relative path with
  subdirectories isn't something you'd want to send to the identity
  validation you'd normally do on a bare filename — deleteModel's guard
  against path traversal now checks for ".." segments and containment
  within the root instead of rejecting any path separator outright, and
  sibling-shard cleanup happens in the target's own directory rather than
  the top-level root.

- downloadGgufFile() now resumes instead of restarting: an existing
  <file>.gguf.part is sent as a Range request, and the response is appended
  rather than overwritten. Falls back to a fresh download if the server
  ignores the Range header (200 instead of 206) or reports the partial as
  stale (416). Errors during streaming — a dropped connection being the
  main one — now deliberately leave the .part file in place instead of
  deleting it, since that's real resumable progress, not corruption. This
  also removes the startup sweep of .part files added in the previous
  commit, since blowing away partial downloads on every launch would defeat
  the point of being able to resume them.

14 new tests across llamacpp-manager.test.ts and huggingface.test.ts cover
subfolder discovery, per-folder shard grouping, nested deletion, path
traversal rejection, and the resume/fresh-start/stale-416 download paths.

Author: voidstackloop

app/src/huggingface.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { downloadGgufFile } from "./huggingface";
+
+function fakeResponse(opts: { status: number; headers?: Record<string, string>; chunks?: string[] }) {
+    const chunks = (opts.chunks ?? []).map((c) => new TextEncoder().encode(c));
+    let i = 0;
+    return {
+        ok: opts.status >= 200 && opts.status < 300,
+        status: opts.status,
+        headers: { get: (name: string) => opts.headers?.[name.toLowerCase()] ?? null },
+        body: {
+            getReader: () => ({
+                read: async () => (i < chunks.length ? { done: false, value: chunks[i++] } : { done: true, value: undefined }),
+            }),
+        },
+    } as unknown as Response;
+}
+
+describe("downloadGgufFile", () => {
+    let dir: string;
+    let destPath: string;
+
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "hf-download-test-"));
+        destPath = path.join(dir, "model.gguf");
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it("downloads fresh, reports progress, and renames the .part file to the final name on success", async () => {
+        const progress: { receivedBytes: number; totalBytes: number | null }[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => fakeResponse({ status: 200, headers: { "content-length": "10" }, chunks: ["hello", "world"] }))
+        );
+
+        await downloadGgufFile("org/model", "model.gguf", destPath, (p) => progress.push(p));
+
+        expect(fs.existsSync(destPath)).toBe(true);
+        expect(fs.existsSync(destPath + ".part")).toBe(false);
+        expect(fs.readFileSync(destPath, "utf8")).toBe("helloworld");
+        expect(progress.at(-1)).toEqual({ receivedBytes: 10, totalBytes: 10 });
+    });
+
+    it("resumes from an existing .part file using a Range request instead of starting over", async () => {
+        fs.writeFileSync(destPath + ".part", "hello");
+        const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+            expect((init?.headers as Record<string, string>).Range).toBe("bytes=5-");
+            return fakeResponse({ status: 206, headers: { "content-range": "bytes 5-9/10" }, chunks: ["world"] });
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        await downloadGgufFile("org/model", "model.gguf", destPath, () => {});
+
+        expect(fs.readFileSync(destPath, "utf8")).toBe("helloworld");
+    });
+
+    it("discards a stale partial and starts over when the server ignores the Range request", async () => {
+        fs.writeFileSync(destPath + ".part", "OLD-STALE-DATA");
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => fakeResponse({ status: 200, headers: { "content-length": "5" }, chunks: ["fresh"] }))
+        );
+
+        await downloadGgufFile("org/model", "model.gguf", destPath, () => {});
+
+        expect(fs.readFileSync(destPath, "utf8")).toBe("fresh");
+    });
+
+    it("keeps the .part file (doesn't delete it) when the connection drops mid-stream, so a retry can resume", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            headers: { get: () => "20" },
+            body: {
+                getReader: () => ({
+                    read: async () => {
+                        throw new Error("connection reset");
+                    },
+                }),
+            },
+        } as unknown as Response)));
+
+        await expect(downloadGgufFile("org/model", "model.gguf", destPath, () => {})).rejects.toThrow("connection reset");
+        expect(fs.existsSync(destPath + ".part")).toBe(true);
+        expect(fs.existsSync(destPath)).toBe(false);
+    });
+
+    it("keeps the .part file and throws when the stream ends short of the expected size", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => fakeResponse({ status: 200, headers: { "content-length": "100" }, chunks: ["short"] }))
+        );
+
+        await expect(downloadGgufFile("org/model", "model.gguf", destPath, () => {})).rejects.toThrow(/incomplete/);
+        expect(fs.existsSync(destPath + ".part")).toBe(true);
+    });
+
+    it("discards a partial and retries once when the server responds 416 (range no longer satisfiable)", async () => {
+        fs.writeFileSync(destPath + ".part", "stale");
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(fakeResponse({ status: 416 }))
+            .mockResolvedValueOnce(fakeResponse({ status: 200, headers: { "content-length": "5" }, chunks: ["fresh"] }));
+        vi.stubGlobal("fetch", fetchMock);
+
+        await downloadGgufFile("org/model", "model.gguf", destPath, () => {});
+
+        expect(fs.readFileSync(destPath, "utf8")).toBe("fresh");
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+});

app/src/huggingface.ts

@@ -55,6 +55,12 @@ export interface DownloadProgress {
 // of the app just not knowing about it.
 export const PARTIAL_DOWNLOAD_SUFFIX = ".part";
 
+function parseContentRangeTotal(headerValue: string | null): number | null {
+    // "bytes 12345-67890/98765" — the part after the slash is the full size.
+    const match = headerValue?.match(/\/(\d+)$/);
+    return match ? Number(match[1]) : null;
+}
+
 export async function downloadGgufFile(
     modelId: string,
     filename: string,
@@ -64,19 +70,48 @@ export async function downloadGgufFile(
 ): Promise<void> {
     const fs = await import("node:fs");
     const url = `https://huggingface.co/${modelId}/resolve/main/${encodeURIComponent(filename)}`;
+    const partPath = destPath + PARTIAL_DOWNLOAD_SUFFIX;
+
+    // A .part file left over from a dropped connection or a force-quit is
+    // real progress, not garbage — resume it with a Range request instead of
+    // re-downloading from byte zero every time.
+    let existingBytes = fs.existsSync(partPath) ? fs.statSync(partPath).size : 0;
+    const headers: Record<string, string> = {};
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (existingBytes > 0) headers.Range = `bytes=${existingBytes}-`;
+
     let res: Response;
     try {
-        res = await fetch(url, { headers: token ? { Authorization: `Bearer ${token}` } : undefined });
+        res = await fetch(url, { headers });
     } catch (err) {
         throw new Error(`Couldn't reach Hugging Face: ${(err as Error).message}`);
     }
+
+    if (existingBytes > 0 && res.status === 416) {
+        // Our partial is already >= what the server has now (stale, or the
+        // remote file changed) — it can't be resumed, so start clean once.
+        fs.rmSync(partPath, { force: true });
+        return downloadGgufFile(modelId, filename, destPath, onProgress, token);
+    }
+    let resuming = existingBytes > 0 && res.status === 206;
+    if (existingBytes > 0 && !resuming) {
+        // Server ignored the Range request and is sending the whole file
+        // from the start — appending that to the stale partial would
+        // corrupt it, so discard the partial and treat this as fresh.
+        existingBytes = 0;
+    }
+
     if (!res.ok || !res.body) throw new Error(`Failed to download "${filename}" (HTTP ${res.status}).`);
 
-    const totalBytes = Number(res.headers.get("content-length")) || null;
-    let receivedBytes = 0;
-    const partPath = destPath + PARTIAL_DOWNLOAD_SUFFIX;
-    const writeStream = fs.createWriteStream(partPath);
+    const contentLength = Number(res.headers.get("content-length")) || null;
+    const totalBytes = resuming
+        ? (parseContentRangeTotal(res.headers.get("content-range")) ?? (contentLength !== null ? existingBytes + contentLength : null))
+        : contentLength;
+
+    let receivedBytes = existingBytes;
+    const writeStream = fs.createWriteStream(partPath, { flags: resuming ? "a" : "w" });
     const reader = res.body.getReader();
+    onProgress({ receivedBytes, totalBytes });
 
     try {
         while (true) {
@@ -89,32 +124,21 @@ export async function downloadGgufFile(
             });
         }
     } catch (err) {
-        writeStream.end();
-        fs.rmSync(partPath, { force: true });
+        // Deliberately not deleting partPath — a dropped connection here
+        // leaves real, resumable progress on disk for the next attempt.
+        // Waited out rather than fire-and-forget so the partial bytes are
+        // actually flushed to disk before this function returns.
+        await new Promise<void>((resolve) => writeStream.end(() => resolve()));
         throw err;
     }
     await new Promise<void>((resolve, reject) => {
         writeStream.once("error", reject);
         writeStream.end(() => resolve());
     });
     if (totalBytes !== null && receivedBytes !== totalBytes) {
-        fs.rmSync(partPath, { force: true });
-        throw new Error(`Download of "${filename}" was incomplete (got ${receivedBytes} of ${totalBytes} bytes).`);
+        throw new Error(
+            `Download of "${filename}" was incomplete (got ${receivedBytes} of ${totalBytes} bytes) — try downloading it again to resume.`
+        );
     }
     fs.renameSync(partPath, destPath);
 }
-
-// Leftover *.gguf.part files can only come from a download that never
-// finished (crash, force-quit, killed process) — there's no resume support,
-// so they're permanently unusable. Called once at startup rather than left
-// for the user to notice a phantom download stuck at some old percentage.
-export async function cleanupIncompleteDownloads(modelsDir: string): Promise<void> {
-    const fs = await import("node:fs");
-    const path = await import("node:path");
-    if (!fs.existsSync(modelsDir)) return;
-    for (const f of fs.readdirSync(modelsDir)) {
-        if (f.toLowerCase().endsWith(PARTIAL_DOWNLOAD_SUFFIX)) {
-            fs.rmSync(path.join(modelsDir, f), { force: true });
-        }
-    }
-}

app/src/llamacpp-manager.test.ts

@@ -64,6 +64,33 @@ describe("listModels", () => {
         const names = listModels(dir).map((m) => m.name);
         expect(names).toEqual(["finished.gguf"]);
     });
+
+    it("finds models nested in publisher/model subfolders, e.g. LM Studio's layout", () => {
+        const modelDir = path.join(dir, "bartowski", "Some-Model-GGUF");
+        fs.mkdirSync(modelDir, { recursive: true });
+        fs.writeFileSync(path.join(modelDir, "some-model.gguf"), "x".repeat(20));
+        const models = listModels(dir);
+        expect(models).toHaveLength(1);
+        expect(models[0].name).toBe("bartowski/Some-Model-GGUF/some-model.gguf");
+        expect(models[0].sizeBytes).toBe(20);
+    });
+
+    it("groups shards separately per subfolder instead of merging same-named shards across models", () => {
+        const dirA = path.join(dir, "pub", "Model-A-GGUF");
+        const dirB = path.join(dir, "pub", "Model-B-GGUF");
+        fs.mkdirSync(dirA, { recursive: true });
+        fs.mkdirSync(dirB, { recursive: true });
+        fs.writeFileSync(path.join(dirA, "weights-00001-of-00002.gguf"), "x");
+        fs.writeFileSync(path.join(dirA, "weights-00002-of-00002.gguf"), "x");
+        fs.writeFileSync(path.join(dirB, "weights-00001-of-00002.gguf"), "x");
+        fs.writeFileSync(path.join(dirB, "weights-00002-of-00002.gguf"), "x");
+        const models = listModels(dir);
+        expect(models).toHaveLength(2);
+        expect(models.map((m) => m.name).sort()).toEqual([
+            "pub/Model-A-GGUF/weights-00001-of-00002.gguf",
+            "pub/Model-B-GGUF/weights-00001-of-00002.gguf",
+        ]);
+    });
 });
 
 describe("deleteModel", () => {
@@ -83,4 +110,23 @@ describe("deleteModel", () => {
     it("rejects a path-traversal attempt", async () => {
         await expect(deleteModel(dir, "../evil.gguf")).rejects.toThrow(/Invalid model file name/);
     });
+
+    it("deletes a model nested in a subfolder, and only its own shards", async () => {
+        const modelDir = path.join(dir, "pub", "Model-GGUF");
+        fs.mkdirSync(modelDir, { recursive: true });
+        fs.writeFileSync(path.join(modelDir, "weights-00001-of-00002.gguf"), "x");
+        fs.writeFileSync(path.join(modelDir, "weights-00002-of-00002.gguf"), "x");
+        const otherDir = path.join(dir, "pub", "Other-GGUF");
+        fs.mkdirSync(otherDir, { recursive: true });
+        fs.writeFileSync(path.join(otherDir, "weights-00001-of-00002.gguf"), "x");
+
+        await deleteModel(dir, "pub/Model-GGUF/weights-00001-of-00002.gguf");
+
+        expect(fs.readdirSync(modelDir)).toEqual([]);
+        expect(fs.readdirSync(otherDir)).toEqual(["weights-00001-of-00002.gguf"]);
+    });
+
+    it("rejects a traversal attempt disguised inside a subfolder path", async () => {
+        await expect(deleteModel(dir, "pub/../../evil.gguf")).rejects.toThrow(/Invalid model file name/);
+    });
 });

app/src/llamacpp-manager.ts

@@ -226,8 +226,12 @@ export async function dispose(): Promise<void> {
 }
 
 export interface LocalGgufModel {
-    // Real file name of the representative shard (part 1, or the lowest part
-    // present) — this is what gets passed back to loadModel/deleteModel.
+    // Path of the representative shard (part 1, or the lowest part present)
+    // relative to the configured models folder, forward-slash separated
+    // (e.g. "bartowski/Some-Model-GGUF/some-model.gguf") — this is what gets
+    // passed back to loadModel/deleteModel. Tools like LM Studio organize
+    // downloads as <publisher>/<model>-GGUF/<file>.gguf, so a flat single
+    // folder isn't enough to find them.
     name: string;
     // What to show in the UI. Same as `name` for a normal single-file model;
     // for a multi-part one it's a synthetic "(N parts)" label instead, since
@@ -286,16 +290,30 @@ export function groupShardedModels(files: RawGgufFile[]): LocalGgufModel[] {
     return [...standalone, ...grouped];
 }
 
+// Bounds the recursive scan below — comfortably covers real-world layouts
+// like LM Studio's <publisher>/<model>-GGUF/<file>.gguf (2 levels deep)
+// without walking into an unrelated, arbitrarily deep folder someone
+// accidentally pointed this setting at.
+const MAX_SCAN_DEPTH = 6;
+
+function walkGgufFiles(root: string, dir: string, depth: number): RawGgufFile[] {
+    if (depth > MAX_SCAN_DEPTH) return [];
+    const files: RawGgufFile[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkGgufFiles(root, full, depth + 1));
+        } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".gguf")) {
+            const relative = path.relative(root, full).split(path.sep).join("/");
+            files.push({ name: relative, path: full, sizeBytes: fs.statSync(full).size });
+        }
+    }
+    return files;
+}
+
 export function listModels(modelsDir: string): LocalGgufModel[] {
     if (!fs.existsSync(modelsDir)) return [];
-    const files = fs
-        .readdirSync(modelsDir)
-        .filter((f) => f.toLowerCase().endsWith(".gguf"))
-        .map((f) => {
-            const full = path.join(modelsDir, f);
-            return { name: f, path: full, sizeBytes: fs.statSync(full).size };
-        });
-    return groupShardedModels(files);
+    return groupShardedModels(walkGgufFiles(modelsDir, modelsDir, 0));
 }
 
 // Model paths currently kept warm in modelCache — used for the
@@ -307,10 +325,14 @@ export function listLoadedModels(): string[] {
 
 export async function deleteModel(modelsDir: string, name: string): Promise<void> {
     const root = path.resolve(modelsDir);
-    const target = path.resolve(root, name);
-    if (path.basename(name) !== name || !name.toLowerCase().endsWith(".gguf")) {
+    // `name` may now be a relative path with subfolders (see LocalGgufModel),
+    // so unlike before this can't reject on path separators — instead it
+    // rejects ".." segments and requires the resolved path to still land
+    // inside `root`, which is what actually prevents escaping the directory.
+    if (path.isAbsolute(name) || name.split(/[\\/]/).includes("..") || !name.toLowerCase().endsWith(".gguf")) {
         throw new Error("Invalid model file name.");
     }
+    const target = path.resolve(root, name);
     if (target === root || !target.startsWith(root + path.sep)) {
         throw new Error("Invalid model file name.");
     }
@@ -334,14 +356,17 @@ export async function deleteModel(modelsDir: string, name: string): Promise<void
     fs.rmSync(target, { force: true });
 
     // A multi-part model's sibling shards live under the same name pattern
-    // in the same directory — leaving them behind would orphan otherwise-
-    // unusable files that just sit there confusing the next listModels() call.
-    const shardMatch = name.match(SHARD_PATTERN);
+    // in the same directory as the target — leaving them behind would orphan
+    // otherwise-unusable files that just sit there confusing the next
+    // listModels() call.
+    const targetDir = path.dirname(target);
+    const targetBasename = path.basename(target);
+    const shardMatch = targetBasename.match(SHARD_PATTERN);
     if (shardMatch) {
         const [, base, , , ext] = shardMatch;
         const siblingPattern = new RegExp(`^${escapeRegExp(base)}-\\d+-of-\\d+${escapeRegExp(ext)}$`, "i");
-        for (const f of fs.readdirSync(root)) {
-            if (f !== name && siblingPattern.test(f)) fs.rmSync(path.join(root, f), { force: true });
+        for (const f of fs.readdirSync(targetDir)) {
+            if (f !== targetBasename && siblingPattern.test(f)) fs.rmSync(path.join(targetDir, f), { force: true });
         }
     }
 

app/src/main.ts

@@ -767,10 +767,6 @@ app.whenReady().then(async () => {
     await ollama.start();
     llamacpp.setModelCacheLimit(settingsStore.getSettings().llamaCppMaxCachedModels ?? 2);
     await llamacpp.setGpuBackend(settingsStore.getSettings().llamaCppGpuBackend ?? "auto");
-    // Leftover *.gguf.part files from a download that never finished last
-    // session (crash, force-quit) — there's no resume support, so they can
-    // only ever be dead weight; clear them before the model list is ever read.
-    await huggingface.cleanupIncompleteDownloads(getLlamaCppModelsDir());
     setupAutoUpdater(() => mainWindow);
     void connectEnabledMcpServers();
     scheduler.init((provider, model, prompt) => completePrompt(provider as ProviderId, model, prompt));