@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/llama-cpp/log.js

@@ -0,0 +1,280 @@
+import { appendFileSync, createWriteStream, mkdirSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { redactCredentials } from '@bendyline/gezel';
+const LLAMA_PROMPT_PROGRESS = /\bslot print_timing:.*?\btask\s*(\d+)\s*\|.*?\bprompt processing(?:\s+progress)?\b.*?\bn_tokens\s*=\s*(\d+).*?\bprogress\s*=\s*([\d.]+)/;
+/**
+ * Suppress a native llama.cpp busy-loop without hiding real progress.
+ *
+ * Some engine builds can emit the same prompt-progress state tens of
+ * thousands of times per second (the uptime prefix changes, but task, token
+ * count, and progress do not). Logging every repaint can fill gigabytes in a
+ * few minutes. Distinct progress states still pass immediately; a stuck state
+ * is sampled periodically and gets an explicit suppression summary.
+ */
+export class LlamaProgressLogThrottle {
+    intervalMs;
+    now;
+    lastSignature = null;
+    lastEmittedAt = 0;
+    suppressed = 0;
+    constructor(intervalMs = 5_000, now = Date.now) {
+        this.intervalMs = intervalMs;
+        this.now = now;
+    }
+    accept(line) {
+        const match = line.match(LLAMA_PROMPT_PROGRESS);
+        if (!match) {
+            const summary = this.takeSummary();
+            this.lastSignature = null;
+            return summary ? [summary, line] : [line];
+        }
+        const signature = `${match[1]}:${match[2]}:${match[3]}`;
+        const now = this.now();
+        if (signature !== this.lastSignature) {
+            const summary = this.takeSummary();
+            this.lastSignature = signature;
+            this.lastEmittedAt = now;
+            return summary ? [summary, line] : [line];
+        }
+        if (now - this.lastEmittedAt < this.intervalMs) {
+            this.suppressed += 1;
+            return [];
+        }
+        const summary = this.takeSummary();
+        this.lastEmittedAt = now;
+        return summary ? [summary, line] : [line];
+    }
+    takeSummary() {
+        if (this.suppressed === 0)
+            return null;
+        const count = this.suppressed;
+        this.suppressed = 0;
+        return `[llama-server] suppressed ${count} duplicate prompt-progress log lines with no token/progress change`;
+    }
+}
+/**
+ * Rolling append-only log for llama-server stdout/stderr. Mirrors the
+ * per-day pattern in packages/app/src/supervisor/log-rotator.ts but
+ * lives inside the service package so the Electron → service
+ * dependency direction stays one-way.
+ *
+ * Files live at `<dir>/llama-server-YYYY-MM-DD.log`, roll to
+ * `-1.log` / `-2.log` when the active file crosses 10 MB, and ones
+ * older than 7 days are swept on open.
+ *
+ * Design note: we duplicate (rather than factor-out) the small
+ * rotator because the alternative is a shared package. Two files of
+ * trivial rotation logic is cheaper than a new package boundary for
+ * the size of this codebase.
+ */
+export class LlamaCppLogFile {
+    dir;
+    baseName;
+    stream = null;
+    currentPath = null;
+    currentDay = null;
+    rollIndex = 0;
+    bytesWritten = 0;
+    maxBytes = 10 * 1024 * 1024;
+    retentionDays = 7;
+    readyPromise;
+    pendingWrites = Promise.resolve();
+    constructor(dir, baseName = 'llama-server') {
+        this.dir = dir;
+        this.baseName = baseName;
+        this.readyPromise = this.init();
+    }
+    async init() {
+        await mkdir(this.dir, { recursive: true });
+        await this.sweepOldFiles();
+        await this.openForToday();
+    }
+    today() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    async openForToday() {
+        this.currentDay = this.today();
+        this.rollIndex = 0;
+        const base = join(this.dir, `${this.baseName}-${this.currentDay}.log`);
+        let existingSize = 0;
+        try {
+            const st = await stat(base);
+            existingSize = st.size;
+        }
+        catch {
+            /* not present yet */
+        }
+        this.currentPath = base;
+        this.bytesWritten = existingSize;
+        this.stream = createWriteStream(base, { flags: 'a' });
+    }
+    async rollIfNeeded() {
+        if (this.today() !== this.currentDay) {
+            // We are already running inside `pendingWrites`; calling the public
+            // close() here would wait for that same promise chain and deadlock.
+            await this.closeStream();
+            await this.openForToday();
+            return;
+        }
+        if (this.bytesWritten < this.maxBytes)
+            return;
+        await this.closeStream();
+        this.rollIndex += 1;
+        const rolled = join(this.dir, `${this.baseName}-${this.currentDay}-${this.rollIndex}.log`);
+        this.currentPath = rolled;
+        this.bytesWritten = 0;
+        this.stream = createWriteStream(rolled, { flags: 'a' });
+    }
+    /**
+     * Fire-and-forget append. Serializes writes via an internal promise
+     * chain so rotation + ordering stay correct even under bursty
+     * stdout. The caller doesn't need to await individual lines; any
+     * subsequent `tail()` / `close()` awaits the drain.
+     */
+    write(line) {
+        // Credential-shape scrub before hitting disk. See core's
+        // `redact.ts` for the patterns + rationale. Defense in depth — llama-server
+        // doesn't emit secrets by design, but a log file is the kind of
+        // thing users share on bug reports, and being wrong-by-omission
+        // here costs more than over-redacting.
+        const safe = redactCredentials(line);
+        const run = async () => {
+            await this.readyPromise;
+            await this.rollIfNeeded();
+            if (!this.stream)
+                return;
+            const buf = Buffer.from(safe.endsWith('\n') ? safe : `${safe}\n`, 'utf8');
+            await new Promise((resolve) => {
+                this.stream?.write(buf, () => resolve());
+            });
+            this.bytesWritten += buf.length;
+        };
+        this.pendingWrites = this.pendingWrites.then(run, run);
+    }
+    /**
+     * Persist an unexpected native exit before the provider releases the
+     * correlated request error. This synchronous, single-line write closes the
+     * race where an eval snapshots its isolated home immediately after a crash.
+     * The potentially user-derived stdout/stderr tail deliberately stays only in
+     * memory; the panic classifier contributes at most one redacted error line.
+     */
+    writeIncident(snapshot) {
+        const { outputTail: _outputTail, ...incident } = snapshot;
+        void _outputTail;
+        if (incident.panicLine)
+            incident.panicLine = redactCredentials(incident.panicLine);
+        mkdirSync(this.dir, { recursive: true });
+        appendFileSync(join(this.dir, 'native-incidents.jsonl'), `${JSON.stringify(incident)}\n`, 'utf8');
+    }
+    /** Wait for all in-flight writes to flush, then return. */
+    async flush() {
+        // Initialization is intentionally asynchronous so constructing the logger
+        // never blocks provider setup. With no queued `write()` call, however,
+        // pendingWrites alone does not observe it.
+        await this.readyPromise;
+        await this.pendingWrites;
+    }
+    async close() {
+        // Incident-only lifecycles may close before any ordinary log line is
+        // queued. Wait for init so it cannot open a fresh stream after close has
+        // returned and raced the caller's directory cleanup.
+        await this.flush();
+        await this.closeStream();
+    }
+    async closeStream() {
+        if (!this.stream)
+            return;
+        const s = this.stream;
+        this.stream = null;
+        await new Promise((resolve) => s.end(() => resolve()));
+    }
+    /**
+     * Read the last `bytes` chars of the current file. Used by the
+     * Settings → On-device → Engine log disclosure. Returns an empty
+     * string if the file doesn't exist yet (first launch, nothing
+     * logged).
+     */
+    async tail(bytes) {
+        await this.readyPromise;
+        await this.flush();
+        if (!this.currentPath)
+            return '';
+        try {
+            const content = await readFile(this.currentPath, 'utf8');
+            return content.length <= bytes ? content : content.slice(content.length - bytes);
+        }
+        catch {
+            return '';
+        }
+    }
+    /** Absolute path of the current log file (for surfacing in UI). */
+    currentFile() {
+        return this.currentPath;
+    }
+    async sweepOldFiles() {
+        const horizonMs = Date.now() - this.retentionDays * 24 * 60 * 60 * 1000;
+        let entries;
+        try {
+            entries = await readdir(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (!name.startsWith(`${this.baseName}-`) || !name.endsWith('.log'))
+                continue;
+            const p = join(this.dir, name);
+            try {
+                const st = await stat(p);
+                if (st.mtimeMs < horizonMs) {
+                    await unlink(p);
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+/**
+ * Read the newest retained engine log without constructing a writer. This is
+ * used by diagnostics after the provider has been evicted or the app was
+ * force-quit — exactly when an in-memory provider handle is unavailable but
+ * the last native stdout/stderr is most useful.
+ */
+export async function tailLatestEngineLog(dir, baseName, bytes) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { path: null, tail: '' };
+    }
+    const candidates = await Promise.all(names
+        .filter((name) => name.startsWith(`${baseName}-`) && name.endsWith('.log'))
+        .map(async (name) => {
+        const path = join(dir, name);
+        try {
+            return { path, mtimeMs: (await stat(path)).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    }));
+    const latest = candidates
+        .filter((entry) => entry !== null)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)[0];
+    if (!latest)
+        return { path: null, tail: '' };
+    try {
+        const content = await readFile(latest.path, 'utf8');
+        return {
+            path: latest.path,
+            tail: content.length <= bytes ? content : content.slice(content.length - bytes),
+        };
+    }
+    catch {
+        return { path: latest.path, tail: '' };
+    }
+}

package/dist/providers/llama-cpp/models.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Local llama.cpp model storage + install pipeline.
+ *
+ * Storage layout:
+ *
+ *   <home>/engines/llama-cpp/
+ *   └── models/
+ *       └── <model-id>/
+ *           ├── manifest.json   (snapshot of catalog metadata + install info)
+ *           └── <weights>.gguf  (the actual weights, original filename preserved)
+ *
+ * Install flow:
+ *   1. Look up the chat-model entry in the catalog.
+ *   2. Stream the GGUF from
+ *      `huggingface.co/<repo>/resolve/<revision>/<filename>` (the pinned
+ *      commit SHA, or `main` for legacy manifests) to a `.partial`
+ *      file, hashing as we go.
+ *   3. Verify the computed sha256 against the manifest's expected value.
+ *   4. Run the GGUF header parser to extract context window + chat-template
+ *      presence. Surface a non-fatal warning when `tokenizer.chat_template`
+ *      is missing — llama-server otherwise silently uses the wrong
+ *      template (the gemma4 footgun the Phase-0 spike caught).
+ *   5. Atomically rename `.partial` → final filename and write
+ *      `manifest.json`.
+ *
+ * Delete flow:
+ *   - Remove the per-model directory in one shot.
+ *
+ * Resolve-current flow:
+ *   - Pick the first installed model (alphabetical) when ChatManager
+ *     wants a default model path. Phase 2 keeps "current" implicit; a
+ *     proper picker lives in the UI.
+ */
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import { type ModelBundleSource } from '../../models/bundle-storage.js';
+import { type ModelUpdateStatus } from '../../models/catalog-drift.js';
+import { type IncompleteModelDownloadInfo, type UnrecognizedModelInfo } from '../../models/storage-roots.js';
+export type { IncompleteModelDownloadInfo } from '../../models/storage-roots.js';
+export interface InstalledLlamaCppModel {
+    id: string;
+    name: string;
+    approxSizeBytes: number;
+    installedAt: string;
+    /** Absolute path to the weights file the supervisor passes to `llama-server --model`. */
+    weightsPath: string;
+    /**
+     * Absolute path to the multimodal projector file, when the catalog
+     * entry shipped an mmproj sidecar. The supervisor appends
+     * `--mmproj <path>` when set — that's what enables image / audio /
+     * video inputs on llama-server. Absent → text-only model.
+     */
+    mmprojPath?: string;
+    /**
+     * On-disk size of {@link mmprojPath}, read from the file rather than the
+     * manifest. `approxSizeBytes` does NOT include the projector — the value
+     * recorded at install time is the weights alone whenever the payload was
+     * adopted or resumed rather than freshly downloaded — so every memory
+     * estimate has to add this explicitly or it under-reserves a vision model
+     * by the projector plus its compute buffers (1.7 GB on muse-glimmer).
+     */
+    mmprojSizeBytes?: number;
+    /**
+     * Absolute path to ds4's model-matched vision encoder, when the catalog
+     * source declares one. The DwarfStar launcher forwards it as
+     * `--vision <path>`; it is intentionally distinct from llama.cpp's mmproj.
+     */
+    visionEncoderPath?: string;
+    /** On-disk size of {@link visionEncoderPath}, used by launch admission. */
+    visionEncoderSizeBytes?: number;
+    /**
+     * Absolute path to a speculative-decoding companion GGUF, when the
+     * catalog ships one. The launcher forwards it as
+     * `--spec-draft-model <path>` for the selected draft algorithm.
+     */
+    draftModelPath?: string;
+    /** From the GGUF metadata — useful for the supervisor's `-c` flag (Phase 3). */
+    contextWindow?: number;
+    /** Quantization tag (Q4_K_M / Q8_0 / …) lifted from the catalog source block. */
+    quantization?: string;
+    /**
+     * What the GGUF header itself declares (`general.file_type`), when the
+     * catalog's tag names no bit depth. The catalog string is hand-authored
+     * content and can be anything — `muse-glimmer-30b-q4` shipped
+     * `K-Quant-17GB` — so the model table falls back to this rather than
+     * printing a filename fragment in a column of `~4` / `~8`.
+     */
+    ggufQuantization?: string;
+    /** Empty when `tokenizer.chat_template` is missing — surfaced in the UI as a warning. */
+    chatTemplatePresent: boolean;
+    /** Complete payload hashes used when adopting a read-only machine model. */
+    fileSha256?: Record<string, string>;
+    /**
+     * The architecture string from the GGUF metadata (qwen2 / llama / gemma3 / …).
+     * Lets the UI surface a hint when a model claims a family llama.cpp doesn't
+     * recognize natively.
+     */
+    architecture?: string;
+    /**
+     * Catalog version this model was DOWNLOADED against (snapshotted into the
+     * local install manifest). Compared to the catalog's current version to
+     * detect drift — stale weights running under newer catalog settings
+     * (tuning/behaviors), the failure mode that shipped garbled gemma4-12b
+     * output.
+     */
+    catalogVersion?: string;
+    /** sha256 of the weights recorded at install (first shard for sharded installs). */
+    sha256?: string;
+    /**
+     * True when this model resolves from a read-only overlay (the machine/shared
+     * asset store) rather than this daemon's writable root. `delete` refuses
+     * these, so the UI shows them as machine-provided instead of offering a
+     * Delete action that can only fail.
+     */
+    readOnly?: boolean;
+    /**
+     * True when the catalog now describes a different PAYLOAD than the one on
+     * disk — a newer build whose bytes this copy does not have. Lets the model
+     * manager offer "Update" (fetch what differs, replace in place) instead of
+     * forcing the user to delete and re-fetch. A catalog version bump that
+     * leaves the files alone (retuning, sizing hints, wording) deliberately
+     * does not set this: the runtime resolves that metadata live, so there is
+     * nothing for the user to download. Computed in
+     * {@link LlamaCppModelManager.listInstalled} against the live catalog.
+     */
+    updateAvailable?: boolean;
+    /** The catalog's current version, when it differs from the installed one. */
+    availableVersion?: string;
+    /** What changed, in one sentence, for the model manager's tooltip. */
+    updateReason?: string;
+}
+export type InstallEvent = {
+    type: 'progress';
+    bytesWritten: number;
+    totalBytes: number;
+}
+/**
+ * Surfaced when the shared `downloadWithRetry` helper hit a transient
+ * network error and is about to try again. The UI renders
+ * "Connection dropped — retrying in 4s (attempt 3/5)…" instead of a
+ * fatal error banner. `reason` is already a user-friendly sentence.
+ */
+ | {
+    type: 'retrying';
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+} | {
+    type: 'verifying';
+} | {
+    type: 'extracting-metadata';
+}
+/**
+ * A second model being pulled alongside the requested one — today only the
+ * image reader, fetched automatically when the chat model can't see images.
+ *
+ * Its own event arm rather than folding the bytes into `progress`, because
+ * the user is entitled to know a further 3 GB is being downloaded and what
+ * for. `done` is withheld until this finishes, so the UI's terminal handler
+ * doesn't close the stream halfway through.
+ */
+ | {
+    type: 'companion';
+    kind: 'image-recognition';
+    id: string;
+    name: string;
+    bytesWritten: number;
+    totalBytes: number;
+    /** Set when the companion pull failed. The primary install still stands. */
+    error?: string;
+}
+/** Final success event. `warning` is set when the GGUF lacks a chat_template. */
+ | {
+    type: 'done';
+    id: string;
+    warning?: string;
+}
+/**
+ * Terminal failure. When the failure is a sha256 mismatch against the
+ * catalog's pinned hashes, `mismatch` carries the offending file +
+ * expected/actual so the UI can offer a "Hugging Face version changed —
+ * download anyway?" prompt instead of a raw error. The user's "anyway"
+ * retry passes `?skipSha=1` and bypasses verification for that one
+ * install.
+ */
+ | {
+    type: 'error';
+    error: string;
+    mismatch?: {
+        file: string;
+        expected: string;
+        actual: string;
+    };
+};
+/**
+ * Snapshot of an in-flight install. Two different code paths drive
+ * the same `install()` generator — the user clicking "Install" in
+ * Settings (consumes events via the SSE route), and the first-run
+ * bootstrap that fires the install in the background. The Home
+ * banner can see what's happening in the bootstrap path, but the
+ * Settings catalog view (where the user looks for download
+ * progress) wouldn't, until we exposed a polled "what's currently
+ * being installed" snapshot. {@link LlamaCppModelManager.getActiveInstalls}
+ * is that snapshot.
+ */
+export interface ActiveInstallSnapshot {
+    catalogId: string;
+    bytesWritten: number;
+    totalBytes: number;
+    phase: 'downloading' | 'verifying' | 'extracting-metadata';
+    startedAt: string;
+}
+export interface LlamaCppModelManagerOptions {
+    /** GEZEL_HOME — used to compute the models root. */
+    home: string;
+    catalog: CatalogService;
+    /** Test seam — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Which engine's GGUFs this manager installs. ds4 (DwarfStar) GGUFs are
+     * structurally identical to llama.cpp's (HF repo + revision + filename/shards
+     * + sha256), so ds4 reuses this exact downloader — only the on-disk dir
+     * (`engines/<engine>/models`) and the catalog source block read (`ds4` vs
+     * `llamaCpp`) differ. Defaults to `'llama-cpp'`.
+     */
+    engine?: 'llama-cpp' | 'ds4';
+    /**
+     * Fired once per successful install, just before the `done` event
+     * yields. Every install flow (Settings SSE route, first-run
+     * bootstrap, /v1 ensure, limbo recovery) funnels through `install()`,
+     * so this is the single post-install chokepoint — the fitness
+     * manager hangs its automatic probe here. Fire-and-forget: a
+     * throwing callback never breaks the install.
+     */
+    onInstalled?: (info: {
+        engine: 'llama-cpp' | 'ds4';
+        id: string;
+    }) => void;
+}
+export declare class LlamaCppModelManager {
+    private readonly modelsRoot;
+    private readonly storageRoots;
+    private readonly catalog;
+    private readonly fetchImpl;
+    private readonly engine;
+    private readonly onInstalled?;
+    /**
+     * In-flight installs. `install()` registers an entry on first yield
+     * and clears it in the iterator's `finally` block, so consumers
+     * (HTTP `/active-installs`, polling React UI) always see the live
+     * subset regardless of which code path drove the install.
+     */
+    private readonly activeInstalls;
+    /**
+     * Model directories we've already warned about skipping. `listInstalled`
+     * runs on every picker/settings poll; a broken directory should be loud
+     * exactly once per process, not once per poll.
+     */
+    private readonly skipWarned;
+    constructor(opts: LlamaCppModelManagerOptions);
+    /**
+     * The catalog source block this manager downloads from — `ds4` for the
+     * DwarfStar engine, `llamaCpp` otherwise. Cast to the llama.cpp source
+     * shape. The common downloader accepts the union directly so engine-specific
+     * sidecars (`mmproj` versus `visionEncoder`) keep their honest catalog names.
+     */
+    private srcBlock;
+    /**
+     * Snapshot of installs currently running. Used by the Settings UI to
+     * mirror background bootstrap installs into its progress view — the
+     * first-run download fires server-side via direct method call (not
+     * the HTTP install route), so the React component has no live SSE
+     * stream to consume; polling this surface fills the gap.
+     */
+    getActiveInstalls(): ActiveInstallSnapshot[];
+    /**
+     * List installed models in alphabetical order. Tolerates malformed or
+     * partial directories — they're skipped, not surfaced as errors.
+     */
+    listInstalled(): Promise<InstalledLlamaCppModel[]>;
+    /**
+     * List incomplete downloads for this engine — interrupted or unverified
+     * downloads that hold bytes on disk but have no `manifest.json`, so they
+     * never appear in {@link listInstalled}. Each is tagged `resumable` when
+     * its id still resolves to a catalog entry this engine can source, so the
+     * UI can offer resume (re-install picks up from the `.partial`) vs
+     * delete-only for stale ids. In-flight installs are excluded.
+     */
+    listIncomplete(): Promise<IncompleteModelDownloadInfo[]>;
+    /**
+     * Model directories that do have a manifest, but whose metadata cannot be
+     * loaded by this build. These used to disappear from every inventory
+     * surface: `listInstalled()` correctly refused to run them, while the
+     * incomplete-download scan correctly ignored anything with a manifest.
+     * Keep that safety boundary, but return a management-only row so Settings
+     * can update a known catalog id or explicitly remove the held bytes.
+     */
+    listUnrecognized(): Promise<UnrecognizedModelInfo[]>;
+    /**
+     * Path of the first installed model, or null when none exist. Phase 2
+     * uses this to pick a default `--model` arg for the supervised
+     * llama-server when the user hasn't explicitly chosen one. A "default
+     * model" UI lives in Phase 3.
+     */
+    resolveDefaultModelPath(): Promise<string | null>;
+    /**
+     * Summary of the first installed model (or null). Same fall-through
+     * rule as {@link resolveDefaultModelPath}; returns the full summary
+     * so callers like `buildLlamaCppProvider` can pick up the manifest's
+     * `contextWindow` along with the path.
+     */
+    resolveDefaultModel(): Promise<InstalledLlamaCppModel | null>;
+    /**
+     * Path of a specific installed model, or null when not installed.
+     * Used by ChatManager when the user has picked a model explicitly.
+     */
+    resolveModelPath(id: string): Promise<string | null>;
+    /**
+     * Full summary for a specific installed model, or null when not
+     * installed. Used when the user has pinned a default model via
+     * `config.defaultModel['llama-cpp']` — `buildLlamaCppProvider`
+     * needs the `contextWindow` to set `--ctx-size` correctly.
+     */
+    resolveModel(id: string): Promise<InstalledLlamaCppModel | null>;
+    /**
+     * Whether a genuinely newer build of one installed model exists. Null when
+     * the id isn't installed for this engine. Shared with the chat manager's
+     * per-session staleness notice so a user is never told to re-download for a
+     * change that only touched metadata.
+     */
+    getUpdateStatus(id: string): Promise<ModelUpdateStatus | null>;
+    /**
+     * Compare one installed copy against the live catalog. The catalog lookup
+     * runs for every model on every inventory poll; the manifest re-read only
+     * happens for the few whose version actually moved.
+     */
+    private evaluateDrift;
+    delete(id: string): Promise<void>;
+    /** Provider-owned snapshot used by the streaming `.gezmodel` exporter. */
+    getModelBundleSource(id: string): Promise<ModelBundleSource>;
+    /**
+     * Validate provider-specific invariants, write the local install manifest,
+     * and atomically publish a security-scanned staged bundle.
+     */
+    importModelBundle(opts: {
+        id: string;
+        stagedModelDir: string;
+        installedManifest: Record<string, unknown>;
+        replace: boolean;
+    }): Promise<void>;
+    /**
+     * Install a model from the catalog. Yields progress / verifying /
+     * extracting-metadata / done events. Yields exactly one terminal
+     * event (`done` or `error`) and is safe to consume to completion.
+     *
+     * Existing weights at the target id are atomically replaced — the
+     * download writes to a `.partial` sibling and renames into place
+     * only after sha256 verification passes. Failed installs leave the
+     * previous weights untouched.
+     */
+    install(catalogId: string, options?: {
+        skipSha?: boolean;
+        includeMmproj?: boolean;
+    }): AsyncIterable<InstallEvent>;
+    /**
+     * Inner install loop. Splitting it out lets {@link install} wrap the
+     * generator in a `try/finally` that clears the active-install
+     * registration on every exit path, including caller break/throw —
+     * the equivalent inline construction would require interleaving the
+     * cleanup with each early `return` and silently rot.
+     */
+    private runInstall;
+    /**
+     * Files the plan asks for that are already on disk as exactly the bytes the
+     * catalog pins, keyed by filename with the digest to carry forward.
+     *
+     * An update usually rotates one thing — a quant, one shard, an added draft
+     * companion — and re-fetching the rest is pure waste. The install manifest
+     * records a sha256 for every file it published, each verified against the
+     * catalog when it landed; where that digest equals the pin we are about to
+     * download and the file is still its full length, the bytes on disk ARE the
+     * bytes we would fetch. Same trust model as the shared-store adoption cache:
+     * a recorded digest plus an unchanged stat is identity.
+     */
+    private planReusableFiles;
+    /** Warn once per model directory per process, then stay quiet. */
+    private warnSkip;
+    private loadInstalled;
+}