@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/transformers-cache.js

@@ -0,0 +1,392 @@
+/**
+ * Shared cache-dir pinning for every `@huggingface/transformers` consumer
+ * in the service (kokoro TTS + memory embeddings).
+ *
+ * transformers.js v3 derives its model cache dir from the transformers
+ * module's OWN on-disk location (`<module>/../.cache/`) and has NO env-var
+ * override — it ignores `TRANSFORMERS_CACHE`. In a packaged/bundled runtime
+ * that directory isn't writable, so a downloaded model never lands as a
+ * cached file and the Node ONNX path-resolver throws "Unable to get model
+ * file path or buffer". Pinning `env.cacheDir` to a writable, gezel-managed
+ * dir before the first `from_pretrained` / `pipeline` call fixes it.
+ *
+ * Both consumers import the same ESM-node transformers build
+ * (`transformers.node.mjs`), so the `env` object we mutate here is the one
+ * the model loader reads `cacheDir` from at download time.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+import { isPathInside } from './fs/safe-paths.js';
+const log = createLogger('service');
+/**
+ * Env var carrying the resolved cache dir to processes that don't otherwise
+ * know the gezel home — notably the embed worker thread, which inherits
+ * `process.env` at spawn. Set once at service boot.
+ */
+export const HF_CACHE_DIR_ENV = 'GEZEL_HF_CACHE_DIR';
+/** Shared writable HF/transformers cache root for on-device model files. */
+export function transformersCacheDir(home) {
+    return join(home, 'engines', 'hf-cache');
+}
+/** The optional peer both TTS and memory embeddings load lazily. */
+export const TRANSFORMERS_MODULE = '@huggingface/transformers';
+const DEFAULT_MODEL_LOCK_TIMEOUT_MS = 10 * 60 * 1_000;
+const DEFAULT_MODEL_LOCK_STALE_MS = 2 * 60 * 60 * 1_000;
+const DEFAULT_MODEL_LOCK_POLL_MS = 100;
+function modelLockDir(cacheDir, modelId) {
+    const key = createHash('sha256').update(modelId, 'utf8').digest('hex').slice(0, 24);
+    return join(cacheDir, '.gezel-locks', `${key}.lock`);
+}
+function cacheModelDir(cacheDir, modelId) {
+    const parts = modelId.split('/');
+    if (parts.length === 0 ||
+        parts.some((part) => !part || part === '.' || part === '..' || part.includes('\\'))) {
+        throw new Error(`refusing unsafe transformers model id: ${modelId}`);
+    }
+    const root = resolve(cacheDir);
+    const target = resolve(root, ...parts);
+    if (target === root || !isPathInside(target, root)) {
+        throw new Error(`refusing transformers cache path outside ${root}: ${modelId}`);
+    }
+    return target;
+}
+function errorCode(err) {
+    return err?.code;
+}
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return errorCode(err) !== 'ESRCH';
+    }
+}
+async function lockOwnerPid(lockDir) {
+    try {
+        const owner = JSON.parse(await readFile(join(lockDir, 'owner.json'), 'utf8'));
+        return typeof owner.pid === 'number' && Number.isInteger(owner.pid) && owner.pid > 0
+            ? owner.pid
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function staleOrMissing(lockDir, staleMs) {
+    try {
+        const info = await stat(lockDir);
+        if (Date.now() - info.mtimeMs > staleMs)
+            return true;
+    }
+    catch (err) {
+        if (errorCode(err) === 'ENOENT')
+            return true;
+        throw err;
+    }
+    // A holder killed mid-download (a quit during first run) never reaches its
+    // `finally`. Waiting out the age limit would keep semantic memory off for
+    // hours after the relaunch, so a lock whose owner is gone is stale now.
+    const pid = await lockOwnerPid(lockDir);
+    return pid !== null && !processAlive(pid);
+}
+/**
+ * Serialize first-use model downloads across service/Vitest processes sharing
+ * one transformers cache. `pipelinePromise` prevents duplicate loads inside a
+ * process; this directory lock closes the remaining cross-process race where
+ * two fetches could replace the same ONNX file and leave one worker parsing a
+ * partial protobuf.
+ */
+export async function withTransformersModelCacheLock(cacheDir, modelId, run, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_MODEL_LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? DEFAULT_MODEL_LOCK_STALE_MS;
+    const pollMs = options.pollMs ?? DEFAULT_MODEL_LOCK_POLL_MS;
+    const lockDir = modelLockDir(cacheDir, modelId);
+    await mkdir(dirname(lockDir), { recursive: true });
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            await mkdir(lockDir);
+            break;
+        }
+        catch (err) {
+            if (errorCode(err) !== 'EEXIST')
+                throw err;
+            if (await staleOrMissing(lockDir, staleMs)) {
+                await rm(lockDir, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new Error(`timed out waiting for transformers cache lock for ${modelId}`);
+            }
+            await delay(pollMs);
+        }
+    }
+    try {
+        await writeFile(join(lockDir, 'owner.json'), `${JSON.stringify({ pid: process.pid, modelId, acquiredAt: new Date().toISOString() })}\n`);
+        return await run();
+    }
+    finally {
+        await rm(lockDir, { recursive: true, force: true });
+    }
+}
+/** Remove only the named repository directory after a proven cache parse failure. */
+export async function removeTransformersModelCache(cacheDir, modelId) {
+    await rm(cacheModelDir(cacheDir, modelId), { recursive: true, force: true });
+}
+/** Failures that mean retrying against the same cached bytes cannot succeed. */
+export function isCorruptTransformersCacheFailure(error) {
+    const messages = [];
+    let current = error;
+    for (let depth = 0; depth < 6 && current; depth++) {
+        messages.push(current instanceof Error ? current.message : String(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return /(?:protobuf parsing failed|failed to parse protobuf|invalid protobuf|unexpected end of (?:file|data)|failed to load model|load model .* failed|invalid wire type)/i.test(messages.join(' '));
+}
+/**
+ * Load a model under its cross-process lock, replacing only its repository
+ * cache and retrying once when the first load proves those bytes corrupt.
+ */
+export async function loadTransformersModelWithCacheRecovery(cacheDir, modelId, load, onCorrupt) {
+    return withTransformersModelCacheLock(cacheDir, modelId, async () => {
+        try {
+            return await load();
+        }
+        catch (err) {
+            if (!isCorruptTransformersCacheFailure(err))
+                throw err;
+            await onCorrupt?.();
+            await removeTransformersModelCache(cacheDir, modelId);
+            return await load();
+        }
+    });
+}
+/**
+ * A model file gezel downloaded itself did not arrive whole or did not match
+ * its pin. Nothing was written to the cache path, so a later attempt starts
+ * clean.
+ */
+export class ModelFileDownloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ModelFileDownloadError';
+    }
+}
+const VERIFIED_MARKER_SUFFIX = '.gezel-verified';
+const PARTIAL_DOWNLOAD_INFIX = '.download-';
+function cacheFilePath(cacheDir, modelId, file) {
+    const parts = file.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..' || part.includes('\\'))) {
+        throw new Error(`refusing unsafe model file path: ${file}`);
+    }
+    const repo = cacheModelDir(cacheDir, modelId);
+    const target = resolve(repo, ...parts);
+    if (!isPathInside(target, repo)) {
+        throw new Error(`refusing model file path outside ${repo}: ${file}`);
+    }
+    return target;
+}
+function remoteFileUrl(source, modelId, pinned) {
+    const host = source.remoteHost.endsWith('/') ? source.remoteHost : `${source.remoteHost}/`;
+    const template = source.remotePathTemplate
+        .replaceAll('{model}', modelId)
+        .replaceAll('{revision}', encodeURIComponent(pinned.revision));
+    const path = template.endsWith('/') ? template : `${template}/`;
+    return `${host}${path.replace(/^\/+/, '')}${pinned.file}`;
+}
+async function sha256File(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return `sha256:${hash.digest('hex')}`;
+}
+async function markerVouches(marker, target, digest) {
+    try {
+        const recorded = JSON.parse(await readFile(marker, 'utf8'));
+        const info = await stat(target);
+        return (recorded.digest === digest && recorded.size === info.size && recorded.mtimeMs === info.mtimeMs);
+    }
+    catch {
+        return false;
+    }
+}
+async function writeMarker(marker, target, digest) {
+    const info = await stat(target);
+    const record = { digest, size: info.size, mtimeMs: info.mtimeMs };
+    await writeFile(marker, `${JSON.stringify(record)}\n`);
+}
+/** Leftovers of a download that died with its process; only safe while holding the model lock. */
+async function sweepPartialDownloads(target) {
+    const prefix = `${basename(target)}${PARTIAL_DOWNLOAD_INFIX}`;
+    const names = await readdir(dirname(target)).catch(() => []);
+    await Promise.all(names
+        .filter((name) => name.startsWith(prefix))
+        .map((name) => rm(join(dirname(target), name), { force: true }).catch(() => { })));
+}
+async function downloadVerified(url, target, pinned, fetchImpl) {
+    const partial = `${target}${PARTIAL_DOWNLOAD_INFIX}${process.pid}-${randomUUID().slice(0, 8)}`;
+    let handle;
+    try {
+        const response = await fetchImpl(url);
+        if (!response.ok || !response.body) {
+            throw new Error(`HTTP ${response.status} downloading ${pinned.file}`);
+        }
+        const encoding = response.headers.get('content-encoding');
+        const declared = Number(response.headers.get('content-length') ?? Number.NaN);
+        const expected = !encoding || encoding === 'identity' ? declared : Number.NaN;
+        handle = await open(partial, 'wx');
+        const hash = createHash('sha256');
+        let received = 0;
+        for await (const chunk of response.body) {
+            hash.update(chunk);
+            received += chunk.byteLength;
+            let offset = 0;
+            while (offset < chunk.byteLength) {
+                const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset);
+                offset += bytesWritten;
+            }
+        }
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (Number.isFinite(expected) && received !== expected) {
+            throw new ModelFileDownloadError(`download of ${pinned.file} stopped at ${received} of ${expected} bytes`);
+        }
+        const actual = `sha256:${hash.digest('hex')}`;
+        if (actual !== pinned.digest) {
+            throw new ModelFileDownloadError(`download of ${pinned.file} does not match its pin (got ${actual})`);
+        }
+        await rename(partial, target);
+    }
+    catch (err) {
+        await handle?.close().catch(() => { });
+        await rm(partial, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Make sure a pinned model file sits in the transformers cache whole.
+ *
+ * transformers.js streams a download straight into its final cache path and
+ * hands that path to onnxruntime, so a reader that arrives mid-write parses
+ * part of a protobuf. The failure was wild-caught on first-run installs over
+ * slower connections: two "Protobuf parsing failed" loads, then vector memory
+ * off for the whole session, while the file finished correctly moments later.
+ * Here the bytes land in a sibling temp file, are checked against the pin,
+ * and appear at the cache path only by an atomic rename, so transformers
+ * finds a complete file and never downloads it. Call it under
+ * {@link withTransformersModelCacheLock}.
+ */
+export async function ensureVerifiedModelFile(cacheDir, modelId, pinned, source) {
+    const target = cacheFilePath(cacheDir, modelId, pinned.file);
+    const marker = `${target}${VERIFIED_MARKER_SUFFIX}`;
+    await mkdir(dirname(target), { recursive: true });
+    await sweepPartialDownloads(target);
+    const present = await stat(target).then((info) => info.isFile(), () => false);
+    if (present) {
+        if (await markerVouches(marker, target, pinned.digest))
+            return 'cached';
+        // Hashed once per file; the marker spares every later boot the read.
+        if ((await sha256File(target)) === pinned.digest) {
+            await writeMarker(marker, target, pinned.digest);
+            return 'cached';
+        }
+        log.warn(`[models] cached ${modelId}/${pinned.file} is incomplete or altered; downloading it`);
+    }
+    await rm(marker, { force: true });
+    await rm(target, { force: true });
+    await downloadVerified(remoteFileUrl(source, modelId, pinned), target, pinned, source.fetchImpl ?? fetch);
+    await writeMarker(marker, target, pinned.digest);
+    return 'downloaded';
+}
+/**
+ * True when Node is reporting that `specifier` itself is not installed, rather
+ * than the package being present and failing to load.
+ *
+ * `@huggingface/transformers` and `kokoro-js` are optional peers that an
+ * ordinary npm install omits, so absence is a supported configuration and must
+ * be distinguishable from breakage before anything picks a log level. Matched
+ * on the resolver's error code plus the specifier it names, not on a substring
+ * of the message: a genuine failure *inside* transformers also mentions the
+ * package, and used to be misreported as "not installed".
+ */
+export function isMissingModule(err, specifier) {
+    if (!(err instanceof Error))
+        return false;
+    const { code } = err;
+    if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND')
+        return false;
+    const escaped = specifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(String.raw `Cannot find (?:package|module) '${escaped}'`).test(err.message);
+}
+async function defaultLoadEnv() {
+    const mod = (await import('@huggingface/transformers'));
+    return mod.env;
+}
+const pinned = new Set();
+let globalsAligned = false;
+/**
+ * transformers.js decides whether to WRITE a downloaded file to its FS cache
+ * with `response instanceof Response`, reading the *global* `Response`. In the
+ * bundled daemon, some dependency leaves `globalThis.fetch` and
+ * `globalThis.Response` sourced from different realms — so a real fetch's
+ * response fails `instanceof Response`, transformers caches NOTHING, and the
+ * ONNX load (which resolves by cached file path) throws "Unable to get model
+ * file path or buffer". Re-sourcing `fetch` + `Response` + friends from one
+ * `undici` restores the invariant, so caching (and offline reuse) works.
+ *
+ * `undici` IS Node's own fetch implementation, so this is a functional no-op
+ * for callers — it only realigns the class identities. Best-effort.
+ */
+async function alignFetchGlobals() {
+    if (globalsAligned)
+        return;
+    try {
+        const u = (await import('undici'));
+        const g = globalThis;
+        for (const k of ['fetch', 'Response', 'Headers', 'Request', 'FormData', 'File', 'Blob']) {
+            if (typeof u[k] !== 'undefined')
+                g[k] = u[k];
+        }
+        globalsAligned = true;
+    }
+    catch (err) {
+        log.warn(`could not align fetch globals: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Point transformers.js at `cacheDir` (and repair the fetch/Response global
+ * mismatch that otherwise defeats its cache). Idempotent per dir, and
+ * best-effort: on failure we log and let the caller proceed on the upstream
+ * default rather than hard-failing (worst case the original bug resurfaces,
+ * which is no worse than not calling this).
+ */
+export async function pinTransformersCacheDir(cacheDir, loadEnv = defaultLoadEnv) {
+    await alignFetchGlobals();
+    if (pinned.has(cacheDir))
+        return;
+    try {
+        await mkdir(cacheDir, { recursive: true });
+        const env = await loadEnv();
+        env.cacheDir = cacheDir;
+        env.useFSCache = true;
+        env.allowRemoteModels = true;
+        pinned.add(cacheDir);
+    }
+    catch (err) {
+        if (isMissingModule(err, TRANSFORMERS_MODULE)) {
+            // Optional peer absent — nothing to pin, and nothing wrong. The caller
+            // that actually needs the model surfaces the actionable install message.
+            log.debug(`skipped transformers cache pin: ${TRANSFORMERS_MODULE} is not installed`);
+            return;
+        }
+        log.warn(`could not pin transformers cache dir "${cacheDir}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/utils/disk-space.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Free-disk-space preflight for model downloads.
+ *
+ * On-device weights are the largest thing gezel ever writes: a llama.cpp Q4 is
+ * a few GiB, but a ds4 GGUF is 80–200+ GiB. Without a preflight the failure
+ * mode is the worst possible one — hours of download, then `ENOSPC` at 95%,
+ * with a half-written `.partial` still occupying the disk it just filled.
+ * Checking first turns that into one instant, actionable sentence.
+ *
+ * Two rules keep this from becoming its own failure source:
+ *
+ *   1. **Never block on unknown.** `statfs` is not available on every
+ *      filesystem (network mounts, some container overlays). A check we
+ *      couldn't perform returns `known: false` and callers proceed — a missing
+ *      measurement must not stop a download that would have succeeded.
+ *   2. **Measure the nearest existing ancestor.** The destination directory is
+ *      usually created just before the download, but callers may preflight
+ *      earlier; walking up to a directory that exists keeps the check honest
+ *      instead of silently degrading to `known: false`.
+ */
+/**
+ * Headroom demanded on top of the download itself. A disk filled to the last
+ * byte is a broken machine, not a successful install: macOS/Linux need free
+ * space for swap, logs, and the atomic `.partial` → final rename. Scales with
+ * the download so a 200 GiB model reserves proportionally more than a 4 GiB
+ * one, with a 2 GiB floor for small models.
+ */
+export declare function requiredSlackBytes(downloadBytes: number): number;
+export interface DiskSpaceCheck {
+    /**
+     * False when the filesystem couldn't be measured. `ok` is always true in
+     * that case — callers must not treat an unmeasurable disk as a full one.
+     */
+    known: boolean;
+    ok: boolean;
+    freeBytes: number;
+    /** Download size plus {@link requiredSlackBytes}. */
+    requiredBytes: number;
+}
+/** Injectable for tests — the unmeasurable-filesystem branch can't be
+ *  reproduced with a real path on a normal dev machine. */
+export type StatfsImpl = (path: string) => Promise<{
+    bsize: number;
+    bavail: number;
+}>;
+/**
+ * Whether `dir`'s filesystem can hold `downloadBytes` more, plus headroom.
+ *
+ * `dir` need not exist yet — the nearest existing ancestor is measured, which
+ * is the same filesystem in every layout gezel creates.
+ */
+export declare function checkDiskSpace(dir: string, downloadBytes: number, statfsImpl?: StatfsImpl): Promise<DiskSpaceCheck>;
+/** One-sentence, user-facing shortfall message. Already friendly — callers
+ *  surface it verbatim in an install-error banner. */
+export declare function describeDiskShortfall(check: DiskSpaceCheck, what: string): string;

package/dist/utils/disk-space.js

@@ -0,0 +1,72 @@
+/**
+ * Free-disk-space preflight for model downloads.
+ *
+ * On-device weights are the largest thing gezel ever writes: a llama.cpp Q4 is
+ * a few GiB, but a ds4 GGUF is 80–200+ GiB. Without a preflight the failure
+ * mode is the worst possible one — hours of download, then `ENOSPC` at 95%,
+ * with a half-written `.partial` still occupying the disk it just filled.
+ * Checking first turns that into one instant, actionable sentence.
+ *
+ * Two rules keep this from becoming its own failure source:
+ *
+ *   1. **Never block on unknown.** `statfs` is not available on every
+ *      filesystem (network mounts, some container overlays). A check we
+ *      couldn't perform returns `known: false` and callers proceed — a missing
+ *      measurement must not stop a download that would have succeeded.
+ *   2. **Measure the nearest existing ancestor.** The destination directory is
+ *      usually created just before the download, but callers may preflight
+ *      earlier; walking up to a directory that exists keeps the check honest
+ *      instead of silently degrading to `known: false`.
+ */
+import { statfs } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const GIB = 1024 ** 3;
+/**
+ * Headroom demanded on top of the download itself. A disk filled to the last
+ * byte is a broken machine, not a successful install: macOS/Linux need free
+ * space for swap, logs, and the atomic `.partial` → final rename. Scales with
+ * the download so a 200 GiB model reserves proportionally more than a 4 GiB
+ * one, with a 2 GiB floor for small models.
+ */
+export function requiredSlackBytes(downloadBytes) {
+    return Math.max(2 * GIB, Math.ceil(downloadBytes * 0.02));
+}
+/**
+ * Whether `dir`'s filesystem can hold `downloadBytes` more, plus headroom.
+ *
+ * `dir` need not exist yet — the nearest existing ancestor is measured, which
+ * is the same filesystem in every layout gezel creates.
+ */
+export async function checkDiskSpace(dir, downloadBytes, statfsImpl = statfs) {
+    const requiredBytes = downloadBytes + requiredSlackBytes(downloadBytes);
+    const freeBytes = await freeBytesFor(dir, statfsImpl);
+    if (freeBytes === null) {
+        return { known: false, ok: true, freeBytes: 0, requiredBytes };
+    }
+    return { known: true, ok: freeBytes >= requiredBytes, freeBytes, requiredBytes };
+}
+async function freeBytesFor(dir, statfsImpl) {
+    let candidate = dir;
+    for (let i = 0; i < 64; i++) {
+        try {
+            const st = await statfsImpl(candidate);
+            // `bavail` (not `bfree`) is what an unprivileged process may actually
+            // use — the difference is the root-reserved pool, which we can't have.
+            return st.bsize * st.bavail;
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return null;
+            candidate = parent;
+        }
+    }
+    return null;
+}
+/** One-sentence, user-facing shortfall message. Already friendly — callers
+ *  surface it verbatim in an install-error banner. */
+export function describeDiskShortfall(check, what) {
+    const need = (check.requiredBytes / GIB).toFixed(1);
+    const have = (check.freeBytes / GIB).toFixed(1);
+    return `Not enough disk space for ${what}: needs about ${need} GB free (including working headroom), but this disk has ${have} GB. Free up space or choose a smaller model.`;
+}

package/dist/utils/download-common.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Shared primitives for the model download helpers — the event/result
+ * contract, retry/backoff math, partial-file sizing, friendly error mapping,
+ * and the honest gezel User-Agent. Both the classic streaming downloader
+ * (`download-with-retry.ts`) and the Xet reconstruction downloader
+ * (`xet-download.ts`) build on these, so neither has to import the other at
+ * runtime (avoids a cycle).
+ */
+export declare const downloadLog: import("@bendyline/gezel").Logger;
+/**
+ * Honest User-Agent sent on every model-download request. We identify
+ * ourselves as gezel rather than impersonating a browser or the huggingface
+ * client — HF's Xet backend serves anonymous public reads, and being
+ * transparent about who we are is the right posture for a third-party client
+ * fetching public weights on the user's behalf.
+ */
+export declare const GEZEL_DOWNLOAD_UA = "gezel/0.0.0 (+https://github.com/bendyline/gezel)";
+/**
+ * Headers for an HF control-plane request. An optional operator token raises
+ * public-model rate limits, but is never forwarded to Xet/CAS/CDN hosts.
+ */
+export declare function huggingFaceRequestHeaders(url: string, token?: string | undefined): Record<string, string>;
+/** Upper bound on *consecutive* failed attempts that made no headway. 5 covers
+ * the dominant on-device failure modes (transient ISP blip, mid-day
+ * congestion, brief HF rate-limit) without giving up too readily. An attempt
+ * that moved real bytes refunds this budget — see `DownloadRetryBudget`. */
+export declare const DEFAULT_MAX_RETRIES = 5;
+/** Absolute ceiling on attempts for one file, however much progress is being
+ * made. A 30 GB download over a link that drops every 200 MB legitimately
+ * needs a lot of resumes; this only exists so a pathological
+ * fails-after-one-chunk loop can't spin forever. */
+export declare const MAX_TOTAL_ATTEMPTS = 100;
+/** Forward progress that counts as "this transfer is alive" and refunds the
+ * consecutive-failure budget. Deliberately larger than one HTTP chunk so a
+ * server that hands us 64 KiB and hangs up can't refill the budget forever. */
+export declare const PROGRESS_REFUND_BYTES: number;
+/** No-bytes-arrived window before we declare a transfer dead. */
+export declare const DEFAULT_CHUNK_TIMEOUT_MS = 20000;
+export type DownloadEvent = {
+    type: 'progress';
+    bytesWritten: number;
+    totalBytes: number;
+} | {
+    type: 'retrying';
+    /** Which attempt is starting (1-based). */
+    attempt: number;
+    maxAttempts: number;
+    /** Wait before next attempt. */
+    delayMs: number;
+    /** Friendly description of why the previous attempt failed. */
+    reason: string;
+    /** Bytes already on disk that the next attempt will resume from. */
+    resumeFromBytes: number;
+};
+export type DownloadResult = {
+    kind: 'ok';
+    bytesWritten: number;
+    partialPath: string;
+    /**
+     * sha256 of the file, computed inline while streaming, IFF the whole
+     * file was written from offset 0 in a single attempt (HTTP 200, no
+     * resume). Absent on resumed/appended transfers and the Xet path,
+     * where the inline hasher never saw the earlier bytes — the caller
+     * must fall back to reading the file back to verify in those cases.
+     */
+    sha256?: string;
+} | {
+    kind: 'aborted';
+    bytesWritten: number;
+    partialPath: string;
+} | {
+    kind: 'error';
+    /** User-facing message. Already friendly — don't add prefixes in the UI. */
+    error: string;
+    /** Attempts taken before giving up. */
+    attemptsMade: number;
+    /** Whatever bytes are on the `.partial` file at give-up time. */
+    bytesWritten: number;
+};
+export declare function existingPartialSize(path: string): number;
+export declare function retryDelayMs(retryIndex: number): number;
+export declare function sleepRespectingAbort(ms: number, signal: AbortSignal | undefined): Promise<boolean>;
+/**
+ * Attempt accounting for a resumable download.
+ *
+ * The naive "5 attempts per file, then give up" budget is what made the
+ * first-run model install fail with a bare "network error": a 12 GB GGUF over
+ * a link that drops every couple of minutes burns all five attempts inside the
+ * first ten minutes and quits — even though every one of those attempts moved
+ * hundreds of megabytes onto disk and the transfer was, in the only sense the
+ * user cares about, working.
+ *
+ * So the budget counts *consecutive failures that made no headway*. An attempt
+ * that pushed the byte high-water mark forward by at least
+ * `PROGRESS_REFUND_BYTES` resets the counter (and the backoff schedule with
+ * it, since the network clearly isn't down). `MAX_TOTAL_ATTEMPTS` is the
+ * backstop for a server that hands us a little data and dies every single
+ * time.
+ *
+ * A budget constructed with `maxConsecutive <= 1` never refunds, so callers
+ * that pass `maxRetries: 1` still get exactly one attempt.
+ */
+export declare class DownloadRetryBudget {
+    private readonly maxConsecutive;
+    private readonly maxTotal;
+    private consecutiveFailures;
+    private attemptsStarted;
+    private highWaterBytes;
+    constructor(maxConsecutive: number, startBytes?: number, maxTotal?: number);
+    /** True while another attempt is permitted. */
+    canAttempt(): boolean;
+    /** Call once at the top of each attempt. */
+    beginAttempt(): number;
+    /** Total attempts started so far — reported in the terminal error. */
+    get attemptsMade(): number;
+    /** Record a transient failure at `bytesWritten` bytes of on-disk progress. */
+    recordFailure(bytesWritten: number): void;
+    /** Wait to serve before the next attempt, based on the consecutive streak. */
+    nextDelayMs(): number;
+    /** 1-based number of the attempt about to start, for `retrying` events. */
+    get nextAttemptLabel(): number;
+    get maxAttempts(): number;
+}
+/**
+ * Map raw fetch/network errors to a single user-readable sentence.
+ * Keep these short — the UI shows them inline in a small banner.
+ */
+export declare function friendlyFetchError(err: unknown): string;
+export declare function friendlyStreamError(err: unknown): string;
+export declare function friendlyStatusError(status: number, statusText: string, _url: string): string;
+export declare function rawErrorString(err: unknown): string;
+/** Friendly-error helpers so providers that build their own non-fetch error
+ * events can produce consistent copy. */
+export declare const friendlyErrors: {
+    fetch: typeof friendlyFetchError;
+    stream: typeof friendlyStreamError;
+    status: typeof friendlyStatusError;
+};