@rigour-labs/core 6.2.3 → 6.2.5

package/dist/inference/http-download.js

@@ -0,0 +1,132 @@
+/**
+ * Streaming HTTPS download for large binaries (models, engine archives).
+ *
+ * Uses node:https rather than global fetch: on large Hugging Face downloads
+ * undici's fetch measured ~1.7 MB/s where node:https reached ~17 MB/s on the
+ * same host and byte range, which made the first-run model download exceed
+ * any reasonable setup window.
+ *
+ * - follows at most MAX_REDIRECTS redirects, https only
+ * - resumes a kept partial file with a Range request (the prefix is re-hashed
+ *   so the SHA-256 still covers the whole file)
+ * - aborts when no bytes arrive for `stallTimeoutMs` instead of imposing a
+ *   wall-clock limit that a slow but healthy connection cannot meet
+ */
+import https from 'https';
+import fs from 'fs-extra';
+import { createHash } from 'crypto';
+import { Transform } from 'stream';
+import { pipeline } from 'stream/promises';
+const MAX_REDIRECTS = 5;
+const DEFAULT_STALL_TIMEOUT_MS = 30_000;
+export async function downloadToFile(url, destPath, options = {}) {
+    const stallMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    const get = options.get ?? httpsGet;
+    let existing = options.resume === false ? 0 : await partialSize(destPath);
+    let { response, etag } = await followRedirects(url, rangeFrom(existing), get, stallMs);
+    if (response.statusCode === 416 && existing > 0) {
+        // The partial is already at or past the end: start over once, from zero.
+        response.body.resume();
+        await fs.remove(destPath);
+        existing = 0;
+        ({ response, etag } = await followRedirects(url, rangeFrom(0), get, stallMs));
+    }
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        response.body.resume();
+        throw new Error(`HTTP ${response.statusCode} for ${url}`);
+    }
+    const resumed = response.statusCode === 206 && existing > 0;
+    const hash = createHash('sha256');
+    if (resumed)
+        await hashFilePrefix(destPath, hash);
+    const startBytes = resumed ? existing : 0;
+    const total = contentLength(response.headers, startBytes);
+    const bytes = await writeBody(response.body, destPath, hash, {
+        append: resumed, startBytes, total, stallMs, onProgress: options.onProgress,
+    });
+    return { sha256: hash.digest('hex'), bytes, etag };
+}
+function rangeFrom(offset) {
+    return offset > 0 ? { Range: `bytes=${offset}-` } : {};
+}
+async function partialSize(filePath) {
+    try {
+        return (await fs.stat(filePath)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+async function followRedirects(url, headers, get, timeoutMs) {
+    let current = url;
+    let etag = null;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (new URL(current).protocol !== 'https:') {
+            throw new Error(`Refusing non-https download URL: ${current}`);
+        }
+        const response = await get(current, headers, timeoutMs);
+        etag = etag ?? headerValue(response.headers, 'x-linked-etag') ?? headerValue(response.headers, 'etag');
+        const location = headerValue(response.headers, 'location');
+        if (response.statusCode >= 300 && response.statusCode < 400 && location) {
+            response.body.resume();
+            current = new URL(location, current).toString();
+            continue;
+        }
+        return { response, etag };
+    }
+    throw new Error(`Too many redirects downloading ${url}`);
+}
+async function writeBody(body, destPath, hash, opts) {
+    let downloaded = opts.startBytes;
+    let stallTimer;
+    const armStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => {
+            body.destroy(new Error(`Download stalled: no data for ${opts.stallMs / 1000}s`));
+        }, opts.stallMs);
+    };
+    const tap = new Transform({
+        transform(chunk, _encoding, callback) {
+            armStall();
+            hash.update(chunk);
+            downloaded += chunk.length;
+            opts.onProgress?.(downloaded, opts.total);
+            callback(null, chunk);
+        },
+    });
+    armStall();
+    try {
+        await pipeline(body, tap, fs.createWriteStream(destPath, { flags: opts.append ? 'a' : 'w' }));
+    }
+    finally {
+        clearTimeout(stallTimer);
+    }
+    return downloaded;
+}
+async function hashFilePrefix(filePath, hash) {
+    const stream = fs.createReadStream(filePath);
+    try {
+        for await (const chunk of stream)
+            hash.update(chunk);
+    }
+    finally {
+        stream.destroy();
+    }
+}
+function contentLength(headers, offset) {
+    const value = Number(headerValue(headers, 'content-length'));
+    return Number.isFinite(value) && value > 0 ? value + offset : null;
+}
+function headerValue(headers, name) {
+    const value = headers[name];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+const httpsGet = (url, headers, timeoutMs) => new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { 'user-agent': 'rigour-cli', ...headers } }, (res) => {
+        resolve({ statusCode: res.statusCode ?? 0, headers: res.headers, body: res });
+    });
+    request.setTimeout(timeoutMs, () => request.destroy(new Error(`No response from ${new URL(url).host} after ${timeoutMs / 1000}s`)));
+    request.on('error', reject);
+});

