@bendyline/gezel-inference 1.0.3 → 1.0.5

package/dist/providers/image/mock.js

@@ -0,0 +1,151 @@
+/**
+ * MockImageProvider — deterministic image generation for tests and for the
+ * `GEZEL_MOCK_PROVIDER=1` flow. Produces a tiny, valid PNG whose pixel
+ * colour is derived from a hash of the prompt so different prompts yield
+ * visually different (but still trivially small) outputs.
+ */
+import { deflateSync } from 'node:zlib';
+export class MockImageProvider {
+    name = 'mock';
+    installed = new Map();
+    /** Internal counter driving deterministic seed generation on "random" seeds. */
+    nextSeed = 1;
+    constructor(opts = {}) {
+        for (const m of opts.preinstalled ?? []) {
+            this.installed.set(m.id, m);
+        }
+    }
+    /** Number of input images received on the most recent generate(). Tests use this. */
+    lastInputImageCount = 0;
+    async generate(input) {
+        this.lastInputImageCount = input.inputImages?.length ?? 0;
+        const width = clamp(input.width ?? 16, 1, 512);
+        const height = clamp(input.height ?? 16, 1, 512);
+        const steps = clamp(input.steps ?? 1, 1, 100);
+        const seed = input.seed ?? this.nextSeed++;
+        const model = input.model ?? [...this.installed.keys()][0] ?? 'mock-model';
+        const rgba = solidFill(width, height, colourForPrompt(input.prompt));
+        const png = encodePng(rgba, width, height);
+        return {
+            png,
+            meta: {
+                model,
+                seed,
+                steps,
+                widthPx: width,
+                heightPx: height,
+                durationMs: 1,
+            },
+        };
+    }
+    async listInstalledModels() {
+        return [...this.installed.values()];
+    }
+    async *pullModel(id, spec, signal) {
+        const total = spec.approxSizeBytes;
+        for (const step of [0.25, 0.5, 0.75, 1]) {
+            if (signal?.aborted) {
+                yield { type: 'error', error: 'download aborted' };
+                yield { type: 'done', id };
+                return;
+            }
+            // Tiny tick so tests can observe a mid-pull state between steps.
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, 5);
+                t.unref?.();
+            });
+            yield { type: 'progress', bytesWritten: Math.round(total * step), totalBytes: total };
+        }
+        this.installed.set(id, {
+            id,
+            name: spec.name,
+            approxSizeBytes: total,
+            installedAt: new Date().toISOString(),
+        });
+        yield { type: 'done', id };
+    }
+    async deleteModel(id) {
+        this.installed.delete(id);
+    }
+    async health() {
+        return { status: 'ok', baseUrl: 'mock://image' };
+    }
+}
+function clamp(n, min, max) {
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+/** Hash the prompt to an `[r, g, b]` tuple so different prompts paint different pixels. */
+function colourForPrompt(prompt) {
+    let h = 2166136261;
+    for (let i = 0; i < prompt.length; i++) {
+        h ^= prompt.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return [h & 0xff, (h >>> 8) & 0xff, (h >>> 16) & 0xff];
+}
+function solidFill(width, height, rgb) {
+    const rgba = new Uint8Array(width * height * 4);
+    for (let i = 0; i < width * height; i++) {
+        rgba[i * 4] = rgb[0];
+        rgba[i * 4 + 1] = rgb[1];
+        rgba[i * 4 + 2] = rgb[2];
+        rgba[i * 4 + 3] = 0xff;
+    }
+    return rgba;
+}
+// ── Minimal PNG encoder (RGBA, no filter) ──────────────────────────
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const typeBytes = Buffer.from(type, 'ascii');
+    const buf = Buffer.alloc(8 + data.length + 4);
+    buf.writeUInt32BE(data.length, 0);
+    typeBytes.copy(buf, 4);
+    Buffer.from(data).copy(buf, 8);
+    const crcInput = new Uint8Array(typeBytes.length + data.length);
+    crcInput.set(typeBytes, 0);
+    crcInput.set(data, typeBytes.length);
+    buf.writeUInt32BE(crc32(crcInput), 8 + data.length);
+    return buf;
+}
+function encodePng(rgba, width, height) {
+    const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    const raw = new Uint8Array(height * (1 + width * 4));
+    for (let y = 0; y < height; y++) {
+        raw[y * (1 + width * 4)] = 0;
+        raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (1 + width * 4) + 1);
+    }
+    const idat = deflateSync(raw);
+    return Buffer.concat([
+        sig,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', idat),
+        chunk('IEND', new Uint8Array(0)),
+    ]);
+}

