threadshelf 1.2.0

package/dist/src/generation/llama-profile.js

@@ -0,0 +1,136 @@
+// Only symmetric pairs: stock CUDA builds compile Flash Attention kernels for
+// q8_0/q8_0 and q4_0/q4_0, while other combinations can fall back to slow paths.
+const KV_CACHE_TYPE = { quality: 'q8_0', memory: 'q4_0' };
+const MTP_DRAFT_TOKENS = { auto: 2, aggressive: 3 };
+/** Above this, current CUDA builds have reported severe decode slowdowns. */
+export const LONG_CONTEXT_WARNING_TOKENS = 65_536;
+const formatTokens = (value) => value % 1024 === 0 ? `${value / 1024}K` : value.toLocaleString('en-US');
+/**
+ * Turns the saved performance settings into llama-server flags. Every option is
+ * gated on what this executable advertises in `--help` and on the GGUF header, so
+ * an unsupported choice is reported as skipped instead of breaking server startup.
+ * Sampling (temperature/top-p/top-k) is deliberately never touched here.
+ */
+export const resolveLlamaTuning = (config, capabilities, model) => {
+    const args = [];
+    const entries = [];
+    const skipped = (setting, value, note) => ({
+        setting,
+        value,
+        source: 'runtime',
+        applied: false,
+        note,
+    });
+    const contextNotes = [
+        model?.contextLength && config.contextSize > model.contextLength
+            ? `exceeds the model's native ${formatTokens(model.contextLength)}`
+            : '',
+        config.contextSize > LONG_CONTEXT_WARNING_TOKENS
+            ? 'experimental: very long contexts can decode much slower'
+            : '',
+    ].filter(Boolean);
+    entries.push({
+        setting: 'ctx',
+        value: formatTokens(config.contextSize),
+        source: 'settings',
+        applied: true,
+        ...(contextNotes.length ? { note: contextNotes.join('; ') } : {}),
+    });
+    let flashAttention = config.flashAttention;
+    let kvEntry;
+    const kvCache = config.kvCache ?? 'default';
+    if (kvCache !== 'default') {
+        const type = KV_CACHE_TYPE[kvCache];
+        const value = `${type}×${type}`;
+        if (!capabilities.kvCacheTypes) {
+            kvEntry = skipped('KV', value, 'this llama-server has no --cache-type-k');
+        }
+        else if (config.flashAttention === 'off') {
+            kvEntry = skipped('KV', value, 'a quantized KV cache needs Flash Attention, which is off');
+        }
+        else if (!capabilities.flashAttentionValues) {
+            kvEntry = skipped('KV', value, 'this llama-server cannot force Flash Attention on');
+        }
+        else {
+            args.push('--cache-type-k', type, '--cache-type-v', type);
+            kvEntry = { setting: 'KV', value, source: 'settings', applied: true };
+            flashAttention = 'on';
+        }
+    }
+    entries.push({
+        setting: 'FA',
+        value: flashAttention,
+        applied: true,
+        ...(flashAttention === config.flashAttention
+            ? { source: 'settings' }
+            : { source: 'threadshelf', note: 'required by the quantized KV cache' }),
+    });
+    if (kvEntry)
+        entries.push(kvEntry);
+    const speculative = config.speculative ?? 'off';
+    if (speculative === 'off') {
+        entries.push({ setting: 'MTP', value: 'off', source: 'settings', applied: true });
+    }
+    else {
+        const draft = String(MTP_DRAFT_TOKENS[speculative]);
+        if (!capabilities.speculativeTypes.includes('draft-mtp')) {
+            entries.push(skipped('MTP', draft, 'this llama-server has no draft-mtp decoding'));
+        }
+        else if (!model) {
+            entries.push(skipped('MTP', draft, 'GGUF metadata could not be read'));
+        }
+        else if (model.nextnPredictLayers < 1) {
+            entries.push({
+                setting: 'MTP',
+                value: 'off',
+                source: 'model',
+                applied: true,
+                note: 'the model has no MTP/NextN head',
+            });
+        }
+        else {
+            args.push('--spec-type', 'draft-mtp', '--spec-draft-n-max', draft);
+            entries.push({
+                setting: 'MTP',
+                value: draft,
+                source: 'settings',
+                applied: true,
+                note: `${model.nextnPredictLayers} NextN layer(s) in the GGUF`,
+            });
+        }
+    }
+    const reasoning = config.reasoningEffort ?? 'default';
+    if (reasoning === 'off') {
+        if (capabilities.reasoningToggle) {
+            args.push('--reasoning', 'off');
+            entries.push({ setting: 'reasoning', value: 'off', source: 'settings', applied: true });
+        }
+        else {
+            entries.push(skipped('reasoning', 'off', 'this llama-server has no --reasoning switch'));
+        }
+    }
+    else if (reasoning !== 'default') {
+        if (capabilities.reasoningEffort) {
+            args.push('--reasoning-effort', reasoning);
+            entries.push({ setting: 'reasoning', value: reasoning, source: 'settings', applied: true });
+        }
+        else {
+            entries.push(skipped('reasoning', reasoning, 'this llama-server has no --reasoning-effort'));
+        }
+    }
+    if (capabilities.parallelSlots) {
+        args.push('--parallel', '1');
+        entries.push({
+            setting: 'slots',
+            value: '1',
+            source: 'threadshelf',
+            applied: true,
+            note: 'single local user; concurrent chats queue',
+        });
+    }
+    return { flashAttention, args, entries };
+};
+/** One human-readable line: value, where it came from, and why anything was skipped. */
+export const formatLlamaTuning = (entries) => entries
+    .map((entry) => `${entry.setting} ${entry.value} (${entry.applied ? entry.source : 'skipped'}${entry.note ? `: ${entry.note}` : ''})`)
+    .join(' · ');

