@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/models/install-registry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Minimal event contract shared by every chat-model installer
+ * (`LlamaCppModelManager.install`, `MlxModelManager.install`): a stream of
+ * typed events where `done` / `error` are terminal. The registry treats
+ * everything else as opaque progress it can replay to late subscribers.
+ */
+export interface ChatInstallEventBase {
+    type: string;
+    error?: string;
+}
+export interface ChatInstallSnapshot {
+    id: string;
+    startedAt: string;
+    /** Set once a terminal event has been observed (done, error, or cancel). */
+    finished: boolean;
+    /** Set when the install errored or was cancelled. */
+    error?: string;
+}
+type Listener<E> = (event: E) => void;
+/**
+ * Owns the lifecycle of in-flight chat-model installs for one engine.
+ *
+ * Installs used to be tied 1:1 to the HTTP request that started them — when
+ * the client disconnected (closed the window, navigated away mid-download),
+ * the SSE loop exited, the async install generator closed, and the download
+ * was abandoned with `.partial` files on disk and no record it ever ran.
+ * This is the chat-model twin of the image path's `ImageModelPullRegistry`,
+ * which fixed the identical failure mode for image pulls.
+ *
+ * The registry decouples the two: the install runs in a detached background
+ * task owned by this object, and HTTP requests are just consumers that
+ * subscribe to the live event fan-out. Disconnect detaches the consumer; the
+ * install keeps going. Cancel is an explicit `DELETE /models/:id/install`.
+ *
+ * Cancellation unwinds the install generator via `iterator.return()` rather
+ * than an AbortSignal — the generator only runs between yields, and the
+ * downloaders yield progress a few times a second, so the unwind lands
+ * within one progress interval and the `.partial` files stay resumable.
+ */
+export declare class ChatModelInstallRegistry<E extends ChatInstallEventBase, O> {
+    private readonly entries;
+    private readonly engine;
+    private readonly run;
+    private readonly onDone;
+    private readonly finishedTtlMs;
+    constructor(opts: {
+        /** Label used in log lines only. */
+        engine: string;
+        /** Start the actual install — typically `(id, o) => manager.install(id, o)`. */
+        run: (id: string, opts: O) => AsyncIterable<E>;
+        /** Fired when an install reaches `done`, before the event is broadcast —
+         *  the place to bust caches so subscribers observing `done` re-fetch
+         *  fresh state. */
+        onDone?: (id: string) => void;
+        /** How long a finished entry stays observable (default {@link FINISHED_TTL_MS}). */
+        finishedTtlMs?: number;
+    });
+    /**
+     * Start an install for `id`, or attach to the one already in flight.
+     * Idempotent — a second `start` for a running id does not launch a second
+     * download and does not change the original's options. The install runs in
+     * a detached `void` task; the entry is claimed synchronously so callers
+     * can subscribe without racing the first event.
+     */
+    start(id: string, opts: O): {
+        alreadyRunning: boolean;
+    };
+    get(id: string): ChatInstallSnapshot | null;
+    /** The snapshot plus the events a late subscriber would be replayed. */
+    describe(id: string): (ChatInstallSnapshot & {
+        lastEvent: E | null;
+        terminalEvent: E | null;
+    }) | null;
+    /** Every install still running, with its latest progress — the polled twin of subscribe(). */
+    active(): Array<{
+        id: string;
+        startedAt: string;
+        lastEvent: E | null;
+    }>;
+    /**
+     * Subscribe to live events for an in-flight install. On subscribe, the
+     * registry replays the last known progress event (and the terminal event,
+     * when one has landed) so a late subscriber renders immediately. Returns
+     * `null` when no entry exists for `id`; otherwise an unsubscribe function.
+     * Unsubscribing does NOT cancel the install — disconnect ≠ cancel.
+     */
+    subscribe(id: string, listener: Listener<E>): (() => void) | null;
+    /**
+     * Cancel an in-flight install. The generator unwinds at its next yield,
+     * running the manager's cleanup (active-install deregistration) and
+     * leaving `.partial` files in place for resume. Subscribers receive a
+     * terminal `error` event stating the install was cancelled. Returns true
+     * when a live entry was cancelled.
+     */
+    cancel(id: string): boolean;
+    /** Shutdown/test hook: unwind every live install and drop all state. */
+    clear(): void;
+    private consume;
+    private broadcast;
+}
+export {};