package/dist/providers/image/pull-registry.d.ts

@@ -0,0 +1,106 @@
+import { type ImageModelPullEvent } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { ImageProvider } from './types.js';
+/**
+ * Snapshot of one in-flight (or recently-finished) image-model pull.
+ * Exposed to the UI via `GET /api/image-gen/pulls` so a client that
+ * mounted after the pull started can still render an accurate
+ * progress bar without subscribing to the live SSE.
+ */
+export interface ActiveImagePull {
+    id: string;
+    startedAt: string;
+    bytesWritten: number;
+    /** Best-known total. Zero until the first `progress` event arrives. */
+    totalBytes: number;
+    /** Present when the shared downloader is between retry attempts. */
+    retrying?: {
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+        reason: string;
+    };
+    /** Set once a terminal event has been observed (done or error). */
+    finished: boolean;
+    /** Set when the pull errored — kept on the snapshot so reconnecting clients see the failure. */
+    error?: string;
+}
+type Listener = (event: ImageModelPullEvent) => void;
+/**
+ * Where pulls get their provider: the service's routing manager, or the
+ * hosted inference's local provider. Read on every pull so a provider reset
+ * (an engine binary swap) is picked up.
+ */
+export interface ImageProviderSource {
+    current(): Promise<Pick<ImageProvider, 'pullModel'>>;
+}
+/**
+ * Owns the lifecycle of every in-flight image-model pull.
+ *
+ * Pulls used to be tied 1:1 to the HTTP request that started them — when
+ * the client disconnected (navigated away from Settings → Image
+ * generation), the SSE loop exited, the async generator closed, and the
+ * download was aborted by the .partial-leaves-resumable code path. A
+ * returning client had no record the pull ever existed.
+ *
+ * The registry decouples those two: the pull runs in the background owned
+ * by this object, and HTTP requests are just consumers that subscribe to
+ * the live event stream + the cached snapshot. Disconnect detaches the
+ * consumer; the pull keeps going. Cancel is now an explicit `DELETE
+ * /pulls/:id` rather than a side-effect of closing the fetch.
+ */
+export declare class ImageModelPullRegistry {
+    private readonly entries;
+    private readonly controllers;
+    private readonly imageProvider;
+    private readonly catalog;
+    constructor(opts: {
+        imageProvider: ImageProviderSource;
+        catalog: CatalogService;
+    });
+    /**
+     * Start a pull for `id`. Idempotent — when a pull is already in flight
+     * for this id, returns the existing snapshot and does not kick off a
+     * second download. Throws if the catalog id is unknown.
+     *
+     * The pull itself runs in a detached `void` task; this method returns
+     * synchronously-claimed state so callers can immediately subscribe
+     * without racing the first event.
+     */
+    start(id: string): Promise<{
+        snapshot: ActiveImagePull;
+        alreadyRunning: boolean;
+    }>;
+    list(): ActiveImagePull[];
+    get(id: string): ActiveImagePull | null;
+    /**
+     * Subscribe to live events for an in-flight pull. On subscribe, the
+     * registry immediately delivers a synthetic event reflecting the last
+     * known snapshot — without it, a late subscriber to a paused (between
+     * retry attempts) or just-started pull would see nothing until the
+     * next real event, leaving the UI's progress bar blank.
+     *
+     * Returns `null` when no entry exists for `id` so the caller can
+     * 404. Returns an unsubscribe function otherwise; calling it removes
+     * the listener but does NOT cancel the pull — disconnect ≠ cancel.
+     */
+    subscribe(id: string, listener: Listener): (() => void) | null;
+    /**
+     * Cancel an in-flight pull. The shared downloader observes the abort,
+     * leaves the `.partial` in place for resume, and surfaces an `error`
+     * event whose snapshot stays in the registry for `FINISHED_TTL_MS`.
+     * Returns true when a live entry was aborted.
+     */
+    cancel(id: string): boolean;
+    /** Test-only: drop everything so a fresh test starts clean. */
+    clear(): void;
+    private replaySnapshot;
+    private consume;
+    private applyEvent;
+    private broadcast;
+}
+export declare class UnknownImageModelError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+export {};

package/dist/providers/image/pull-registry.js