package/dist/inference/http-download.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/inference/http-download.test.js

@@ -0,0 +1,109 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { createHash } from 'crypto';
+import { Readable, PassThrough } from 'stream';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { downloadToFile } from './http-download.js';
+const PAYLOAD = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz');
+const sha = (b) => createHash('sha256').update(b).digest('hex');
+function response(statusCode, body = Buffer.alloc(0), headers = {}) {
+    return { statusCode, headers, body: Buffer.isBuffer(body) ? Readable.from([body]) : body };
+}
+/** Serves PAYLOAD, honouring Range unless told not to. */
+function server(opts = {}) {
+    const calls = [];
+    const get = async (url, headers) => {
+        calls.push({ url, headers });
+        const range = headers.Range?.match(/bytes=(\d+)-/);
+        if (range && opts.honourRange !== false) {
+            const start = Number(range[1]);
+            if (start >= PAYLOAD.length)
+                return response(416);
+            return response(206, PAYLOAD.subarray(start), { 'content-length': String(PAYLOAD.length - start) });
+        }
+        return response(200, PAYLOAD, { 'content-length': String(PAYLOAD.length), etag: opts.etag });
+    };
+    return { get, calls };
+}
+describe('downloadToFile', () => {
+    let dir;
+    let dest;
+    beforeEach(async () => {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-dl-'));
+        dest = path.join(dir, 'model.gguf.download');
+    });
+    afterEach(async () => { await fs.remove(dir); });
+    it('downloads the full body and hashes it', async () => {
+        const { get } = server({ etag: '"abc"' });
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result).toEqual({ sha256: sha(PAYLOAD), bytes: PAYLOAD.length, etag: '"abc"' });
+    });
+    it('follows redirects and keeps the x-linked-etag from the first hop', async () => {
+        const { get: origin, calls } = server();
+        const get = async (url, headers, timeout) => {
+            if (url === 'https://hub/model') {
+                return response(302, Buffer.alloc(0), { location: 'https://cdn/model', 'x-linked-etag': '"lfs-sha"' });
+            }
+            return origin(url, headers, timeout);
+        };
+        const result = await downloadToFile('https://hub/model', dest, { get });
+        expect(calls.map(c => c.url)).toEqual(['https://cdn/model']);
+        expect(result.etag).toBe('"lfs-sha"');
+    });
+    it('resumes a partial file with a Range request and hashes the whole file', async () => {
+        await fs.writeFile(dest, PAYLOAD.subarray(0, 10));
+        const { get, calls } = server();
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(calls[0].headers.Range).toBe('bytes=10-');
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result.sha256).toBe(sha(PAYLOAD));
+        expect(result.bytes).toBe(PAYLOAD.length);
+    });
+    it('restarts from zero when the server ignores Range', async () => {
+        await fs.writeFile(dest, Buffer.from('stale-bytes'));
+        const { get } = server({ honourRange: false });
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result.sha256).toBe(sha(PAYLOAD));
+    });
+    it('restarts when the partial is already past the end (416)', async () => {
+        await fs.writeFile(dest, Buffer.concat([PAYLOAD, Buffer.from('extra')]));
+        const { get, calls } = server();
+        await downloadToFile('https://host/model', dest, { get });
+        expect(calls).toHaveLength(2);
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+    });
+    it('rejects non-success responses without creating the file', async () => {
+        const get = async () => response(401);
+        await expect(downloadToFile('https://host/model', dest, { get })).rejects.toThrow('HTTP 401');
+        expect(await fs.pathExists(dest)).toBe(false);
+    });
+    it('refuses non-https URLs, including redirects to them', async () => {
+        const { get } = server();
+        await expect(downloadToFile('http://host/model', dest, { get })).rejects.toThrow('non-https');
+        const redirecting = async () => response(302, Buffer.alloc(0), { location: 'http://evil/model' });
+        await expect(downloadToFile('https://host/model', dest, { get: redirecting })).rejects.toThrow('non-https');
+    });
+    it('stops after too many redirects', async () => {
+        const loop = async (url) => response(302, Buffer.alloc(0), { location: `${url}x` });
+        await expect(downloadToFile('https://host/m', dest, { get: loop })).rejects.toThrow('Too many redirects');
+    });
+    it('aborts a stalled body and keeps the partial for the next resume', async () => {
+        const body = new PassThrough();
+        body.write(PAYLOAD.subarray(0, 5));
+        const get = async () => response(200, body, { 'content-length': String(PAYLOAD.length) });
+        await expect(downloadToFile('https://host/model', dest, { get, stallTimeoutMs: 50 })).rejects.toThrow('stalled');
+        // The partial file is kept for the next resume (how many bytes reached disk is up to the OS).
+        expect(await fs.pathExists(dest)).toBe(true);
+        expect((await fs.stat(dest)).size).toBeLessThanOrEqual(5);
+    });
+    it('reports progress against the full size when resuming', async () => {
+        await fs.writeFile(dest, PAYLOAD.subarray(0, 10));
+        const { get } = server();
+        const seen = [];
+        await downloadToFile('https://host/model', dest, { get, onProgress: (d, t) => seen.push([d, t]) });
+        expect(seen.at(-1)).toEqual([PAYLOAD.length, PAYLOAD.length]);
+    });
+});

