threadshelf 1.2.0

package/dist/src/embedding.js

@@ -0,0 +1,59 @@
+import { dataPath } from './paths.js';
+const MODEL = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
+const DIMENSION = 384;
+export const getDimension = () => {
+    return DIMENSION;
+};
+const loadPipeline = async () => {
+    const { env, pipeline } = await import('@huggingface/transformers');
+    // Transformers.js caches model weights inside its own node_modules folder by
+    // default. For an `npx threadshelf` install that directory is disposable, so
+    // the ~50 MB model would be re-downloaded on every run. Keep it with the
+    // user's data instead.
+    env.cacheDir = process.env.THREADSHELF_MODEL_CACHE || dataPath('modelCache');
+    return (await pipeline('feature-extraction', MODEL, {
+        dtype: 'q8',
+        progress_callback: (p) => {
+            const info = p;
+            if (info.status === 'progress')
+                console.error('[embedding]', info.file, info.progress);
+        },
+    }));
+};
+export const createEmbedder = (load) => {
+    let pipeline;
+    return async (texts) => {
+        if (texts.length === 0)
+            return [];
+        pipeline ??= load().catch((error) => {
+            pipeline = undefined;
+            throw error;
+        });
+        const pipe = await pipeline;
+        const options = { pooling: 'mean', normalize: true };
+        try {
+            const out = await pipe(texts, options);
+            const data = Array.from(out.data);
+            const batchSize = out.dims?.[0] === texts.length ? texts.length : texts.length === 1 ? 1 : 0;
+            if (batchSize > 0 && data.length % batchSize === 0) {
+                const stride = data.length / batchSize;
+                return texts.map((_, index) => data.slice(index * stride, (index + 1) * stride));
+            }
+        }
+        catch (e) {
+            if (texts.length === 1)
+                throw e;
+        }
+        const results = [];
+        for (const text of texts) {
+            const out = await pipe(text, options);
+            results.push(Array.from(out.data));
+        }
+        return results;
+    };
+};
+export const embed = createEmbedder(loadPipeline);
+export const embedOne = async (text) => {
+    const [v] = await embed([text]);
+    return v;
+};

package/dist/src/env.js

@@ -0,0 +1,2 @@
+import { loadThreadShelfEnv } from './load-env.js';
+loadThreadShelfEnv();

package/dist/src/generation/config.js