package/dist/models/install-registry.js

@@ -0,0 +1,216 @@
+import { createLogger } from '@bendyline/gezel';
+const log = createLogger('models');
+/**
+ * How long a finished install (done OR error) stays in the registry after
+ * the terminal event — long enough for a reconnecting client to observe the
+ * terminal state, short enough that the installed-models list takes over.
+ */
+const FINISHED_TTL_MS = 8_000;
+/**
+ * Owns the lifecycle of in-flight chat-model installs for one engine.
+ *
+ * Installs used to be tied 1:1 to the HTTP request that started them — when
+ * the client disconnected (closed the window, navigated away mid-download),
+ * the SSE loop exited, the async install generator closed, and the download
+ * was abandoned with `.partial` files on disk and no record it ever ran.
+ * This is the chat-model twin of the image path's `ImageModelPullRegistry`,
+ * which fixed the identical failure mode for image pulls.
+ *
+ * The registry decouples the two: the install runs in a detached background
+ * task owned by this object, and HTTP requests are just consumers that
+ * subscribe to the live event fan-out. Disconnect detaches the consumer; the
+ * install keeps going. Cancel is an explicit `DELETE /models/:id/install`.
+ *
+ * Cancellation unwinds the install generator via `iterator.return()` rather
+ * than an AbortSignal — the generator only runs between yields, and the
+ * downloaders yield progress a few times a second, so the unwind lands
+ * within one progress interval and the `.partial` files stay resumable.
+ */
+export class ChatModelInstallRegistry {
+    entries = new Map();
+    engine;
+    run;
+    onDone;
+    finishedTtlMs;
+    constructor(opts) {
+        this.engine = opts.engine;
+        this.run = opts.run;
+        this.onDone = opts.onDone;
+        this.finishedTtlMs = opts.finishedTtlMs ?? FINISHED_TTL_MS;
+    }
+    /**
+     * Start an install for `id`, or attach to the one already in flight.
+     * Idempotent — a second `start` for a running id does not launch a second
+     * download and does not change the original's options. The install runs in
+     * a detached `void` task; the entry is claimed synchronously so callers
+     * can subscribe without racing the first event.
+     */
+    start(id, opts) {
+        const existing = this.entries.get(id);
+        if (existing && !existing.snapshot.finished) {
+            return { alreadyRunning: true };
+        }
+        const entry = {
+            snapshot: { id, startedAt: new Date().toISOString(), finished: false },
+            lastEvent: null,
+            terminalEvent: null,
+            listeners: new Set(),
+            iterator: null,
+            cancelled: false,
+        };
+        this.entries.set(id, entry);
+        void this.consume(id, entry, opts);
+        return { alreadyRunning: false };
+    }
+    get(id) {
+        const entry = this.entries.get(id);
+        return entry ? { ...entry.snapshot } : null;
+    }
+    /** The snapshot plus the events a late subscriber would be replayed. */
+    describe(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return null;
+        return { ...entry.snapshot, lastEvent: entry.lastEvent, terminalEvent: entry.terminalEvent };
+    }
+    /** Every install still running, with its latest progress — the polled twin of subscribe(). */
+    active() {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (entry.snapshot.finished)
+                continue;
+            out.push({
+                id: entry.snapshot.id,
+                startedAt: entry.snapshot.startedAt,
+                lastEvent: entry.lastEvent,
+            });
+        }
+        return out;
+    }
+    /**
+     * Subscribe to live events for an in-flight install. On subscribe, the
+     * registry replays the last known progress event (and the terminal event,
+     * when one has landed) so a late subscriber renders immediately. Returns
+     * `null` when no entry exists for `id`; otherwise an unsubscribe function.
+     * Unsubscribing does NOT cancel the install — disconnect ≠ cancel.
+     */
+    subscribe(id, listener) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return null;
+        entry.listeners.add(listener);
+        if (entry.lastEvent)
+            listener(entry.lastEvent);
+        if (entry.terminalEvent)
+            listener(entry.terminalEvent);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    /**
+     * Cancel an in-flight install. The generator unwinds at its next yield,
+     * running the manager's cleanup (active-install deregistration) and
+     * leaving `.partial` files in place for resume. Subscribers receive a
+     * terminal `error` event stating the install was cancelled. Returns true
+     * when a live entry was cancelled.
+     */
+    cancel(id) {
+        const entry = this.entries.get(id);
+        if (!entry || entry.snapshot.finished || entry.cancelled)
+            return false;
+        entry.cancelled = true;
+        void entry.iterator?.return?.(undefined);
+        return true;
+    }
+    /** Shutdown/test hook: unwind every live install and drop all state. */
+    clear() {
+        for (const entry of this.entries.values()) {
+            if (!entry.snapshot.finished) {
+                entry.cancelled = true;
+                void entry.iterator?.return?.(undefined);
+            }
+        }
+        this.entries.clear();
+    }
+    async consume(id, entry, opts) {
+        let iterator = null;
+        try {
+            iterator = this.run(id, opts)[Symbol.asyncIterator]();
+            entry.iterator = iterator;
+            while (true) {
+                const { value, done } = await iterator.next();
+                if (done)
+                    break;
+                const event = value;
+                const terminal = event.type === 'done' || event.type === 'error';
+                if (terminal) {
+                    entry.terminalEvent = event;
+                    if (event.type === 'error') {
+                        entry.snapshot.error = event.error ?? 'install failed';
+                        log.warn(`[${this.engine}] install "${id}" failed: ${entry.snapshot.error}`);
+                    }
+                    else {
+                        this.onDone?.(id);
+                    }
+                }
+                else {
+                    entry.lastEvent = event;
+                }
+                this.broadcast(entry, event);
+                if (terminal)
+                    break;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.warn(`[${this.engine}] install "${id}" crashed: ${message}`);
+            const errorEvent = { type: 'error', error: message };
+            entry.terminalEvent = errorEvent;
+            entry.snapshot.error = message;
+            this.broadcast(entry, errorEvent);
+        }
+        finally {
+            entry.iterator = null;
+            // Breaking on a terminal event leaves the generator suspended at its
+            // final yield — unlike a `for await` loop, a manual next() loop does
+            // not auto-return. Unwind it explicitly so the manager's own finally
+            // (active-install deregistration) always runs.
+            try {
+                await iterator?.return?.(undefined);
+            }
+            catch {
+                // The generator's unwind path failing must not mask the install result.
+            }
+            if (!entry.terminalEvent) {
+                // The generator unwound without a terminal event — a cancel(), or
+                // an installer bug. Either way subscribers must not hang waiting
+                // for a `done` that will never come.
+                const message = entry.cancelled ? 'install cancelled' : 'install ended unexpectedly';
+                if (entry.cancelled)
+                    log.info(`[${this.engine}] install "${id}" cancelled`);
+                else
+                    log.warn(`[${this.engine}] install "${id}" ended without a terminal event`);
+                const errorEvent = { type: 'error', error: message };
+                entry.terminalEvent = errorEvent;
+                entry.snapshot.error = message;
+                this.broadcast(entry, errorEvent);
+            }
+            entry.snapshot.finished = true;
+            const timer = setTimeout(() => {
+                if (this.entries.get(id) === entry)
+                    this.entries.delete(id);
+            }, this.finishedTtlMs);
+            timer.unref?.();
+        }
+    }
+    broadcast(entry, event) {
+        for (const listener of entry.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log.warn(`[${this.engine}] install listener threw: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+}

package/dist/models/model-id.d.ts

@@ -0,0 +1,22 @@
+export declare const INVALID_MODEL_ID_CODE = "invalid-model-id";
+export declare const INVALID_MODEL_ID_MESSAGE = "model id must be a portable single-segment id (letters, numbers, @, ., _, or -)";
+/**
+ * Model ids are storage keys, never paths.
+ *
+ * Keep this model-specific alias instead of scattering entity-id checks
+ * through providers and routes. It gives every model lifecycle surface one
+ * invariant while retaining the stricter cross-platform rules from core.
+ */
+export declare function isSafeModelId(value: unknown): value is string;
+export declare class InvalidModelIdError extends TypeError {
+    readonly code = "invalid-model-id";
+    constructor();
+}
+export declare function assertSafeModelId(value: unknown): asserts value is string;
+/**
+ * Resolve a writable model directory only after proving that the caller
+ * supplied an id rather than a path. The second containment check is
+ * deliberate defense in depth for destructive provider methods that can be
+ * called without going through an HTTP route.
+ */
+export declare function resolveModelDirectory(modelsRoot: string, id: unknown): string;

package/dist/models/model-id.js

@@ -0,0 +1,40 @@
+import { isSafeEntityId } from '@bendyline/gezel';
+import { safeJoin } from '../fs/safe-paths.js';
+export const INVALID_MODEL_ID_CODE = 'invalid-model-id';
+export const INVALID_MODEL_ID_MESSAGE = 'model id must be a portable single-segment id (letters, numbers, @, ., _, or -)';
+/**
+ * Model ids are storage keys, never paths.
+ *
+ * Keep this model-specific alias instead of scattering entity-id checks
+ * through providers and routes. It gives every model lifecycle surface one
+ * invariant while retaining the stricter cross-platform rules from core.
+ */
+export function isSafeModelId(value) {
+    return isSafeEntityId(value);
+}
+export class InvalidModelIdError extends TypeError {
+    code = INVALID_MODEL_ID_CODE;
+    constructor() {
+        super(INVALID_MODEL_ID_MESSAGE);
+        this.name = 'InvalidModelIdError';
+    }
+}
+export function assertSafeModelId(value) {
+    if (!isSafeModelId(value)) {
+        throw new InvalidModelIdError();
+    }
+}
+/**
+ * Resolve a writable model directory only after proving that the caller
+ * supplied an id rather than a path. The second containment check is
+ * deliberate defense in depth for destructive provider methods that can be
+ * called without going through an HTTP route.
+ */
+export function resolveModelDirectory(modelsRoot, id) {
+    assertSafeModelId(id);
+    const target = safeJoin(modelsRoot, id);
+    if (!target) {
+        throw new InvalidModelIdError();
+    }
+    return target;
+}

package/dist/models/storage-roots.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Public machine assets are intentionally separate from the machine
+ * service's private GEZEL_HOME state. The installer/service host supplies
+ * this variable; standalone CLI launches supply the same canonical path as a
+ * read-only overlay.
+ */
+export declare const SHARED_ASSETS_ENV = "GEZEL_SHARED_ASSETS_DIR";
+/**
+ * Additional gezel HOMES whose installed models this process may read but
+ * never write. Delimiter-separated absolute paths, lowest priority in the
+ * overlay.
+ *
+ * This exists for a daemon hosted by a third-party app through
+ * `@bendyline/gezel-app-sdk/host`: it owns a private home under
+ * `~/.gezel/apps/<appId>/`, so without this it would re-download weights the
+ * user's own Gezel install already has. Unlike {@link SHARED_ASSETS_ENV},
+ * which names a purpose-built public asset store, the entries here are
+ * ordinary homes, so the per-engine `engines/<engine>/models` suffix is
+ * applied for them. Read-only payloads still have to carry
+ * `manifest.fileSha256` to be adopted, so a home whose installs predate
+ * that field is simply skipped rather than trusted.
+ */
+export declare const READONLY_MODEL_HOMES_ENV = "GEZEL_READONLY_MODEL_HOMES";
+export interface ModelStorageRoots {
+    /** The only root this process may create, replace, or delete models in. */
+    writableRoot: string;
+    /**
+     * Lower-priority, read-only roots, highest priority first. A standalone CLI
+     * uses the machine asset store here; a machine service has none because that
+     * store is its writer. An app-hosted daemon may additionally list other
+     * gezel homes through {@link READONLY_MODEL_HOMES_ENV}.
+     */
+    readOnlyRoots: string[];
+}
+export interface ModelStorageRootOptions {
+    home: string;
+    engine: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve a model store without ever treating the machine service's private
+ * home as a fallback. Local assets shadow machine assets with the same id.
+ */
+export declare function modelStorageRoots(opts: ModelStorageRootOptions): ModelStorageRoots;
+/**
+ * Parse {@link READONLY_MODEL_HOMES_ENV}. Relative entries are dropped rather
+ * than resolved against the daemon's cwd — a model root is a machine-level
+ * location, and guessing one from whichever directory happened to launch the
+ * process is how a host ends up reading someone else's files.
+ */
+export declare function readOnlyModelHomes(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Fail closed when an existing model-store component resolves through a
+ * symlink/junction or outside the configured root. On Windows, Node reports
+ * directory junctions as symbolic links and `realpath` resolves the final
+ * filesystem target, so this protects both recursive ACL work and ordinary
+ * publish/delete operations from descendant reparse redirection.
+ *
+ * Missing trailing components are allowed so callers can validate a publish
+ * target before creating it. Every existing ancestor, including `root`, is
+ * still checked.
+ */
+export declare function assertModelStorePathSafe(root: string, target: string): Promise<void>;
+/**
+ * One-shot upgrade bridge for machine services that downloaded models into
+ * the formerly-private `<home>/engines/<engine>/models` tree. Both locations are on
+ * the same machine volume in supported installers, so directory renames are
+ * atomic and avoid copying multi-gigabyte weights.
+ */
+export declare function migrateLegacySystemModels(home: string, env?: NodeJS.ProcessEnv): Promise<number>;
+/** Search order: user-owned/writable first, then machine-owned/read-only. */
+export declare function modelSearchRoots(roots: ModelStorageRoots): string[];
+/**
+ * List ids across an overlay, de-duplicating in search order so a user-owned
+ * model intentionally shadows a machine model with the same catalog id.
+ */
+export declare function listOverlayModelIds(roots: ModelStorageRoots): Promise<string[]>;
+/**
+ * Return the first overlay root containing a readable model manifest.
+ * Presence of an incomplete directory in a higher-priority root does not
+ * hide a complete machine model.
+ */
+export declare function findModelRoot(roots: ModelStorageRoots, id: string): Promise<string | null>;
+/**
+ * Resolve an id that a quant-suffix migration renamed away, by finding the
+ * install that records it as its {@link InstalledModelRenameRecord.renamedFrom}.
+ *
+ * Config pins, gezel frontmatter, eval caches, and session records all hold
+ * whatever id was current when they were written, and there is no way to
+ * find and rewrite every one of them. Keeping the former id resolvable is
+ * what makes the rename cosmetic rather than a breaking change.
+ *
+ * Only ever called on a miss, and only over directories whose name the
+ * former id prefixes — every rename target is the former id plus a suffix,
+ * so no other directory can be the answer.
+ */
+export declare function findRenamedModelId(roots: ModelStorageRoots, formerId: string): Promise<string | null>;
+export declare function modelExistsOnlyReadOnly(roots: ModelStorageRoots, id: string): Promise<boolean>;
+export declare const READ_ONLY_MODEL_CODE = "read-only-model";
+/**
+ * Refusal to mutate a model that only exists in a read-only overlay root.
+ * Typed so HTTP routes can map it to a 4xx with the actionable message
+ * instead of letting it escape as an opaque 500.
+ */
+export declare class ReadOnlyModelError extends Error {
+    readonly code = "read-only-model";
+    constructor(id: string);
+}
+export declare function readOnlyModelError(id: string): Error;
+/**
+ * Remove a model directory, tolerating the file locks that make a naive
+ * `rm` flaky on Windows. Antivirus / Search-Indexer transient holds clear in
+ * a few hundred ms, so we retry with backoff. A *persistent* lock (a running
+ * llama-server has the GGUF open) never clears on its own — we surface an
+ * actionable message rather than the raw `EBUSY`/`EPERM` so the UI can tell
+ * the user to switch models first, instead of the delete looking like a no-op.
+ */
+export declare function removeModelDir(itemDir: string, writableRoot?: string): Promise<void>;
+/**
+ * Hash every published payload file except the self-describing manifest.
+ *
+ * `precomputed` lets a caller that has *already* streamed a file through
+ * SHA-256 (the install path verifies every shard against the catalog hash
+ * before this runs) hand those digests in, keyed by the same '/'-joined
+ * relative path this returns. Matching files are taken from the cache
+ * instead of re-read — a multi-GB install would otherwise hash the whole
+ * payload from disk twice. Files on disk but absent from the cache (stale
+ * shards from a prior install, a dropped mmproj) are still enumerated and
+ * hashed, so the returned map always describes the real on-disk payload.
+ */
+export declare function hashModelPayloadFiles(modelDir: string, precomputed?: Record<string, string>): Promise<Record<string, string>>;
+/**
+ * Delete payload files in a model directory that the freshly-written install no
+ * longer references. When a model updates in place to a different quant/filename
+ * (e.g. gemma4-12b-q4 moving from `…-Q4_K_M.gguf` to `…-qat-UD-Q4_K_XL.gguf`),
+ * the rename publishes the new weights but the old file lingers — tens of GB of
+ * orphaned weights for one slot. `keep` is the set of '/'-joined relative paths
+ * the new manifest references (weights + shards + mmproj + draft). manifest.json
+ * and in-flight `.partial` files are never candidates (listModelPayloadFiles
+ * already excludes them). Returns the relative paths removed. Best-effort per
+ * file — a file we can't remove is left rather than aborting the install.
+ */
+export declare function pruneModelPayloadFiles(modelDir: string, keep: ReadonlySet<string>): Promise<string[]>;
+/**
+ * Revalidate a read-only machine model on first adoption. The user-owned
+ * cache records file identity + size + mtime; any change forces full SHA-256
+ * verification again. The cache itself never lives beside shared models.
+ */
+export declare function verifyReadOnlyModelPayload(roots: ModelStorageRoots, modelRoot: string, id: string, expected: Record<string, string> | undefined, onReject?: (reason: string) => void): Promise<boolean>;
+/**
+ * Machine daemons use a restrictive umask for private state. After a model
+ * has been fully downloaded and hash-verified, make only that published
+ * bundle traversable/readable by ordinary users.
+ *
+ * Windows needs an explicit inheritance reset. A model imported through the
+ * private transaction area, or moved from the legacy private model store,
+ * keeps its old DACL when it is renamed within the ProgramData volume. Merely
+ * placing that directory below the public `assets` container therefore does
+ * not make it readable. Resetting the published tree makes it inherit the
+ * installer's read-only BUILTIN\Users ACE without granting users write access.
+ */
+export declare function makeSharedModelReadable(modelDir: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export interface ReclaimedDownload {
+    id: string;
+    bytes: number;
+}
+/** Grace period before an abandoned download is reclaimed. Within it the
+ *  `.partial` files still serve as resume credit for a retried install. */
+export declare const ABANDONED_DOWNLOAD_TTL_MS: number;
+/**
+ * Delete abandoned model downloads from the writable root.
+ *
+ * A directory qualifies only when ALL of these hold — the gates are meant to
+ * make "we delete something the user wanted" impossible:
+ *   - no `manifest.json` (never completed an install, invisible to every
+ *     listing surface),
+ *   - contains at least one `.partial` file (the downloader's signature —
+ *     a hand-placed model directory without one is never touched),
+ *   - nothing in it was written for `ttlMs` (default 7 days — within that
+ *     window the `.partial` files are resume credit for a retried install),
+ *   - not currently being installed (`activeIds`).
+ *
+ * Only the writable root is swept — read-only machine roots belong to the
+ * machine service, which runs its own sweep. Callers run this once at boot;
+ * errors are contained per-directory so one unreadable entry can't stop the
+ * sweep.
+ */
+export declare function reclaimAbandonedModelDownloads(opts: {
+    writableRoot: string;
+    activeIds?: ReadonlySet<string>;
+    ttlMs?: number;
+    now?: number;
+}): Promise<ReclaimedDownload[]>;
+export interface IncompleteModelDownload {
+    id: string;
+    /** Total bytes on disk across the directory (payload + `.partial`). */
+    bytes: number;
+    /** ISO timestamp of the newest write in the directory. */
+    updatedAt: string;
+    /** Whether a `.partial` is present (a resumable in-flight download vs
+     *  stray files left without one). */
+    hasPartial: boolean;
+}
+/**
+ * Cheap metadata-only profile of one model directory. Unlike
+ * {@link hashModelPayloadFiles}, this never reads payload contents — it only
+ * walks regular files and sums their stat sizes. Inventory surfaces use it to
+ * keep malformed/legacy installs visible without hashing a hundred-gigabyte
+ * model merely to say that the files exist.
+ */
+export interface ModelDirectoryProfile {
+    /** Total bytes on disk across payload, metadata, and partial files. */
+    bytes: number;
+    /** ISO timestamp of the newest directory/file write. */
+    updatedAt: string;
+    /** Whether any resumable download fragment is present. */
+    hasPartial: boolean;
+    /** Whether the directory tree contains model metadata. */
+    hasManifest: boolean;
+}
+/** Inventory row for a model directory whose manifest exists but is not
+ * loadable by the current engine manager. */
+export interface UnrecognizedModelInfo {
+    id: string;
+    name?: string;
+    bytes: number;
+    updatedAt: string;
+    reason: string;
+    canUpdate: boolean;
+    readOnly?: boolean;
+}
+export declare function inspectModelDirectory(dir: string): Promise<ModelDirectoryProfile | null>;
+/**
+ * An incomplete download enriched with per-engine catalog context. Managers
+ * return this from `listIncomplete()`; the route serializes it as-is.
+ */
+export interface IncompleteModelDownloadInfo extends IncompleteModelDownload {
+    /**
+     * True when this id still resolves to a catalog entry the owning engine can
+     * source — a re-install resumes from the on-disk `.partial` files rather
+     * than starting over. False for stale/removed ids, where delete is the only
+     * sensible action.
+     */
+    resumable: boolean;
+    /** Display name from the catalog, when the id still resolves. */
+    name?: string;
+}
+/**
+ * List incomplete model downloads in the writable root — directories with no
+ * `manifest.json` (so they're invisible to `listInstalled` and every other
+ * listing surface) that nonetheless hold bytes. These are interrupted or
+ * unverified downloads: they can hold tens of GB yet the user has no way to
+ * see or manage them until the 7-day {@link reclaimAbandonedModelDownloads}
+ * sweep silently removes them. Surfacing them lets the UI offer resume/delete
+ * immediately. Currently-installing ids are excluded (they show as live
+ * progress elsewhere). Sorted largest-first — the most disk to reclaim.
+ */
+export declare function listIncompleteModelDownloads(opts: {
+    writableRoot: string;
+    activeIds?: ReadonlySet<string>;
+}): Promise<IncompleteModelDownload[]>;
+/**
+ * Read buffer for hashing multi-GB model files off disk. The default
+ * `createReadStream` highWaterMark is 64 KB, which for a 7 GB file means
+ * ~110k `'data'` events — one event-loop turn each. Inside the daemon's busy
+ * event loop (chat, scheduler, index scans) those turns queue behind other
+ * work and the hash starves: a file that hashes in ~9s idle took 15+ minutes
+ * in the running service. A 16 MB buffer cuts it to ~400 turns, so a
+ * congested loop barely affects wall time (measured: a 6.3 GB file that
+ * hashed in ~9s idle did not finish in 2 min at 64 KB under a busy loop, but
+ * stayed ~10s at 16 MB). Hash correctness with this buffer is covered by the
+ * hashModelPayloadFiles tests in storage-roots.test.ts.
+ */
+export declare const MODEL_HASH_READ_BUFFER_BYTES: number;