package/dist/inference/index.d.ts

@@ -4,8 +4,12 @@
 export type { InferenceProvider, InferenceOptions, DeepFinding, DeepAnalysisResult, ModelTier, ModelInfo } from './types.js';
 export { MODELS } from './types.js';
 export { SidecarProvider } from './sidecar-provider.js';
+export type { ActiveModel } from './sidecar-provider.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './llama-engine.js';
+export type { ProbeResult } from './llama-engine.js';
 export { CloudProvider } from './cloud-provider.js';
-export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir, getCachedModel } from './model-manager.js';
+export type { CachedModel } from './model-manager.js';
 import type { InferenceProvider } from './types.js';
 import type { DeepOptions } from '../types/index.js';
 /**

package/dist/inference/index.js

@@ -1,7 +1,8 @@
 export { MODELS } from './types.js';
 export { SidecarProvider } from './sidecar-provider.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './llama-engine.js';
 export { CloudProvider } from './cloud-provider.js';
-export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir, getCachedModel } from './model-manager.js';
 import { SidecarProvider } from './sidecar-provider.js';
 import { CloudProvider } from './cloud-provider.js';
 /**

package/dist/inference/llama-engine.d.ts

@@ -0,0 +1,27 @@
+import { type HttpGet } from './http-download.js';
+export declare const LLAMA_RELEASE_TAG = "b5604";
+export declare function llamaBinaryName(): string;
+/** Install directory for the pinned release: ~/.rigour/bin/llama-<tag>. */
+export declare function managedEngineDir(): string;
+export declare function managedEnginePath(): string;
+export declare function releaseAssetFor(platformKey: string): string | undefined;
+export interface ProbeResult {
+    ok: boolean;
+    version?: string;
+    error?: string;
+}
+/**
+ * Run `<binary> --version` and accept it only if it exits 0. A placeholder
+ * script (such as an unbundled brain package) or a binary missing its shared
+ * libraries fails here instead of on every inference call.
+ */
+export declare function probeBinary(binaryPath: string): Promise<ProbeResult>;
+/** Forget cached probe results, e.g. after installing a new engine. */
+export declare function resetProbeCache(): void;
+/**
+ * Download the pinned release for this platform and install its whole bin
+ * folder into managedEngineDir(). Returns the verified binary path.
+ */
+export declare function installLlamaEngine(onProgress?: (message: string) => void, get?: HttpGet): Promise<string>;
+/** Copy the folder that contains llama-cli (binary + shared libraries) into place. */
+export declare function installBinFolder(extractedRoot: string, installDir: string): Promise<void>;