@@ -0,0 +1,344 @@
+import { existsSync } from 'fs';
+import { mkdir, readFile, rename, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { dataPath } from '../paths.js';
+import { dirname, join, resolve } from 'path';
+import { randomUUID } from 'crypto';
+import { ValidationError } from '../validation.js';
+const KV_CACHE_PROFILES = ['default', 'quality', 'memory'];
+const SPECULATIVE_MODES = ['off', 'auto', 'aggressive'];
+const REASONING_EFFORTS = [
+    'default',
+    'off',
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+];
+let sessionOpenRouterApiKey = '';
+const warnedInvalidEnvironmentValues = new Set();
+export const generationConfigPath = () => resolve(process.env.GENERATION_CONFIG_PATH || dataPath('generationConfig'));
+const normalizePaths = (paths) => [
+    ...new Set(paths.map((path) => resolve(path.trim())).filter(Boolean)),
+];
+export const defaultModelDirectories = (env = process.env, home = homedir()) => {
+    const configured = (env.LLAMA_MODEL_PATHS || '')
+        .split(process.platform === 'win32' ? ';' : ':')
+        .filter(Boolean);
+    const defaults = env.THREADSHELF_DISABLE_DEFAULT_MODEL_PATHS === '1'
+        ? []
+        : [
+            join(home, '.lmstudio', 'models'),
+            join(home, '.lmstudio'),
+            join(home, '.cache', 'lm-studio', 'models'),
+            join(home, '.cache', 'llama.cpp'),
+            join(home, '.cache', 'huggingface', 'hub'),
+        ];
+    return normalizePaths([...configured, ...defaults]);
+};
+export const defaultDownloadDirectory = (env = process.env) => resolve(env.THREADSHELF_MODELS_PATH || dataPath('models'));
+const readStoredConfig = async () => {
+    try {
+        return JSON.parse(await readFile(generationConfigPath(), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid generation config JSON at ${generationConfigPath()}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+};
+const parseLocalBaseUrl = (value, field) => {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string' || value.length > 2048) {
+        throw new ValidationError(`Invalid ${field}`, { field });
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ValidationError(`Invalid ${field}: expected URL`, { field });
+    }
+    const host = url.hostname.toLowerCase();
+    if (!['localhost', '127.0.0.1', '::1', '[::1]'].includes(host)) {
+        throw new ValidationError(`Invalid ${field}: llama.cpp endpoint must be loopback-only`, {
+            field,
+        });
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw new ValidationError(`Invalid ${field}: expected HTTP(S)`, { field });
+    }
+    return url.toString().replace(/\/$/, '');
+};
+const parsePath = (value, field) => {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string' || value.length > 4096 || value.includes('\0')) {
+        throw new ValidationError(`Invalid ${field}`, { field });
+    }
+    const trimmed = value.trim();
+    if (!trimmed || /^[/\\]{2}/.test(trimmed)) {
+        throw new ValidationError(`Invalid ${field}: network paths are not allowed`, { field });
+    }
+    return resolve(trimmed);
+};
+const parseBoolean = (value, field) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new ValidationError(`Invalid ${field}`, { field });
+    return value;
+};
+const parseContextSize = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 512 || value > 1_048_576) {
+        throw new ValidationError('Invalid contextSize: expected integer from 512 to 1048576', {
+            field: 'contextSize',
+        });
+    }
+    return value;
+};
+const parseEnum = (value, values, field) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !values.includes(value)) {
+        throw new ValidationError(`Invalid ${field}`, { field });
+    }
+    return value;
+};
+const parseInteger = (value, field, min, max) => {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new ValidationError(`Invalid ${field}: expected integer from ${min} to ${max}`, {
+            field,
+        });
+    }
+    return value;
+};
+const parseTensorSplit = (value) => {
+    if (value === undefined || value === '')
+        return undefined;
+    if (typeof value !== 'string' || value.length > 256) {
+        throw new ValidationError('Invalid tensorSplit', { field: 'tensorSplit' });
+    }
+    const parts = value.split(',').map((part) => part.trim());
+    if (parts.length === 0 ||
+        parts.length > 16 ||
+        parts.some((part) => !part || !Number.isFinite(Number(part)) || Number(part) <= 0)) {
+        throw new ValidationError('Invalid tensorSplit: expected positive comma-separated weights', {
+            field: 'tensorSplit',
+        });
+    }
+    return parts.join(',');
+};
+const parseDirectories = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > 32) {
+        throw new ValidationError('Invalid modelDirectories: expected at most 32 paths', {
+            field: 'modelDirectories',
+        });
+    }
+    return normalizePaths(value.map((entry, index) => {
+        const path = parsePath(entry, `modelDirectories[${index}]`);
+        if (!path) {
+            throw new ValidationError(`Invalid modelDirectories[${index}]: empty path`, {
+                field: 'modelDirectories',
+            });
+        }
+        return path;
+    }));
+};
+const resolveApiKey = () => sessionOpenRouterApiKey || process.env.OPENROUTER_API_KEY || '';
+export const getOpenRouterApiKey = () => resolveApiKey();
+export const clearSessionOpenRouterApiKeyForTests = () => {
+    sessionOpenRouterApiKey = '';
+};
+const parseEnvironmentOverride = (name, parser) => {
+    const value = process.env[name];
+    if (value === undefined)
+        return undefined;
+    try {
+        return parser(value);
+    }
+    catch (error) {
+        const warningKey = `${name}\0${value}`;
+        if (!warnedInvalidEnvironmentValues.has(warningKey)) {
+            warnedInvalidEnvironmentValues.add(warningKey);
+            console.warn(`[generation] Ignoring invalid ${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return undefined;
+    }
+};
+export const effectiveModelDirectories = (config) => normalizePaths([
+    config.downloadDirectory,
+    ...config.modelDirectories,
+    ...config.defaultModelDirectories,
+]);
+export const llamaCppConfigChanged = (previous, next) => JSON.stringify(previous.llamaCpp) !== JSON.stringify(next.llamaCpp);
+export const getGenerationConfig = async () => {
+    const stored = await readStoredConfig();
+    return {
+        experimentalAlpha: true,
+        llamaCpp: {
+            executablePath: process.env.LLAMA_CPP_SERVER ||
+                process.env.LLAMA_SERVER_PATH ||
+                stored.llamaCpp?.executablePath,
+            baseUrl: parseEnvironmentOverride('LLAMA_CPP_BASE_URL', (value) => parseLocalBaseUrl(value, 'LLAMA_CPP_BASE_URL')) ?? parseLocalBaseUrl(stored.llamaCpp?.baseUrl, 'baseUrl'),
+            modelDirectories: normalizePaths(stored.llamaCpp?.modelDirectories ?? []),
+            defaultModelDirectories: defaultModelDirectories(),
+            downloadDirectory: parseEnvironmentOverride('THREADSHELF_MODELS_PATH', (value) => parsePath(value, 'THREADSHELF_MODELS_PATH')) ??
+                (stored.llamaCpp?.downloadDirectory
+                    ? resolve(stored.llamaCpp.downloadDirectory)
+                    : defaultDownloadDirectory()),
+            contextSize: parseEnvironmentOverride('LLAMA_CPP_CONTEXT_SIZE', (value) => parseContextSize(Number(value))) ??
+                stored.llamaCpp?.contextSize ??
+                8192,
+            acceleration: parseEnvironmentOverride('LLAMA_CPP_ACCELERATION', (value) => parseEnum(value, ['auto', 'cpu', 'gpu', 'hybrid', 'multi-gpu'], 'LLAMA_CPP_ACCELERATION')) ??
+                stored.llamaCpp?.acceleration ??
+                'auto',
+            gpuLayers: parseEnvironmentOverride('LLAMA_CPP_GPU_LAYERS', (value) => parseInteger(Number(value), 'LLAMA_CPP_GPU_LAYERS', 1, 999)) ??
+                stored.llamaCpp?.gpuLayers ??
+                20,
+            splitMode: parseEnvironmentOverride('LLAMA_CPP_SPLIT_MODE', (value) => parseEnum(value, ['layer', 'row'], 'LLAMA_CPP_SPLIT_MODE')) ??
+                stored.llamaCpp?.splitMode ??
+                'layer',
+            mainGpu: parseEnvironmentOverride('LLAMA_CPP_MAIN_GPU', (value) => parseInteger(Number(value), 'LLAMA_CPP_MAIN_GPU', 0, 31)) ??
+                stored.llamaCpp?.mainGpu ??
+                0,
+            tensorSplit: parseEnvironmentOverride('LLAMA_CPP_TENSOR_SPLIT', parseTensorSplit) ??
+                stored.llamaCpp?.tensorSplit,
+            threads: parseEnvironmentOverride('LLAMA_CPP_THREADS', (value) => parseInteger(Number(value), 'LLAMA_CPP_THREADS', -1, 1024)) ??
+                stored.llamaCpp?.threads ??
+                -1,
+            flashAttention: parseEnvironmentOverride('LLAMA_CPP_FLASH_ATTENTION', (value) => parseEnum(value, ['auto', 'on', 'off'], 'LLAMA_CPP_FLASH_ATTENTION')) ??
+                stored.llamaCpp?.flashAttention ??
+                'auto',
+            kvCache: parseEnvironmentOverride('LLAMA_CPP_KV_CACHE', (value) => parseEnum(value, KV_CACHE_PROFILES, 'LLAMA_CPP_KV_CACHE')) ??
+                stored.llamaCpp?.kvCache ??
+                'quality',
+            speculative: parseEnvironmentOverride('LLAMA_CPP_SPECULATIVE', (value) => parseEnum(value, SPECULATIVE_MODES, 'LLAMA_CPP_SPECULATIVE')) ??
+                stored.llamaCpp?.speculative ??
+                'auto',
+            reasoningEffort: parseEnvironmentOverride('LLAMA_CPP_REASONING_EFFORT', (value) => parseEnum(value, REASONING_EFFORTS, 'LLAMA_CPP_REASONING_EFFORT')) ??
+                stored.llamaCpp?.reasoningEffort ??
+                'medium',
+        },
+        openRouter: {
+            baseUrl: (process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1').replace(/\/$/, ''),
+            apiKeyConfigured: Boolean(resolveApiKey()),
+            enforceZdr: stored.schemaVersion === 2 ? (stored.openRouter?.enforceZdr ?? false) : false,
+            denyDataCollection: stored.schemaVersion === 2 ? (stored.openRouter?.denyDataCollection ?? false) : false,
+        },
+        diagnostics: {
+            persistErrorLogs: stored.schemaVersion === 2 ? (stored.diagnostics?.persistErrorLogs ?? true) : true,
+        },
+    };
+};
+export const updateGenerationConfig = async (update) => {
+    if (!update || typeof update !== 'object' || Array.isArray(update)) {
+        throw new ValidationError('Invalid generation config');
+    }
+    const current = await readStoredConfig();
+    const llamaUpdate = update.llamaCpp;
+    const openRouterUpdate = update.openRouter;
+    const diagnosticsUpdate = update.diagnostics;
+    if (llamaUpdate !== undefined &&
+        (typeof llamaUpdate !== 'object' || Array.isArray(llamaUpdate))) {
+        throw new ValidationError('Invalid llamaCpp config', { field: 'llamaCpp' });
+    }
+    if (diagnosticsUpdate !== undefined &&
+        (typeof diagnosticsUpdate !== 'object' || Array.isArray(diagnosticsUpdate))) {
+        throw new ValidationError('Invalid diagnostics config', { field: 'diagnostics' });
+    }
+    if (openRouterUpdate !== undefined &&
+        (typeof openRouterUpdate !== 'object' || Array.isArray(openRouterUpdate))) {
+        throw new ValidationError('Invalid openRouter config', { field: 'openRouter' });
+    }
+    let nextSessionOpenRouterApiKey = sessionOpenRouterApiKey;
+    if (openRouterUpdate?.apiKey !== undefined) {
+        if (typeof openRouterUpdate.apiKey !== 'string' ||
+            openRouterUpdate.apiKey.length > 4096 ||
+            openRouterUpdate.apiKey.includes('\0')) {
+            throw new ValidationError('Invalid apiKey', { field: 'apiKey' });
+        }
+        nextSessionOpenRouterApiKey = openRouterUpdate.apiKey.trim();
+    }
+    const clearApiKey = parseBoolean(openRouterUpdate?.clearApiKey, 'clearApiKey');
+    if (clearApiKey === true)
+        nextSessionOpenRouterApiKey = '';
+    const next = {
+        schemaVersion: 2,
+        llamaCpp: {
+            executablePath: llamaUpdate?.executablePath !== undefined
+                ? parsePath(llamaUpdate.executablePath, 'executablePath')
+                : current.llamaCpp?.executablePath,
+            baseUrl: llamaUpdate?.baseUrl !== undefined
+                ? parseLocalBaseUrl(llamaUpdate.baseUrl, 'baseUrl')
+                : current.llamaCpp?.baseUrl,
+            modelDirectories: parseDirectories(llamaUpdate?.modelDirectories) ?? current.llamaCpp?.modelDirectories ?? [],
+            downloadDirectory: (llamaUpdate?.downloadDirectory !== undefined
+                ? parsePath(llamaUpdate.downloadDirectory, 'downloadDirectory')
+                : current.llamaCpp?.downloadDirectory) ?? undefined,
+            contextSize: parseContextSize(llamaUpdate?.contextSize) ?? current.llamaCpp?.contextSize ?? 8192,
+            acceleration: parseEnum(llamaUpdate?.acceleration, ['auto', 'cpu', 'gpu', 'hybrid', 'multi-gpu'], 'acceleration') ??
+                current.llamaCpp?.acceleration ??
+                'auto',
+            gpuLayers: parseInteger(llamaUpdate?.gpuLayers, 'gpuLayers', 1, 999) ??
+                current.llamaCpp?.gpuLayers ??
+                20,
+            splitMode: parseEnum(llamaUpdate?.splitMode, ['layer', 'row'], 'splitMode') ??
+                current.llamaCpp?.splitMode ??
+                'layer',
+            mainGpu: parseInteger(llamaUpdate?.mainGpu, 'mainGpu', 0, 31) ?? current.llamaCpp?.mainGpu ?? 0,
+            tensorSplit: llamaUpdate?.tensorSplit !== undefined
+                ? parseTensorSplit(llamaUpdate.tensorSplit)
+                : current.llamaCpp?.tensorSplit,
+            threads: parseInteger(llamaUpdate?.threads, 'threads', -1, 1024) ?? current.llamaCpp?.threads ?? -1,
+            flashAttention: parseEnum(llamaUpdate?.flashAttention, ['auto', 'on', 'off'], 'flashAttention') ??
+                current.llamaCpp?.flashAttention ??
+                'auto',
+            kvCache: parseEnum(llamaUpdate?.kvCache, KV_CACHE_PROFILES, 'kvCache') ??
+                current.llamaCpp?.kvCache ??
+                'quality',
+            speculative: parseEnum(llamaUpdate?.speculative, SPECULATIVE_MODES, 'speculative') ??
+                current.llamaCpp?.speculative ??
+                'auto',
+            reasoningEffort: parseEnum(llamaUpdate?.reasoningEffort, REASONING_EFFORTS, 'reasoningEffort') ??
+                current.llamaCpp?.reasoningEffort ??
+                'medium',
+        },
+        openRouter: {
+            enforceZdr: parseBoolean(openRouterUpdate?.enforceZdr, 'enforceZdr') ??
+                (current.schemaVersion === 2 ? current.openRouter?.enforceZdr : undefined) ??
+                false,
+            denyDataCollection: parseBoolean(openRouterUpdate?.denyDataCollection, 'denyDataCollection') ??
+                (current.schemaVersion === 2 ? current.openRouter?.denyDataCollection : undefined) ??
+                false,
+        },
+        diagnostics: {
+            persistErrorLogs: parseBoolean(diagnosticsUpdate?.persistErrorLogs, 'persistErrorLogs') ??
+                (current.schemaVersion === 2 ? current.diagnostics?.persistErrorLogs : undefined) ??
+                true,
+        },
+    };
+    const path = generationConfigPath();
+    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);
+    sessionOpenRouterApiKey = nextSessionOpenRouterApiKey;
+    return getGenerationConfig();
+};
+export const generationPathExists = (path) => existsSync(path);

package/dist/src/generation/downloader.js

@@ -0,0 +1,172 @@
+import { createHash } from 'crypto';
+import { createReadStream, createWriteStream } from 'fs';
+import { rename, rm, stat } from 'fs/promises';
+import { Readable, Transform } from 'stream';
+import { pipeline } from 'stream/promises';
+export class DownloadHashMismatchError extends Error {
+    expected;
+    actual;
+    url;
+    constructor(expected, actual, url) {
+        super(`SHA-256 mismatch for ${url}: expected ${expected}, got ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+        this.url = url;
+        this.name = 'DownloadHashMismatchError';
+    }
+}
+const DEFAULT_ATTEMPTS = 4;
+const DEFAULT_STALL_TIMEOUT_MS = 60_000;
+const partPath = (destination) => `${destination}.part`;
+const fileSize = async (path) => {
+    try {
+        const info = await stat(path);
+        return info.isFile() ? info.size : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+/** Re-reads an existing `.part` so a resumed transfer keeps a single-pass digest. */
+const hashExistingBytes = async (path, hash) => {
+    await pipeline(createReadStream(path), new Transform({
+        transform(chunk, _encoding, callback) {
+            hash.update(chunk);
+            callback();
+        },
+    }));
+};
+const isRetryableStatus = (status) => status === 408 || status === 425 || status === 429 || status >= 500;
+const isRetryableError = (error) => {
+    if (error instanceof DownloadHashMismatchError)
+        return false;
+    if (error instanceof HttpStatusError)
+        return isRetryableStatus(error.status);
+    // Network-level faults surface as TypeError from fetch or as errno codes from
+    // the stream. Both are worth another attempt; a resumed range picks up where
+    // the broken transfer stopped.
+    return true;
+};
+class HttpStatusError extends Error {
+    status;
+    constructor(status, url) {
+        super(`Download failed (${status}) for ${url}`);
+        this.status = status;
+        this.name = 'HttpStatusError';
+    }
+}
+const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 8000);
+const delay = (ms, signal) => new Promise((resolveDelay, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolveDelay();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+export const assertDownloadUrl = (url) => {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error('Download URL must use HTTPS or HTTP');
+    }
+    return parsed;
+};
+export const downloadToFile = async (url, destination, { sha256, expectedBytes, onProgress, signal, attempts = DEFAULT_ATTEMPTS, stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS, headers = {}, fetchImpl = fetch, resume = true, } = {}) => {
+    const parsed = assertDownloadUrl(url);
+    const target = partPath(destination);
+    let lastError;
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt += 1) {
+        signal?.throwIfAborted();
+        const existing = resume ? await fileSize(target) : 0;
+        if (!resume && existing > 0)
+            await rm(target, { force: true });
+        const stallController = new AbortController();
+        const attemptSignal = signal
+            ? AbortSignal.any([signal, stallController.signal])
+            : stallController.signal;
+        let stallTimer;
+        const armStallTimer = () => {
+            clearTimeout(stallTimer);
+            stallTimer = setTimeout(() => stallController.abort(new Error(`Download stalled for ${stallTimeoutMs}ms`)), stallTimeoutMs);
+            stallTimer.unref?.();
+        };
+        try {
+            armStallTimer();
+            const response = await fetchImpl(parsed, {
+                redirect: 'follow',
+                signal: attemptSignal,
+                headers: {
+                    'User-Agent': 'ThreadShelf',
+                    ...headers,
+                    ...(existing > 0 ? { Range: `bytes=${existing}-` } : {}),
+                },
+            });
+            if (!response.ok)
+                throw new HttpStatusError(response.status, url);
+            if (!response.body)
+                throw new Error(`Download returned no body for ${url}`);
+            // A server that ignores Range answers 200 with the whole file; appending
+            // to the partial file would corrupt it, so start over in that case.
+            const resumed = existing > 0 && response.status === 206;
+            if (existing > 0 && !resumed)
+                await rm(target, { force: true });
+            const resumedBytes = resumed ? existing : 0;
+            const declared = Number(response.headers.get('content-length'));
+            const totalBytes = Number.isFinite(declared)
+                ? declared + resumedBytes
+                : (expectedBytes ?? undefined);
+            const hash = createHash('sha256');
+            if (resumedBytes > 0)
+                await hashExistingBytes(target, hash);
+            let downloadedBytes = resumedBytes;
+            onProgress?.({ downloadedBytes, totalBytes, resumedBytes, attempt });
+            const meter = new Transform({
+                transform(chunk, _encoding, callback) {
+                    hash.update(chunk);
+                    downloadedBytes += chunk.length;
+                    armStallTimer();
+                    onProgress?.({ downloadedBytes, totalBytes, resumedBytes, attempt });
+                    callback(null, chunk);
+                },
+            });
+            await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(target, { flags: resumed ? 'a' : 'w', mode: 0o600 }), { signal: attemptSignal });
+            clearTimeout(stallTimer);
+            const digest = hash.digest('hex');
+            if (sha256 && digest !== sha256.toLowerCase()) {
+                // Either the source changed or the bytes were tampered with. Keeping the
+                // partial file would poison every later resume.
+                await rm(target, { force: true });
+                throw new DownloadHashMismatchError(sha256.toLowerCase(), digest, url);
+            }
+            if (expectedBytes !== undefined && downloadedBytes !== expectedBytes) {
+                await rm(target, { force: true });
+                throw new Error(`Size mismatch for ${url}: expected ${expectedBytes} bytes, got ${downloadedBytes}`);
+            }
+            await rename(target, destination);
+            return { bytes: downloadedBytes, sha256: digest, resumedBytes, attempts: attempt };
+        }
+        catch (error) {
+            clearTimeout(stallTimer);
+            // A caller-driven abort is a cancellation, never a fault to retry.
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+            lastError = error;
+            if (attempt >= attempts || !isRetryableError(error))
+                break;
+            await delay(backoffMs(attempt), signal);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(`Download failed for ${url}`);
+};
+export const sha256File = async (path) => {
+    const hash = createHash('sha256');
+    await hashExistingBytes(path, hash);
+    return hash.digest('hex');
+};

package/dist/src/generation/error-log.js

@@ -0,0 +1,34 @@
+import { appendFile, mkdir, readFile, stat, writeFile } from 'fs/promises';
+import { basename, dirname, resolve } from 'path';
+import { dataPath } from '../paths.js';
+import { getGenerationConfig } from './config.js';
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+const KEEP_LOG_BYTES = 4 * 1024 * 1024;
+let pendingWrite = Promise.resolve();
+export const generationErrorLogPath = () => resolve(process.env.GENERATION_ERROR_LOG_PATH || dataPath('generationErrorLog'));
+const appendError = async (request, error) => {
+    if (request.persistDiagnostics === false)
+        return;
+    const config = await getGenerationConfig();
+    if (!config.diagnostics.persistErrorLogs)
+        return;
+    const path = generationErrorLogPath();
+    const message = error instanceof Error ? error.message : String(error);
+    const entry = [
+        `[${new Date().toISOString()}] provider=${request.provider} model=${basename(request.model)}`,
+        message,
+        '',
+    ].join('\n');
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, entry, { encoding: 'utf8', mode: 0o600 });
+    const size = await stat(path).then((value) => value.size);
+    if (size <= MAX_LOG_BYTES)
+        return;
+    const content = await readFile(path);
+    const tail = content.subarray(-KEEP_LOG_BYTES);
+    await writeFile(path, tail[0] === 0x0a ? tail.subarray(1) : tail, { mode: 0o600 });
+};
+export const persistGenerationError = (request, error) => {
+    pendingWrite = pendingWrite.then(() => appendError(request, error), () => appendError(request, error));
+    return pendingWrite;
+};