@@ -0,0 +1,227 @@
+import { createLogger } from '@bendyline/gezel';
+const log = createLogger('image-pulls');
+/**
+ * How long a finished pull (done OR error) stays in the registry after
+ * the terminal event. Long enough that a client polling once per second
+ * sees the final state on reconnect; short enough that the catalog UI's
+ * "Installed" row gets to take over.
+ */
+const FINISHED_TTL_MS = 8_000;
+/**
+ * Owns the lifecycle of every in-flight image-model pull.
+ *
+ * Pulls used to be tied 1:1 to the HTTP request that started them — when
+ * the client disconnected (navigated away from Settings → Image
+ * generation), the SSE loop exited, the async generator closed, and the
+ * download was aborted by the .partial-leaves-resumable code path. A
+ * returning client had no record the pull ever existed.
+ *
+ * The registry decouples those two: the pull runs in the background owned
+ * by this object, and HTTP requests are just consumers that subscribe to
+ * the live event stream + the cached snapshot. Disconnect detaches the
+ * consumer; the pull keeps going. Cancel is now an explicit `DELETE
+ * /pulls/:id` rather than a side-effect of closing the fetch.
+ */
+export class ImageModelPullRegistry {
+    entries = new Map();
+    controllers = new Map();
+    imageProvider;
+    catalog;
+    constructor(opts) {
+        this.imageProvider = opts.imageProvider;
+        this.catalog = opts.catalog;
+    }
+    /**
+     * Start a pull for `id`. Idempotent — when a pull is already in flight
+     * for this id, returns the existing snapshot and does not kick off a
+     * second download. Throws if the catalog id is unknown.
+     *
+     * The pull itself runs in a detached `void` task; this method returns
+     * synchronously-claimed state so callers can immediately subscribe
+     * without racing the first event.
+     */
+    async start(id) {
+        const existing = this.entries.get(id);
+        if (existing && !existing.snapshot.finished) {
+            return { snapshot: { ...existing.snapshot }, alreadyRunning: true };
+        }
+        // Resolve the catalog entry up-front so we can fail fast with a
+        // proper 404 rather than emitting a 200 + error SSE for "unknown id".
+        const item = await this.catalog.get('image-model', id);
+        if (!item || item.manifest.kind !== 'image-model') {
+            throw new UnknownImageModelError(id);
+        }
+        const manifest = item.manifest;
+        const snapshot = {
+            id,
+            startedAt: new Date().toISOString(),
+            bytesWritten: 0,
+            totalBytes: manifest.approxSizeBytes +
+                manifest.auxiliaryFiles.reduce((n, f) => n + f.approxSizeBytes, 0),
+            finished: false,
+        };
+        const entry = { snapshot, listeners: new Set() };
+        this.entries.set(id, entry);
+        const controller = new AbortController();
+        this.controllers.set(id, controller);
+        const spec = {
+            downloadUrl: manifest.downloadUrl,
+            sha256: manifest.sha256,
+            approxSizeBytes: manifest.approxSizeBytes,
+            name: manifest.name,
+            weightsKind: manifest.weightsKind,
+            ...(manifest.supportsImg2Img !== undefined
+                ? { supportsImg2Img: manifest.supportsImg2Img }
+                : {}),
+            auxiliaryFiles: manifest.auxiliaryFiles.map((aux) => ({
+                role: aux.role,
+                downloadUrl: aux.downloadUrl,
+                sha256: aux.sha256,
+                approxSizeBytes: aux.approxSizeBytes,
+            })),
+        };
+        void this.consume(id, spec, controller.signal);
+        return { snapshot: { ...snapshot }, alreadyRunning: false };
+    }
+    list() {
+        return Array.from(this.entries.values()).map((e) => ({ ...e.snapshot }));
+    }
+    get(id) {
+        const entry = this.entries.get(id);
+        return entry ? { ...entry.snapshot } : null;
+    }
+    /**
+     * Subscribe to live events for an in-flight pull. On subscribe, the
+     * registry immediately delivers a synthetic event reflecting the last
+     * known snapshot — without it, a late subscriber to a paused (between
+     * retry attempts) or just-started pull would see nothing until the
+     * next real event, leaving the UI's progress bar blank.
+     *
+     * Returns `null` when no entry exists for `id` so the caller can
+     * 404. Returns an unsubscribe function otherwise; calling it removes
+     * the listener but does NOT cancel the pull — disconnect ≠ cancel.
+     */
+    subscribe(id, listener) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return null;
+        entry.listeners.add(listener);
+        // Replay the current state so the UI renders immediately.
+        this.replaySnapshot(entry.snapshot, listener);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    /**
+     * Cancel an in-flight pull. The shared downloader observes the abort,
+     * leaves the `.partial` in place for resume, and surfaces an `error`
+     * event whose snapshot stays in the registry for `FINISHED_TTL_MS`.
+     * Returns true when a live entry was aborted.
+     */
+    cancel(id) {
+        const controller = this.controllers.get(id);
+        const entry = this.entries.get(id);
+        if (!controller || !entry || entry.snapshot.finished)
+            return false;
+        controller.abort();
+        return true;
+    }
+    /** Test-only: drop everything so a fresh test starts clean. */
+    clear() {
+        for (const controller of this.controllers.values())
+            controller.abort();
+        this.controllers.clear();
+        this.entries.clear();
+    }
+    replaySnapshot(snapshot, listener) {
+        // The order matters: deliver any in-progress retry banner LAST so it
+        // overrides the bare progress bar in the UI's state machine.
+        listener({
+            type: 'progress',
+            bytesWritten: snapshot.bytesWritten,
+            ...(snapshot.totalBytes > 0 ? { totalBytes: snapshot.totalBytes } : {}),
+        });
+        if (snapshot.retrying)
+            listener({ type: 'retrying', ...snapshot.retrying });
+        if (snapshot.error)
+            listener({ type: 'error', error: snapshot.error });
+        if (snapshot.finished && !snapshot.error)
+            listener({ type: 'done', id: snapshot.id });
+    }
+    async consume(id, spec, signal) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        try {
+            const provider = await this.imageProvider.current();
+            for await (const event of provider.pullModel(id, spec, signal)) {
+                this.applyEvent(entry, event);
+                this.broadcast(entry, event);
+                if (event.type === 'done' || event.type === 'error')
+                    break;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const errorEvent = { type: 'error', error: message };
+            this.applyEvent(entry, errorEvent);
+            this.broadcast(entry, errorEvent);
+            log.warn(`[pull-registry] ${id} crashed: ${message}`);
+        }
+        finally {
+            entry.snapshot.finished = true;
+            // Drop the controller — cancel() should be a no-op once finished.
+            this.controllers.delete(id);
+            // Keep the snapshot around briefly so a client mid-reconnect still
+            // sees the terminal state on `list()` / `subscribe()`. Then garbage
+            // collect.
+            const timer = setTimeout(() => {
+                if (this.entries.get(id) === entry)
+                    this.entries.delete(id);
+            }, FINISHED_TTL_MS);
+            timer.unref?.();
+        }
+    }
+    applyEvent(entry, event) {
+        const s = entry.snapshot;
+        if (event.type === 'progress') {
+            s.bytesWritten = event.bytesWritten;
+            if (event.totalBytes !== undefined)
+                s.totalBytes = event.totalBytes;
+            delete s.retrying;
+        }
+        else if (event.type === 'retrying') {
+            s.retrying = {
+                attempt: event.attempt,
+                maxAttempts: event.maxAttempts,
+                delayMs: event.delayMs,
+                reason: event.reason,
+            };
+        }
+        else if (event.type === 'error') {
+            s.error = event.error;
+            delete s.retrying;
+        }
+        else if (event.type === 'done') {
+            delete s.retrying;
+        }
+    }
+    broadcast(entry, event) {
+        for (const listener of entry.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log.warn(`[pull-registry] listener threw: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+}
+export class UnknownImageModelError extends Error {
+    id;
+    constructor(id) {
+        super(`unknown image-model: ${id}`);
+        this.id = id;
+        this.name = 'UnknownImageModelError';
+    }
+}

package/dist/providers/image/sd-cpp.d.ts

@@ -0,0 +1,200 @@
+/**
+ * StableDiffusionCppProvider — talks to a local `sd-server` binary over
+ * HTTP. The server speaks an OpenAI-compatible `/v1/images/generations`
+ * shape with a few extensions (seed, sample_steps, negative_prompt,
+ * cfg_scale) supported by upstream sd.cpp.
+ *
+ * Lifecycle of the server itself is not the provider's concern — an
+ * Electron-side supervisor (Phase 3) spawns / idle-stops the binary and
+ * the provider simply hits whichever URL is configured. If the server
+ * isn't reachable, {@link generate} surfaces a clear error so the UI
+ * can prompt the user to enable image generation in Settings.
+ *
+ * Model management is filesystem-only: weights live under
+ * `<modelsRoot>/<id>/weights.*` alongside a resolved copy of the
+ * catalog manifest (so local state is self-describing even if the
+ * catalog entry later disappears).
+ */
+import { type ModelStorageRoots } from '../../models/storage-roots.js';
+import type { GpuArbiter } from '../gpu-arbiter.js';
+import type { NativeEngineSupervisor } from '../native/supervisor.js';
+import { type ImageEngineHealth, type ImageGenerationInput, type ImageGenerationOutput, type ImageGenerationProgress, type ImageModelPullEvent, type ImageModelPullSpec, type ImageProvider, type InstalledImageModelInfo } from './types.js';
+export interface StableDiffusionCppProviderOptions {
+    /** Base URL of the running sd-server (no trailing slash). */
+    baseUrl: string;
+    /** Absolute path to `~/.gezel/engines/sd-cpp/models`. */
+    modelsRoot: string;
+    /** Optional read-only machine-store overlay. */
+    storageRoots?: ModelStorageRoots;
+    /** Awake-time budget for one render request, in ms. Defaults to 30 minutes. */
+    timeoutMs?: number;
+    /** Injected for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional lifecycle manager. When supplied, the provider calls
+     * `ensureRunning()` before each generate and uses the returned
+     * baseUrl (overriding `baseUrl`) — so lazy-start / idle-stop /
+     * health-watch all work transparently. Omit for "user runs
+     * sd-server themselves" deployments.
+     */
+    supervisor?: NativeEngineSupervisor;
+    /**
+     * Whether the factory had a real engine wiring (an explicit URL or a
+     * spawnable binary) at construction. The default-loopback fallback
+     * sets this to false so `health()` can return `not-configured`
+     * instead of `unreachable` — distinct UI state, distinct guidance.
+     */
+    configured?: boolean;
+    /**
+     * Cross-engine GPU coordinator. When supplied alongside a
+     * supervisor, the provider acquires the `'image'` slot before each
+     * generate (which evicts the local LLM in `swap` mode) and
+     * registers its supervisor's `stop()` as the `'image'` evictor so
+     * the LLM can evict us back symmetrically.
+     */
+    arbiter?: GpuArbiter;
+    /**
+     * Shared, mutable holder the supervised path uses to tell the
+     * factory's `resolveLaunch` which installed model to spawn sd-server
+     * with. sd-server serves one model per process, so when a request
+     * targets a different installed model than the one loaded, the
+     * provider updates `modelId` here and stops the running server — the
+     * next `ensureRunning()` relaunches with the requested model instead
+     * of always serving whichever model sorts first.
+     */
+    launchState?: {
+        modelId: string | undefined;
+    };
+    /**
+     * The user's configured default model (`config.defaultImageModel['sd-cpp']`,
+     * Settings -> Image generation). Read on every generate that names no model
+     * of its own. A configured id that is no longer installed falls through to
+     * the first installed model, which is what every install did before this
+     * setting existed.
+     */
+    defaultModelId?: string;
+}
+/**
+ * Model-specific step counts, from fast distilled models to the 50 of MOSS
+ * and Iris. Shared with `buildSdServerArgs`, which sets
+ * the same server launch default for endpoints that ignore request steps.
+ */
+export declare const MODEL_SAMPLE_STEP_DEFAULTS: Map<string, number>;
+/**
+ * Classifier-free guidance (CFG) scale per model, applied to the
+ * `/sdapi/v1/txt2img` request. Distilled / Flux-flow models are trained
+ * to run at CFG 1 — their guidance is baked in (turbo/lightning) or
+ * carried by the separate Flux distilled-guidance value. Applying
+ * sd-server's higher default CFG to them blows out color and contrast
+ * (the oversaturated, "burned" look Krea 2 Turbo had before this).
+ * Models absent from the map (traditional SD 1.x / SDXL checkpoints)
+ * omit `cfg_scale` and inherit the server default, preserving their
+ * established behavior.
+ */
+export declare const MODEL_CFG_DEFAULTS: Map<string, number>;
+/**
+ * Whether the engine runs this model with guidance that reads a negative
+ * prompt. At CFG 1 the unconditional pass that carries it is skipped.
+ * Models absent from the map run at the server's default of 7.
+ */
+export declare function sdCppHonorsNegativePrompt(modelId: string): boolean;
+/** Pin samplers validated with the native engine for these models. */
+export declare const MODEL_SAMPLER_DEFAULTS: Map<string, string>;
+/**
+ * Models whose VAE shows visible tile-boundary seams under
+ * stable-diffusion.cpp's `--vae-tiling` (Krea 2's Qwen-Image VAE is the
+ * known case — rainbow column streaks at ≤512px). `--vae-tiling` is a
+ * launch-time, size-agnostic flag: sd-server serves every request size
+ * from one process, so we can't gate it per-request on image size as
+ * we'd ideally like — we gate it per-model instead and skip it here.
+ * The trade-off is that very large renders of these models could hit a
+ * VAE allocation cap on memory-constrained GPUs; acceptable given these
+ * are high-VRAM models and seam-free output matters more.
+ */
+export declare const VAE_TILING_INCOMPATIBLE_MODELS: Set<string>;
+/**
+ * The launch choices that change what sd-server holds in memory for one
+ * model. Read by the launch argv and by memory pricing, so the price is for
+ * the process that actually starts.
+ */
+export interface SdServerLoadProfile {
+    vaeDecode: 'tiled' | 'untiled' | 'none';
+    /** The default render size, which working memory follows more than the weights do. */
+    defaultSidePx: number;
+    /** A `--tensor-type-rules` pattern whose tensors load as bfloat16. */
+    bf16TensorPattern?: string;
+    diffusionFlashAttention: boolean;
+    /**
+     * Reuse a diffusion transformer's output across steps whose input barely
+     * changed (`--cache-mode easycache`). Only for a model whose renders it was
+     * measured not to change.
+     */
+    stepCache?: 'easycache';
+}
+export declare function sdServerLoadProfile(modelId: string): SdServerLoadProfile;
+export declare class StableDiffusionCppProvider implements ImageProvider {
+    readonly name = "sd-cpp";
+    private readonly baseUrl;
+    private readonly modelsRoot;
+    private readonly storageRoots;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly supervisor?;
+    private readonly configured;
+    private readonly arbiter?;
+    private readonly launchState?;
+    private readonly defaultModelId?;
+    private renderTail;
+    private pendingRenders;
+    constructor(opts: StableDiffusionCppProviderOptions);
+    generate(input: ImageGenerationInput): Promise<ImageGenerationOutput>;
+    private generateInner;
+    listInstalledModels(): Promise<InstalledImageModelInfo[]>;
+    pullModel(id: string, spec: ImageModelPullSpec, signal?: AbortSignal): AsyncIterable<ImageModelPullEvent>;
+    /**
+     * Stream a single URL to disk with sha256 verification, reporting cumulative
+     * progress against `totalAllBytes` so multi-file pulls share one bar.
+     *
+     * Delegates the network plumbing to `downloadWithRetry` — that handles
+     * Range-based resume, exponential backoff, chunk-stall timeouts, and
+     * friendly error messages. This wrapper only owns the
+     * provider-specific concerns: sha256 verification, the
+     * `writtenSoFar`-aware progress translation, and the atomic rename
+     * after verify.
+     */
+    private downloadFile;
+    deleteModel(id: string): Promise<void>;
+    health(): Promise<ImageEngineHealth>;
+    shutdown(): Promise<void>;
+    /**
+     * The configured default when it is installed, else the first installed
+     * model id, else undefined. Stable ordering matches
+     * {@link listInstalledModels} so the default is deterministic.
+     */
+    resolveDefaultModelId(): Promise<string | undefined>;
+    private defaultSampleSteps;
+    /**
+     * Read the installed `manifest.json` fields that steer per-model
+     * behavior. Returns null for unknown ids and unreadable/legacy
+     * metadata — callers fall back to their per-field defaults. (Older
+     * installed metadata did not persist catalog generation defaults or
+     * the img2img capability.)
+     */
+    private readInstalledManifestFields;
+}
+/**
+ * Parse one line of sd-server's weight-load bar, which it prints inside the
+ * first request after a launch because it loads weights lazily:
+ *
+ *     |#########                                         | 49/298 - 435.57MB/s
+ */
+export declare function parseWeightLoadProgress(line: string): ImageGenerationProgress | null;
+/**
+ * Classify sd-server's progress bars into phases. Weight loads print a
+ * bytes-per-second bar. The first iteration bar is sampling; once it
+ * completes, the next is the tiled VAE decode, which reports tiles rather
+ * than steps. The step count the engine prints is used rather than the one
+ * requested, because some launch defaults override a request's steps.
+ */
+export declare function progressTracker(emit: (progress: ImageGenerationProgress) => void): (line: string) => void;
+export declare function parseSamplingProgress(line: string): ImageGenerationProgress | null;