package/dist/src/generation/master-prompts.js

@@ -0,0 +1,155 @@
+import { mkdir, readFile, rename, writeFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { randomUUID } from 'crypto';
+import { dataPath } from '../paths.js';
+import { ValidationError } from '../validation.js';
+const MAX_PROMPTS = 50;
+const MAX_NAME_CHARS = 60;
+const MAX_TEXT_CHARS = 20_000;
+export const masterPromptsPath = () => resolve(process.env.MASTER_PROMPTS_PATH || dataPath('masterPrompts'));
+const isPrompt = (value) => Boolean(value) &&
+    typeof value === 'object' &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    typeof value.text === 'string';
+const read = async () => {
+    let raw;
+    try {
+        raw = await readFile(masterPromptsPath(), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { prompts: [], activeId: '' };
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid master prompt JSON at ${masterPromptsPath()}`, { cause: error });
+    }
+    const stored = parsed;
+    const prompts = (Array.isArray(stored.prompts) ? stored.prompts : [])
+        .filter(isPrompt)
+        .slice(0, MAX_PROMPTS)
+        .map((prompt) => ({
+        id: prompt.id,
+        name: prompt.name,
+        text: prompt.text,
+        updatedAt: typeof prompt.updatedAt === 'string' ? prompt.updatedAt : '',
+    }));
+    const activeId = typeof stored.activeId === 'string' ? stored.activeId : '';
+    return {
+        prompts,
+        activeId: prompts.some((prompt) => prompt.id === activeId) ? activeId : '',
+    };
+};
+const write = async (next) => {
+    const path = masterPromptsPath();
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    await rename(temporary, path);
+    return next;
+};
+// Writes are small but arrive from a chatty UI; serializing them keeps the
+// read-modify-write cycle from dropping a concurrent edit.
+let queue = Promise.resolve();
+const serialize = (operation) => {
+    const result = queue.then(operation, operation);
+    queue = result.catch(() => undefined);
+    return result;
+};
+const parseText = (value) => {
+    if (typeof value !== 'string') {
+        throw new ValidationError('Invalid text: must be a string', { field: 'text' });
+    }
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new ValidationError('A master prompt cannot be empty', { field: 'text' });
+    if (trimmed.length > MAX_TEXT_CHARS) {
+        throw new ValidationError(`Invalid text: max ${MAX_TEXT_CHARS} chars`, { field: 'text' });
+    }
+    return trimmed;
+};
+const parseName = (value, fallback) => {
+    if (value === undefined || value === null || value === '') {
+        return fallback.replace(/\s+/g, ' ').slice(0, 28);
+    }
+    if (typeof value !== 'string') {
+        throw new ValidationError('Invalid name: must be a string', { field: 'name' });
+    }
+    const trimmed = value.replace(/\s+/g, ' ').trim();
+    if (!trimmed)
+        return fallback.replace(/\s+/g, ' ').slice(0, 28);
+    if (trimmed.length > MAX_NAME_CHARS) {
+        throw new ValidationError(`Invalid name: max ${MAX_NAME_CHARS} chars`, { field: 'name' });
+    }
+    return trimmed;
+};
+// Route params arrive untyped from Express, so ids are validated here rather
+// than trusted at the call site.
+const parseId = (value) => {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new ValidationError('Invalid id', { field: 'id' });
+    }
+    return value;
+};
+export const listMasterPrompts = () => read();
+export const createMasterPrompt = (input) => serialize(async () => {
+    const current = await read();
+    if (current.prompts.length >= MAX_PROMPTS) {
+        throw new ValidationError(`At most ${MAX_PROMPTS} master prompts can be stored`);
+    }
+    const text = parseText(input?.text);
+    const prompt = {
+        id: randomUUID(),
+        name: parseName(input?.name, text),
+        text,
+        updatedAt: new Date().toISOString(),
+    };
+    // A freshly written prompt is the one the user means to use.
+    return write({ prompts: [...current.prompts, prompt], activeId: prompt.id });
+});
+export const updateMasterPrompt = (value, input) => serialize(async () => {
+    const id = parseId(value);
+    const current = await read();
+    const existing = current.prompts.find((prompt) => prompt.id === id);
+    if (!existing)
+        throw new ValidationError('Master prompt not found', { field: 'id' });
+    const text = input?.text === undefined ? existing.text : parseText(input.text);
+    const updated = {
+        ...existing,
+        name: input?.name === undefined ? existing.name : parseName(input.name, text),
+        text,
+        updatedAt: new Date().toISOString(),
+    };
+    return write({
+        prompts: current.prompts.map((prompt) => (prompt.id === id ? updated : prompt)),
+        activeId: input?.active === false ? '' : id,
+    });
+});
+export const deleteMasterPrompt = (value) => serialize(async () => {
+    const id = parseId(value);
+    const current = await read();
+    const prompts = current.prompts.filter((prompt) => prompt.id !== id);
+    if (prompts.length === current.prompts.length) {
+        throw new ValidationError('Master prompt not found', { field: 'id' });
+    }
+    return write({ prompts, activeId: current.activeId === id ? '' : current.activeId });
+});
+/** `id` of '' turns the master prompt off without deleting anything. */
+export const setActiveMasterPrompt = (id) => serialize(async () => {
+    if (typeof id !== 'string') {
+        throw new ValidationError('Invalid id: must be a string', { field: 'id' });
+    }
+    const current = await read();
+    if (id && !current.prompts.some((prompt) => prompt.id === id)) {
+        throw new ValidationError('Master prompt not found', { field: 'id' });
+    }
+    return write({ prompts: current.prompts, activeId: id });
+});

package/dist/src/generation/model-catalog.js

@@ -0,0 +1,276 @@
+/**
+ * Read-only browser for GGUF models published on the Hugging Face Hub.
+ *
+ * Everything here uses the public, unauthenticated API: search, download counts,
+ * per-file sizes and the LFS `oid` that doubles as the file's SHA-256. A token is
+ * only ever needed for *gated* repositories, which are detected up front so the
+ * UI can say so instead of failing with a 401 halfway through a download.
+ *
+ * Only catalog metadata leaves the machine. No chat content is ever sent here.
+ */
+export const HUGGINGFACE_ORIGIN = 'https://huggingface.co';
+/**
+ * Publishers whose GGUF repositories are consistently ungated and well-formed.
+ * They are surfaced first and used as the pool for one-click setup, which is how
+ * the common path avoids ever needing a Hugging Face login.
+ */
+export const TRUSTED_PUBLISHERS = [
+    'unsloth',
+    'lmstudio-community',
+    'bartowski',
+    'ggml-org',
+    'Qwen',
+    'google',
+    'mistralai',
+];
+const REPO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,95}\/[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/;
+const CACHE_TTL_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 20_000;
+const MAX_SEARCH_LIMIT = 50;
+/**
+ * Matches the quantisation suffix at the end of a GGUF file name: `Q4_K_M`,
+ * `IQ3_XXS`, `UD-Q4_K_XL`, `BF16`, `MXFP4_MOE`, `TQ1_0`.
+ */
+const QUANT_SUFFIX = /(?:^|[-_.])((?:UD-)?(?:I?Q\d+[A-Z0-9_]*|TQ\d+[A-Z0-9_]*|MXFP4[A-Z0-9_]*|BF16|FP16|F16|FP32|F32))$/i;
+const SHARD_SUFFIX = /-(\d{5})-of-(\d{5})$/;
+const PREFERRED_QUANTS = ['UD-Q4_K_XL', 'Q4_K_M', 'Q4_K_S', 'IQ4_XS', 'Q5_K_M', 'Q8_0'];
+/**
+ * Quality tiers for automatic selection. Size alone is a bad proxy: a legacy
+ * `Q4_1` and a modern `Q4_K_M` occupy the same space while the K-quant is
+ * clearly better, and full-precision weights waste memory that the KV cache
+ * needs. Higher is better; 0 means "never pick this automatically".
+ */
+export const quantQualityTier = (label) => {
+    const value = label.toUpperCase();
+    if (/^(UD-)?(BF16|FP16|F16|FP32|F32)$/.test(value))
+        return 0;
+    // Legacy non-K quantisations, kept usable but never preferred. Only the 4- and
+    // 5-bit families are legacy; `Q8_0` shares the shape but is the best common
+    // quantisation there is.
+    if (/^(UD-)?Q[45]_[01]$/.test(value))
+        return 1;
+    const bits = Number(value.match(/Q(\d+)/)?.[1] ?? 0);
+    if (bits >= 8)
+        return 6;
+    if (bits >= 6)
+        return 5;
+    if (bits >= 5)
+        return 4;
+    if (bits >= 4)
+        return 3;
+    if (bits >= 3)
+        return 2;
+    return 1;
+};
+export class CatalogError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'CatalogError';
+    }
+}
+export const assertRepoId = (value) => {
+    if (typeof value !== 'string' || !REPO_ID_PATTERN.test(value) || value.includes('..')) {
+        throw new CatalogError('Invalid model id: expected "owner/name"', 400);
+    }
+    return value;
+};
+export const huggingFaceToken = (env = process.env) => (env.HF_TOKEN || env.HUGGING_FACE_HUB_TOKEN || '').trim();
+const catalogHeaders = () => {
+    const token = huggingFaceToken();
+    return {
+        Accept: 'application/json',
+        'User-Agent': 'ThreadShelf-model-catalog',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    };
+};
+const cache = new Map();
+const cached = async (key, load) => {
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS)
+        return hit.value;
+    const value = await load();
+    cache.set(key, { at: Date.now(), value });
+    // The catalog is browsed interactively; a small bound keeps memory flat without
+    // any eviction bookkeeping.
+    if (cache.size > 200)
+        cache.delete(cache.keys().next().value);
+    return value;
+};
+export const clearCatalogCacheForTests = () => cache.clear();
+const catalogGet = async (path, fetchImpl) => {
+    const response = await fetchImpl(`${HUGGINGFACE_ORIGIN}${path}`, {
+        headers: catalogHeaders(),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new CatalogError('Hugging Face refused the request. Gated repositories need HF_TOKEN in the server .env.', response.status);
+    }
+    if (response.status === 404)
+        throw new CatalogError('Model not found on Hugging Face', 404);
+    if (response.status === 429) {
+        throw new CatalogError('Hugging Face rate limit reached. Try again shortly.', 429);
+    }
+    if (!response.ok) {
+        throw new CatalogError(`Hugging Face request failed (${response.status})`, response.status);
+    }
+    return response.json();
+};
+const parseGating = (value) => value === 'auto' || value === 'manual' ? value : false;
+const HF_SORT_FIELD = {
+    downloads: 'downloads',
+    likes: 'likes',
+    trending: 'trendingScore',
+    recent: 'lastModified',
+};
+const toSummary = (raw) => {
+    const id = raw.id || raw.modelId;
+    if (!id || !id.includes('/'))
+        return null;
+    const [author = '', ...rest] = id.split('/');
+    return {
+        id,
+        author,
+        name: rest.join('/'),
+        downloads: Number(raw.downloads) || 0,
+        likes: Number(raw.likes) || 0,
+        trendingScore: typeof raw.trendingScore === 'number' ? raw.trendingScore : undefined,
+        gated: parseGating(raw.gated),
+        updatedAt: raw.lastModified,
+        architecture: raw.gguf?.architecture,
+        contextLength: raw.gguf?.context_length,
+        parameterCount: raw.gguf?.total,
+        trustedPublisher: TRUSTED_PUBLISHERS.some((publisher) => publisher.toLowerCase() === author.toLowerCase()),
+    };
+};
+export const searchCatalogModels = async ({ query = '', sort = 'downloads', limit = 24, author, fetchImpl = fetch, } = {}) => {
+    const safeLimit = Math.min(Math.max(1, Math.trunc(limit) || 24), MAX_SEARCH_LIMIT);
+    const params = new URLSearchParams({
+        filter: 'gguf',
+        sort: HF_SORT_FIELD[sort] ?? 'downloads',
+        direction: '-1',
+        limit: String(safeLimit),
+    });
+    // The list endpoint omits `gated` unless it is explicitly expanded, so without
+    // this the browser could never warn that a repository needs a Hugging Face
+    // login. Expanding replaces the default field set, so every field the UI reads
+    // has to be named here.
+    for (const field of ['gated', 'downloads', 'likes', 'trendingScore', 'lastModified']) {
+        params.append('expand[]', field);
+    }
+    const trimmed = query.trim().slice(0, 128);
+    if (trimmed)
+        params.set('search', trimmed);
+    if (author)
+        params.set('author', author);
+    const path = `/api/models?${params.toString()}`;
+    const payload = await cached(path, () => catalogGet(path, fetchImpl));
+    const models = (Array.isArray(payload) ? payload : [])
+        .map((entry) => toSummary(entry))
+        .filter((model) => model !== null);
+    return {
+        models,
+        source: HUGGINGFACE_ORIGIN,
+        tokenConfigured: Boolean(huggingFaceToken()),
+    };
+};
+/** Splits `Model-Q4_K_M-00001-of-00002.gguf` into its quant label and shard index. */
+export const parseGgufFileName = (path) => {
+    const segments = path.split('/');
+    const fileName = segments[segments.length - 1] ?? path;
+    let base = fileName.replace(/\.gguf$/i, '');
+    let shardIndex;
+    let shardTotal;
+    const shard = base.match(SHARD_SUFFIX);
+    if (shard) {
+        shardIndex = Number(shard[1]);
+        shardTotal = Number(shard[2]);
+        base = base.slice(0, -shard[0].length);
+    }
+    const quant = base.match(QUANT_SUFFIX);
+    if (quant?.[1])
+        return { label: quant[1].toUpperCase(), shardIndex, shardTotal };
+    // Some repositories keep each quant in its own folder instead of encoding it in
+    // the file name (`Q4_K_M/model-00001-of-00002.gguf`).
+    if (segments.length > 1 && segments[0]) {
+        return { label: segments[0].toUpperCase(), shardIndex, shardTotal };
+    }
+    return { label: null, shardIndex, shardTotal };
+};
+export const groupCatalogQuants = (entries) => {
+    const projectors = [];
+    const groups = new Map();
+    for (const entry of entries) {
+        if (entry.type !== 'file' || !entry.path)
+            continue;
+        if (!/\.gguf$/i.test(entry.path))
+            continue;
+        const file = {
+            path: entry.path,
+            sizeBytes: Number(entry.lfs?.size ?? entry.size) || 0,
+            // The LFS object id for a Hub file is its SHA-256, which lets a download be
+            // verified with exactly the same guarantee as a llama.cpp release archive.
+            sha256: /^[a-f0-9]{64}$/i.test(entry.lfs?.oid ?? '')
+                ? entry.lfs.oid.toLowerCase()
+                : undefined,
+        };
+        const fileName = entry.path.split('/').pop() ?? entry.path;
+        if (/^mmproj/i.test(fileName)) {
+            projectors.push(file);
+            continue;
+        }
+        const { label } = parseGgufFileName(entry.path);
+        const key = label ?? fileName.replace(/\.gguf$/i, '').toUpperCase();
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(file);
+        else
+            groups.set(key, [file]);
+    }
+    const quants = [...groups.entries()]
+        .map(([label, files]) => {
+        const ordered = [...files].sort((a, b) => a.path.localeCompare(b.path));
+        return {
+            label,
+            files: ordered,
+            totalBytes: ordered.reduce((sum, file) => sum + file.sizeBytes, 0),
+            shards: ordered.length,
+            recommended: false,
+        };
+    })
+        .sort((a, b) => a.totalBytes - b.totalBytes);
+    const preferred = PREFERRED_QUANTS.map((label) => quants.find((quant) => quant.label === label)).find(Boolean) ??
+        quants[Math.floor(quants.length / 2)];
+    return {
+        quants: quants.map((quant) => ({ ...quant, recommended: quant === preferred })),
+        projectors: projectors.sort((a, b) => a.path.localeCompare(b.path)),
+    };
+};
+export const getCatalogModel = async (repoId, fetchImpl = fetch) => {
+    const id = assertRepoId(repoId);
+    const encoded = id.split('/').map(encodeURIComponent).join('/');
+    const [info, tree] = await Promise.all([
+        cached(`/api/models/${encoded}`, () => catalogGet(`/api/models/${encoded}`, fetchImpl)),
+        cached(`/tree/${encoded}`, () => catalogGet(`/api/models/${encoded}/tree/main?recursive=true`, fetchImpl)),
+    ]);
+    const summary = toSummary({ ...info, id });
+    if (!summary)
+        throw new CatalogError('Hugging Face returned an unusable model payload', 502);
+    const { quants, projectors } = groupCatalogQuants(Array.isArray(tree) ? tree : []);
+    if (quants.length === 0) {
+        throw new CatalogError(`${id} publishes no GGUF files`, 404);
+    }
+    return {
+        ...summary,
+        quants,
+        projectors,
+        license: info.cardData?.license,
+    };
+};
+export const catalogFileUrl = (repoId, filePath) => {
+    const id = assertRepoId(repoId);
+    const encodedRepo = id.split('/').map(encodeURIComponent).join('/');
+    const encodedPath = filePath.split('/').map(encodeURIComponent).join('/');
+    return `${HUGGINGFACE_ORIGIN}/${encodedRepo}/resolve/main/${encodedPath}?download=true`;
+};

package/dist/src/generation/model-discovery.js

@@ -0,0 +1,60 @@
+import { readdir, stat } from 'fs/promises';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'path';
+const MAX_MODELS = 10_000;
+const MAX_DEPTH = 8;
+export const localGgufModelName = (modelPath) => basename(modelPath, extname(modelPath));
+const isInside = (path, root) => {
+    const rel = relative(resolve(root), resolve(path));
+    // Across Windows drives `relative` yields an absolute path, which carries no
+    // `..` prefix and would otherwise read as "inside" — silently dropping every
+    // model root that lives on a different drive than the first one.
+    if (isAbsolute(rel))
+        return false;
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.includes('\0'));
+};
+export const discoverGgufModels = async (directories, { maxModels = MAX_MODELS, maxDepth = MAX_DEPTH } = {}) => {
+    const models = [];
+    const seen = new Set();
+    const roots = [...new Set(directories.map((directory) => resolve(directory)))]
+        .sort((a, b) => a.length - b.length)
+        .filter((root, index, all) => !all.slice(0, index).some((parent) => isInside(root, parent)));
+    const walk = async (root, directory, depth) => {
+        if (depth > maxDepth || models.length >= maxModels || !isInside(directory, root))
+            return;
+        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (models.length >= maxModels)
+                break;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                await walk(root, path, depth + 1);
+            }
+            else if (entry.isFile() && extname(entry.name).toLowerCase() === '.gguf') {
+                const lowerName = entry.name.toLowerCase();
+                if (lowerName.startsWith('mmproj'))
+                    continue;
+                const shard = lowerName.match(/-(\d{5})-of-\d{5}\.gguf$/);
+                if (shard && shard[1] !== '00001')
+                    continue;
+                const absolute = resolve(path);
+                if (seen.has(absolute))
+                    continue;
+                seen.add(absolute);
+                const fileStat = await stat(absolute).catch(() => null);
+                models.push({
+                    id: absolute,
+                    name: localGgufModelName(absolute),
+                    provider: 'llama-cpp',
+                    path: absolute,
+                    sizeBytes: fileStat?.size,
+                });
+            }
+        }
+    };
+    for (const root of roots) {
+        await walk(root, root, 0);
+        if (models.length >= maxModels)
+            break;
+    }
+    return models.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+};