package/dist/inference/llama-engine.js

@@ -0,0 +1,152 @@
+/**
+ * llama.cpp engine: install from the pinned GitHub release and verify that a
+ * candidate binary actually runs.
+ *
+ * The release archives link llama-cli against shared libraries next to it
+ * (@rpath → @loader_path on macOS), so the whole bin folder is installed; a
+ * lone llama-cli fails with "Library not loaded: @rpath/libllama.dylib".
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs-extra';
+import { RIGOUR_DIR } from '../storage/db.js';
+import { downloadToFile } from './http-download.js';
+import { runProcess } from './llama-process.js';
+export const LLAMA_RELEASE_TAG = 'b5604';
+const LLAMA_RELEASE_BASE = `https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_RELEASE_TAG}`;
+const PROBE_TIMEOUT_MS = 5_000;
+const EXTRACT_TIMEOUT_MS = 120_000;
+/** Platform → llama.cpp release asset. linux-arm64 has no published build. */
+const LLAMA_RELEASE_ASSETS = {
+    'darwin-arm64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-arm64.zip`,
+    'darwin-x64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-x64.zip`,
+    'linux-x64': `llama-${LLAMA_RELEASE_TAG}-bin-ubuntu-x64.zip`,
+    'win32-x64': `llama-${LLAMA_RELEASE_TAG}-bin-win-cpu-x64.zip`,
+};
+export function llamaBinaryName() {
+    return os.platform() === 'win32' ? 'llama-cli.exe' : 'llama-cli';
+}
+/** Install directory for the pinned release: ~/.rigour/bin/llama-<tag>. */
+export function managedEngineDir() {
+    return path.join(RIGOUR_DIR, 'bin', `llama-${LLAMA_RELEASE_TAG}`);
+}
+export function managedEnginePath() {
+    return path.join(managedEngineDir(), llamaBinaryName());
+}
+export function releaseAssetFor(platformKey) {
+    return LLAMA_RELEASE_ASSETS[platformKey];
+}
+const probeCache = new Map();
+/**
+ * Run `<binary> --version` and accept it only if it exits 0. A placeholder
+ * script (such as an unbundled brain package) or a binary missing its shared
+ * libraries fails here instead of on every inference call.
+ */
+export function probeBinary(binaryPath) {
+    let cached = probeCache.get(binaryPath);
+    if (!cached) {
+        cached = runProbe(binaryPath);
+        probeCache.set(binaryPath, cached);
+    }
+    return cached;
+}
+/** Forget cached probe results, e.g. after installing a new engine. */
+export function resetProbeCache() {
+    probeCache.clear();
+}
+async function runProbe(binaryPath) {
+    if (!(await fs.pathExists(binaryPath)))
+        return { ok: false, error: 'not found' };
+    try {
+        const { code, stdout, stderr } = await runProcess(binaryPath, ['--version'], { timeoutMs: PROBE_TIMEOUT_MS });
+        const output = `${stdout}\n${stderr}`;
+        if (code !== 0)
+            return { ok: false, error: lastLine(output) || `exit code ${code}` };
+        const version = output.match(/version:\s*([^\s]+)/)?.[1];
+        return { ok: true, version };
+    }
+    catch (error) {
+        return { ok: false, error: error?.message ?? String(error) };
+    }
+}
+function lastLine(text) {
+    return text.trim().split(/\r?\n/).pop()?.trim() ?? '';
+}
+/**
+ * Download the pinned release for this platform and install its whole bin
+ * folder into managedEngineDir(). Returns the verified binary path.
+ */
+export async function installLlamaEngine(onProgress, get) {
+    const platformKey = `${os.platform()}-${os.arch()}`;
+    const asset = releaseAssetFor(platformKey);
+    if (!asset) {
+        throw new Error(`No llama.cpp ${LLAMA_RELEASE_TAG} build is published for ${platformKey}. Install llama-cli on PATH or use a cloud provider.`);
+    }
+    const installDir = managedEngineDir();
+    const workDir = `${installDir}.partial`;
+    const zipPath = path.join(path.dirname(installDir), asset);
+    await fs.ensureDir(path.dirname(installDir));
+    await fs.remove(workDir);
+    onProgress?.(`⬇ Downloading inference engine (llama.cpp ${LLAMA_RELEASE_TAG})...`);
+    try {
+        await downloadToFile(`${LLAMA_RELEASE_BASE}/${asset}`, zipPath, { get });
+        onProgress?.('  Extracting...');
+        await extractZip(zipPath, workDir);
+        await installBinFolder(workDir, installDir);
+    }
+    finally {
+        await fs.remove(zipPath).catch(() => undefined);
+        await fs.remove(workDir).catch(() => undefined);
+    }
+    resetProbeCache();
+    const binary = managedEnginePath();
+    const probe = await probeBinary(binary);
+    if (!probe.ok) {
+        throw new Error(`Installed llama-cli does not run: ${probe.error}`);
+    }
+    onProgress?.(`✓ Inference engine ready (llama.cpp ${probe.version ?? LLAMA_RELEASE_TAG})`);
+    return binary;
+}
+async function extractZip(zipPath, destDir) {
+    await fs.ensureDir(destDir);
+    const result = os.platform() === 'win32'
+        ? await runProcess('powershell', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath ${psQuote(zipPath)} -DestinationPath ${psQuote(destDir)} -Force`], { timeoutMs: EXTRACT_TIMEOUT_MS })
+        : await runProcess('unzip', ['-q', '-o', zipPath, '-d', destDir], { timeoutMs: EXTRACT_TIMEOUT_MS });
+    if (result.code !== 0) {
+        throw new Error(`Could not extract ${path.basename(zipPath)}: ${lastLine(result.stderr) || `exit code ${result.code}`}`);
+    }
+}
+/** PowerShell single-quoted literal: a quote inside is escaped by doubling it. */
+function psQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Copy the folder that contains llama-cli (binary + shared libraries) into place. */
+export async function installBinFolder(extractedRoot, installDir) {
+    const binary = await findFileRecursive(extractedRoot, llamaBinaryName());
+    if (!binary)
+        throw new Error(`${llamaBinaryName()} not found in the llama.cpp release archive`);
+    await fs.remove(installDir);
+    await fs.copy(path.dirname(binary), installDir);
+    if (os.platform() !== 'win32') {
+        await fs.chmod(path.join(installDir, llamaBinaryName()), 0o755);
+    }
+}
+/** Release archives nest the binary at most a few folders deep (build/bin/). */
+const MAX_ARCHIVE_DEPTH = 6;
+async function findFileRecursive(dir, filename, depth = 0) {
+    if (depth > MAX_ARCHIVE_DEPTH)
+        return null;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const found = await findFileRecursive(fullPath, filename, depth + 1);
+            if (found)
+                return found;
+        }
+        else if (entry.name === filename) {
+            return fullPath;
+        }
+    }
+    return null;
+}

package/dist/inference/llama-engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/inference/llama-engine.test.js

@@ -0,0 +1,51 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installBinFolder, llamaBinaryName, probeBinary, resetProbeCache } from './llama-engine.js';
+const isWindows = process.platform === 'win32';
+async function writeScript(file, body) {
+    await fs.outputFile(file, `#!/bin/sh\n${body}\n`);
+    await fs.chmod(file, 0o755);
+}
+describe.skipIf(isWindows)('probeBinary', () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-engine-'));
+        resetProbeCache();
+    });
+    afterEach(async () => { await fs.remove(dir); });
+    it('accepts a binary that reports its version', async () => {
+        const bin = path.join(dir, 'llama-cli');
+        await writeScript(bin, 'echo "version: 5604 (228f34c9)" >&2; exit 0');
+        expect(await probeBinary(bin)).toEqual({ ok: true, version: '5604' });
+    });
+    it('rejects the placeholder brain script', async () => {
+        const bin = path.join(dir, 'rigour-brain');
+        await writeScript(bin, 'echo "rigour-brain is a placeholder." >&2; exit 1');
+        const result = await probeBinary(bin);
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain('placeholder');
+    });
+    it('rejects a missing binary', async () => {
+        expect((await probeBinary(path.join(dir, 'nope'))).ok).toBe(false);
+    });
+});
+describe('installBinFolder', () => {
+    let dir;
+    beforeEach(async () => { dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-engine-')); });
+    afterEach(async () => { await fs.remove(dir); });
+    it('installs the binary together with the shared libraries next to it', async () => {
+        const extracted = path.join(dir, 'extract', 'build', 'bin');
+        await fs.outputFile(path.join(extracted, llamaBinaryName()), 'bin');
+        await fs.outputFile(path.join(extracted, 'libllama.dylib'), 'lib');
+        await fs.outputFile(path.join(extracted, 'ggml-metal.metal'), 'metal');
+        const installDir = path.join(dir, 'llama-b5604');
+        await installBinFolder(path.join(dir, 'extract'), installDir);
+        expect((await fs.readdir(installDir)).sort()).toEqual(['ggml-metal.metal', 'libllama.dylib', llamaBinaryName()].sort());
+    });
+    it('fails clearly when the archive has no llama-cli', async () => {
+        await fs.outputFile(path.join(dir, 'extract', 'README.md'), 'x');
+        await expect(installBinFolder(path.join(dir, 'extract'), path.join(dir, 'out'))).rejects.toThrow('not found');
+    });
+});

package/dist/inference/llama-process.d.ts

@@ -0,0 +1,72 @@
+export interface ProcessResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface RunProcessOptions {
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class ProcessTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * Run a binary with stdin closed, collecting stdout/stderr. Rejects on spawn
+ * errors and timeouts; a non-zero exit resolves with its code.
+ */
+export declare function runProcess(command: string, args: string[], options: RunProcessOptions): Promise<ProcessResult>;
+export interface LlamaArgsInput {
+    modelPath: string;
+    prompt: string;
+    maxTokens: number;
+    threads: number;
+    temperature: number;
+    schemaPath?: string;
+}
+export declare function buildLlamaArgs(input: LlamaArgsInput): string[];
+/**
+ * Context window large enough for prompt + output, rounded up to 1024 and
+ * clamped to what Qwen2.5-Coder was trained on. The b5604 default is 4096,
+ * which silently truncates code-bearing prompts.
+ */
+export declare function contextSizeFor(prompt: string, maxTokens: number): number;
+/** Remove llama-cli's end-of-generation marker from stdout. */
+export declare function cleanLlamaOutput(stdout: string): string;
+/** JSON schema matching DeepFinding, used to constrain local generation. */
+export declare const FINDINGS_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly findings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly category: {
+                        readonly type: "string";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+                    };
+                    readonly file: {
+                        readonly type: "string";
+                    };
+                    readonly line: {
+                        readonly type: readonly ["integer", "null"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly suggestion: {
+                        readonly type: "string";
+                    };
+                    readonly confidence: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["category", "severity", "file", "description", "suggestion", "confidence"];
+            };
+        };
+    };
+    readonly required: readonly ["findings"];
+};