@bendyline/gezel-inference 1.0.3 → 1.0.4

package/dist/providers/ds4/dspark.js

@@ -6,9 +6,12 @@
  * one measurement shape the policy here:
  *
  *  - **The engine refuses an external MTP model alongside `--ssd-streaming`**,
- *    aborting at startup. Streaming
- *    is gezel's safe default and the only way the 153 GiB Q4 GGUF runs at all
- *    on a 128 GiB machine, so drafting is unreachable for most installs.
+ *    aborting at startup, for every family except DeepSeek V4.1
+ *    (`general.architecture` `deepseek41`, upstream ee7e840). Streaming is the
+ *    only way the 153 GiB Q4 GGUF runs at all on a 128 GiB machine, so
+ *    drafting is unreachable there. V4.1 keeps its 8.04 GiB drafter resident
+ *    while the target's experts stream, but upstream warns it can still be
+ *    slower than plain decoding, so `auto` never drafts a streamed launch.
  *  - **A support model is required.** Without one there is nothing to draft
  *    with, and ds4 exits on `--dspark` alone ("--dspark requires --mtp-model FILE").
  *  - **It does not pay on Metal.** Measured 2026-08-26, M5 Max, DeepSeek V4
@@ -23,6 +26,20 @@
  * residency-or-unified predicate would enable drafting on the one platform
  * where it was measured to lose.
  */
+/**
+ * Whether ds4 accepts `--mtp-model` alongside `--ssd-streaming` for a target
+ * with this GGUF `general.architecture`. Mirrors the engine's own check
+ * (`DS4_MODEL_FAMILY != DS4_MODEL_FAMILY_DEEPSEEK41` in `ds4_engine_open`);
+ * an unknown architecture is treated as unsupported because the engine aborts.
+ */
+export function ds4DsparkStreamsWithSsd(architecture) {
+    return architecture === 'deepseek41';
+}
+/**
+ * Buffers ds4 allocates beside a V4.1 drafter's weights; its startup memory
+ * plan charges `mtp_model.size + 64 MiB` for them.
+ */
+export const DS4_V41_DRAFTER_RUNTIME_BYTES = 64 * 1024 ** 2;
 /**
  * Resolve whether this launch drafts, and with what.
  *
@@ -47,24 +64,29 @@ export function resolveDs4Dspark(opts) {
                 : {}),
         };
     }
-    if (opts.ssdStreaming) {
+    if (opts.ssdStreaming && !ds4DsparkStreamsWithSsd(opts.targetArchitecture)) {
         return {
             enabled: false,
-            reason: 'SSD streaming is on; ds4 rejects --mtp-model with --ssd-streaming',
+            reason: 'SSD streaming is on; ds4 rejects --mtp-model with --ssd-streaming except for DeepSeek V4.1',
             ...(mode === 'on'
                 ? {
-                    unmetRequest: 'ds4Dspark=on cannot be honored while SSD streaming is active — ds4 refuses an external --mtp-model with --ssd-streaming. Full residency requires a model that fits this machine with headroom to spare (ds4SsdStreaming=false).',
+                    unmetRequest: 'ds4Dspark=on cannot be honored while SSD streaming is active — ds4 refuses an external --mtp-model with --ssd-streaming for every model but DeepSeek V4.1. Full residency requires a model that fits this machine with headroom to spare (ds4SsdStreaming=false).',
                 }
                 : {}),
         };
     }
     if (opts.companionFitsMemory === false) {
+        const held = opts.ssdStreaming
+            ? 'the resident weights and a minimum expert cache'
+            : 'the resident weights';
         return {
             enabled: false,
-            reason: 'support model does not fit alongside the resident weights',
+            reason: `support model does not fit alongside ${held}`,
             ...(mode === 'on'
                 ? {
-                    unmetRequest: 'ds4Dspark=on cannot be honored: the DSpark support model does not fit in memory alongside the fully resident weights. Drafting was dropped rather than giving up full residency, which is worth far more than drafting.',
+                    unmetRequest: opts.ssdStreaming
+                        ? `ds4Dspark=on cannot be honored: the DSpark support model does not fit in memory alongside ${held}. Drafting was dropped rather than starving the expert cache.`
+                        : 'ds4Dspark=on cannot be honored: the DSpark support model does not fit in memory alongside the fully resident weights. Drafting was dropped rather than giving up full residency, which is worth far more than drafting.',
                 }
                 : {}),
         };
@@ -77,6 +99,12 @@ export function resolveDs4Dspark(opts) {
         };
     }
     // auto
+    if (opts.ssdStreaming) {
+        return {
+            enabled: false,
+            reason: 'auto: drafting a streamed launch is unmeasured and upstream reports it can be slower; set ds4Dspark=on to draft',
+        };
+    }
     if (opts.backend !== 'cuda') {
         return {
             enabled: false,

package/dist/providers/image/img2img-support.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-model img2img capability resolution for the local sd-cpp engine.
+ *
+ * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
+ * `init_images` for any loaded model, but whether the *architecture*
+ * actually honors the init latents varies: the classic SD 1.x / SDXL
+ * denoising path is mature, while newer diffusion-model architectures
+ * (FLUX.2's LLM-encoder family, Krea 2's Qwen-Image lineage) are unverified on
+ * the pinned sd-server — the same server build that already ignores
+ * per-request step overrides for Krea (see MODEL_SAMPLE_STEP_DEFAULTS).
+ *
+ * Resolution ladder, most explicit wins:
+ *   1. `supportsImg2Img` declared on the catalog manifest (persisted
+ *      into the installed `manifest.json` at pull time),
+ *   2. the assessment map below (repo-local truth for shipped models,
+ *      same pattern as MODEL_CFG_DEFAULTS),
+ *   3. a `weightsKind` default: `checkpoint` (and unknown/legacy
+ *      installs, which are all SD-era checkpoints) → supported;
+ *      `diffusion-model` → not supported until assessed.
+ *
+ * When a model resolves unsupported, callers drop the input images and
+ * report `img2imgSkippedReason` instead of silently producing an
+ * "edit" that never saw the source image. Flip a map entry (or set the
+ * catalog field) after verifying a family on real hardware.
+ */
+export declare const MODEL_IMG2IMG_SUPPORT: Map<string, boolean>;
+export interface Img2ImgSupportInput {
+    /** Resolved model id; undefined when nothing is installed. */
+    modelId?: string | undefined;
+    /** Explicit capability from catalog/installed metadata, when declared. */
+    explicit?: boolean | undefined;
+    /** Loading shape from installed metadata, when recorded. */
+    weightsKind?: 'checkpoint' | 'diffusion-model' | undefined;
+}
+export interface Img2ImgSupportVerdict {
+    supported: boolean;
+    /** Human-readable reason, set only when unsupported. */
+    reason?: string;
+}
+export declare function resolveImg2ImgSupport(input: Img2ImgSupportInput): Img2ImgSupportVerdict;

package/dist/providers/image/img2img-support.js

@@ -0,0 +1,74 @@
+/**
+ * Per-model img2img capability resolution for the local sd-cpp engine.
+ *
+ * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
+ * `init_images` for any loaded model, but whether the *architecture*
+ * actually honors the init latents varies: the classic SD 1.x / SDXL
+ * denoising path is mature, while newer diffusion-model architectures
+ * (FLUX.2's LLM-encoder family, Krea 2's Qwen-Image lineage) are unverified on
+ * the pinned sd-server — the same server build that already ignores
+ * per-request step overrides for Krea (see MODEL_SAMPLE_STEP_DEFAULTS).
+ *
+ * Resolution ladder, most explicit wins:
+ *   1. `supportsImg2Img` declared on the catalog manifest (persisted
+ *      into the installed `manifest.json` at pull time),
+ *   2. the assessment map below (repo-local truth for shipped models,
+ *      same pattern as MODEL_CFG_DEFAULTS),
+ *   3. a `weightsKind` default: `checkpoint` (and unknown/legacy
+ *      installs, which are all SD-era checkpoints) → supported;
+ *      `diffusion-model` → not supported until assessed.
+ *
+ * When a model resolves unsupported, callers drop the input images and
+ * report `img2imgSkippedReason` instead of silently producing an
+ * "edit" that never saw the source image. Flip a map entry (or set the
+ * catalog field) after verifying a family on real hardware.
+ */
+export const MODEL_IMG2IMG_SUPPORT = new Map([
+    // Classic SD checkpoints — the original, well-exercised img2img path.
+    ['sd-1.5', true],
+    ['sd-turbo', true],
+    ['sdxl-base-1.0', true],
+    ['sdxl-turbo', true],
+    ['sdxl-lightning-4step', true],
+    ['animagine-xl-4', true],
+    // FLUX.1 — img2img documented working in upstream stable-diffusion.cpp.
+    // Still in the pinned catalog and on people's disks.
+    ['flux-1-schnell-q4', true],
+    ['flux-1-dev-q4', true],
+    // FLUX.2 Klein — LLM-text-encoder flow model; img2img unverified on the
+    // pinned sd-server. Treat as txt2img-only until assessed.
+    ['flux-2-klein-4b-q4', false],
+    // Krea 2 Turbo — Qwen-Image architecture; the pinned server already has
+    // known per-request gaps for these models (steps override ignored).
+    ['krea-2-turbo-q4', false],
+    ['krea-2-turbo-q6', false],
+    ['krea-2-turbo-q8', false],
+]);
+export function resolveImg2ImgSupport(input) {
+    if (input.explicit !== undefined) {
+        return input.explicit
+            ? { supported: true }
+            : {
+                supported: false,
+                reason: `model ${input.modelId ?? 'unknown'} does not support image editing (img2img)`,
+            };
+    }
+    if (input.modelId !== undefined) {
+        const assessed = MODEL_IMG2IMG_SUPPORT.get(input.modelId);
+        if (assessed !== undefined) {
+            return assessed
+                ? { supported: true }
+                : {
+                    supported: false,
+                    reason: `model ${input.modelId} does not support image editing (img2img) on the bundled engine`,
+                };
+        }
+    }
+    if (input.weightsKind === 'diffusion-model') {
+        return {
+            supported: false,
+            reason: `model ${input.modelId ?? 'unknown'} has not been verified for image editing (img2img) on the bundled engine`,
+        };
+    }
+    return { supported: true };
+}

package/dist/providers/image/local-engine.d.ts

@@ -0,0 +1,31 @@
+import type { GezelConfig } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { GpuArbiter } from '../gpu-arbiter.js';
+import { ImageModelPullRegistry } from './pull-registry.js';
+import type { ImageProvider } from './types.js';
+export interface LocalImageEngineOptions {
+    home: string;
+    catalog: CatalogService;
+    arbiter: GpuArbiter;
+    readConfig: () => Promise<Pick<GezelConfig, 'defaultImageModel'>>;
+    /** Override for tests. */
+    env?: NodeJS.ProcessEnv;
+    /** Test seam: a provider in place of the local engine. */
+    provider?: ImageProvider;
+}
+/**
+ * Hosted inference's image engine: the local sd-server provider, built on
+ * first use, plus the pulls that install its models. Reset drains in-flight
+ * renders before an engine binary swap takes effect.
+ */
+export declare class LocalImageEngine {
+    private readonly opts;
+    readonly pulls: ImageModelPullRegistry;
+    private readonly lifecycle;
+    constructor(opts: LocalImageEngineOptions);
+    /** Whether this host can render at all: an engine binary, a server URL, or the mock. */
+    available(): boolean;
+    current(): Promise<ImageProvider>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/providers/image/local-engine.js

@@ -0,0 +1,47 @@
+import { ProviderLifecycle } from '../provider-lifecycle.js';
+import { createLocalImageProvider } from './local-factory.js';
+import { ImageModelPullRegistry } from './pull-registry.js';
+/**
+ * Hosted inference's image engine: the local sd-server provider, built on
+ * first use, plus the pulls that install its models. Reset drains in-flight
+ * renders before an engine binary swap takes effect.
+ */
+export class LocalImageEngine {
+    opts;
+    pulls;
+    // Only promise-returning operations can be tracked; a pull is an async
+    // iterable and is cancelled through its own registry instead.
+    lifecycle = new ProviderLifecycle(new Set(['generate', 'deleteModel']));
+    constructor(opts) {
+        this.opts = opts;
+        this.pulls = new ImageModelPullRegistry({ imageProvider: this, catalog: opts.catalog });
+    }
+    /** Whether this host can render at all: an engine binary, a server URL, or the mock. */
+    available() {
+        if (this.opts.provider)
+            return true;
+        const env = this.opts.env ?? process.env;
+        return Boolean(env.GEZEL_MOCK_PROVIDER === '1' || env.GEZEL_SD_SERVER_BIN || env.GEZEL_SD_SERVER_URL);
+    }
+    current() {
+        return this.lifecycle.current(async () => {
+            if (this.opts.provider)
+                return this.opts.provider;
+            const config = await this.opts.readConfig().catch(() => ({}));
+            const defaultModelId = config.defaultImageModel?.['sd-cpp'];
+            return createLocalImageProvider({
+                home: this.opts.home,
+                arbiter: this.opts.arbiter,
+                ...(this.opts.env ? { env: this.opts.env } : {}),
+                ...(defaultModelId ? { defaultModelId } : {}),
+            });
+        }, false);
+    }
+    reset() {
+        return this.lifecycle.reset();
+    }
+    async shutdown() {
+        this.pulls.clear();
+        await this.lifecycle.reset();
+    }
+}

package/dist/providers/image/local-factory.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The local image provider: stable-diffusion.cpp's `sd-server` on this
+ * machine. Shared by the full service (behind its cloud and remote routing)
+ * and by hosted inference, which serves only this.
+ *
+ * Selection rules (first-match):
+ *   1. `GEZEL_MOCK_PROVIDER=1` → `MockImageProvider` (tests, CI).
+ *   2. `GEZEL_SD_SERVER_URL` present → `StableDiffusionCppProvider`
+ *      pointed at that URL, no supervisor ("user runs their own
+ *      server" mode — useful during development).
+ *   3. `GEZEL_SD_SERVER_BIN` present → `StableDiffusionCppProvider`
+ *      backed by a `NativeEngineSupervisor` that spawns the binary
+ *      on-demand at an ephemeral port.
+ *   4. Fallback: `StableDiffusionCppProvider` with the default
+ *      base URL (127.0.0.1:9081) and no supervisor. `health()` reports
+ *      `not-configured` so the UI can say the engine is not installed.
+ */
+import type { GpuArbiter } from '../gpu-arbiter.js';
+import type { NativeCapacityOptions } from '../native/device-capacity.js';
+import type { ImageProvider, InstalledImageModelInfo } from './types.js';
+export interface LocalImageProviderOptions {
+    home: string;
+    /** Override for tests. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The person's default local model (`config.defaultImageModel['sd-cpp']`).
+     * A configured id that is no longer installed falls through to the first
+     * installed model.
+     */
+    defaultModelId?: string;
+    /**
+     * Cross-engine GPU coordinator. Forwarded only to the supervised branch —
+     * the user-runs-their-own (`GEZEL_SD_SERVER_URL`) path doesn't manage
+     * VRAM tenancy.
+     */
+    arbiter?: GpuArbiter;
+}
+/**
+ * Nothing to generate with: the person has to download a model first. Its
+ * own type so a route can answer with the fix, not a bare 500, which reads
+ * to an outside app as "something went wrong inside Gezel".
+ */
+export declare class NoLocalImageModelError extends Error {
+    readonly code = "no_local_image_model";
+    constructor();
+}
+/**
+ * How sd-server is admitted to the device memory ledger: by bytes, like any
+ * other engine, never exclusively. The ledger already refuses co-residency
+ * where the byte or GPU budget cannot hold both, and `detectGpuPolicy` states
+ * the rule: automatic heuristics must not serialize models that fit.
+ * Exclusive admission did exactly that. On a DGX Spark with gemma4-31b
+ * resident (95 GB of a 128 GB machine), a 4-second SDXL render waited up to
+ * 89 s for the chat engine to go idle, then was evicted as soon as the next
+ * chat turn asked for memory, so every render paid a fresh load.
+ */
+export declare function sdServerCapacity(home: string): NativeCapacityOptions;
+export declare function createLocalImageProvider(opts: LocalImageProviderOptions): Promise<ImageProvider>;
+export interface ResolvedInstalledModel extends InstalledImageModelInfo {
+    weightsPath: string;
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    auxiliaryFiles: Array<{
+        role: string;
+        path: string;
+    }>;
+}
+/**
+ * Translate a resolved on-disk model into stable-diffusion.cpp's `sd-server`
+ * launch flags. `checkpoint` weights load via `--model`; `diffusion-model`
+ * weights are unet-only and ride alongside `--vae`/`--clip_l`/`--clip_g`/
+ * `--t5xxl` from the auxiliary files. Aux roles map 1:1 to flag names.
+ *
+ * Bind flags use `--listen-ip` / `--listen-port` (NOT `--host` / `--port`)
+ * — that's the upstream stable-diffusion.cpp server CLI as of master-587;
+ * earlier llama.cpp-style `--host` / `--port` will be rejected with
+ * `error: unknown argument: --host` and the supervisor restart-loops.
+ *
+ * `--vae-tiling` is the default because SDXL/Flux-class VAE decode at
+ * 800–1024px wants a single ~7 GB Vulkan buffer, which exceeds the
+ * per-allocation cap most consumer drivers enforce (~25–50% of total
+ * VRAM). The OOM lands at the very last step (sampling completes, then
+ * VAE blows up), wasting the entire generation. Tiled decode splits
+ * that buffer into chunks at ~10–20% decode-speed cost; on a 12 GB
+ * card it's the difference between succeeding and dying on `vae alloc
+ * compute buffer failed`. Quality difference is imperceptible for the
+ * tile sizes sd.cpp picks.
+ *
+ * The text encoder never takes flash attention. ggml's CPU kernel sums the
+ * attention values in FP16, which a Qwen-family encoder overflows: FLUX.2
+ * klein on a Windows-on-ARM CPU rendered unrelated shapes with a 200
+ * (native-v0.1.53). It bites wherever the encoder lands on the CPU, and the
+ * encoder runs once per image, so GPUs lose nothing. `--diffusion-fa` means
+ * `--flash-attn off,diffusion=on`, so that branch already leaves it off.
+ */
+export declare function buildSdServerArgs(model: ResolvedInstalledModel, port: number): string[];

package/dist/providers/image/local-factory.js

@@ -0,0 +1,270 @@
+/**
+ * The local image provider: stable-diffusion.cpp's `sd-server` on this
+ * machine. Shared by the full service (behind its cloud and remote routing)
+ * and by hosted inference, which serves only this.
+ *
+ * Selection rules (first-match):
+ *   1. `GEZEL_MOCK_PROVIDER=1` → `MockImageProvider` (tests, CI).
+ *   2. `GEZEL_SD_SERVER_URL` present → `StableDiffusionCppProvider`
+ *      pointed at that URL, no supervisor ("user runs their own
+ *      server" mode — useful during development).
+ *   3. `GEZEL_SD_SERVER_BIN` present → `StableDiffusionCppProvider`
+ *      backed by a `NativeEngineSupervisor` that spawns the binary
+ *      on-demand at an ephemeral port.
+ *   4. Fallback: `StableDiffusionCppProvider` with the default
+ *      base URL (127.0.0.1:9081) and no supervisor. `health()` reports
+ *      `not-configured` so the UI can say the engine is not installed.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { imageMediaPool, sdServerLedgerClaim, sdServerRequirement, } from '../../models/image-fit.js';
+import { findModelRoot, listOverlayModelIds, modelStorageRoots, verifyReadOnlyModelPayload, } from '../../models/storage-roots.js';
+import { localSdCppWeightFiles } from '../../models/weight-facts.js';
+import { pressureIdleGraceMs } from '../native/capacity-broker.js';
+import { measuredCapacityBudget } from '../native/measured-budget.js';
+import { pickFreePort } from '../native/port.js';
+import { NativeEngineSupervisor } from '../native/supervisor.js';
+import { patientFetch } from '../patient-fetch.js';
+import { MockImageProvider } from './mock.js';
+import { MODEL_SAMPLE_STEP_DEFAULTS, StableDiffusionCppProvider, sdServerLoadProfile, } from './sd-cpp.js';
+/**
+ * Nothing to generate with: the person has to download a model first. Its
+ * own type so a route can answer with the fix, not a bare 500, which reads
+ * to an outside app as "something went wrong inside Gezel".
+ */
+export class NoLocalImageModelError extends Error {
+    code = 'no_local_image_model';
+    constructor() {
+        super('No image model is available locally. Download one from Settings → Image generation before generating.');
+        this.name = 'NoLocalImageModelError';
+    }
+}
+/**
+ * How sd-server is admitted to the device memory ledger: by bytes, like any
+ * other engine, never exclusively. The ledger already refuses co-residency
+ * where the byte or GPU budget cannot hold both, and `detectGpuPolicy` states
+ * the rule: automatic heuristics must not serialize models that fit.
+ * Exclusive admission did exactly that. On a DGX Spark with gemma4-31b
+ * resident (95 GB of a 128 GB machine), a 4-second SDXL render waited up to
+ * 89 s for the chat engine to go idle, then was evicted as soon as the next
+ * chat turn asked for memory, so every render paid a fresh load.
+ */
+export function sdServerCapacity(home) {
+    return { home };
+}
+export async function createLocalImageProvider(opts) {
+    const env = opts.env ?? process.env;
+    const storageRoots = modelStorageRoots({ home: opts.home, engine: 'sd-cpp', env });
+    const modelsRoot = storageRoots.writableRoot;
+    const defaultLocalModelId = opts.defaultModelId;
+    if (env.GEZEL_MOCK_PROVIDER === '1') {
+        return new MockImageProvider();
+    }
+    if (env.GEZEL_SD_SERVER_URL) {
+        return new StableDiffusionCppProvider({
+            baseUrl: env.GEZEL_SD_SERVER_URL,
+            modelsRoot,
+            storageRoots,
+            fetchImpl: patientFetch(),
+            ...(defaultLocalModelId ? { defaultModelId: defaultLocalModelId } : {}),
+        });
+    }
+    if (env.GEZEL_SD_SERVER_BIN) {
+        const binary = env.GEZEL_SD_SERVER_BIN;
+        // Track the most-recently-resolved launch so the provider can point
+        // fetch() at the right port without the supervisor exposing state.
+        let cachedPort;
+        // Shared with the provider: which installed model to launch
+        // sd-server with. sd-server is single-model per process, so the
+        // provider sets this to the requested model and stops the server
+        // when it changes; resolveLaunch reads it on the next start.
+        const launchState = { modelId: undefined };
+        let launchedModel;
+        const supervisor = new NativeEngineSupervisor({
+            capacity: {
+                ...sdServerCapacity(opts.home),
+                // Price the launched model from its own weight files — the same
+                // pricing the download page used — and claim what the render
+                // actually holds on the card (see sdServerLedgerClaim).
+                requirement: async () => {
+                    if (!launchedModel)
+                        return undefined;
+                    const budget = await measuredCapacityBudget();
+                    const requirement = sdServerRequirement({
+                        modelId: launchedModel.id,
+                        weightsKind: launchedModel.weightsKind,
+                        files: await localSdCppWeightFiles(launchedModel),
+                        pool: imageMediaPool(budget.kind),
+                    });
+                    return sdServerLedgerClaim(requirement, budget.fastBytes);
+                },
+            },
+            logPrefix: '[sd-server]',
+            // sd-server has no `/health`. It answers the root with an HTML file
+            // (with --serve-html-path) or a 404, and starts listening only once
+            // it has read the model's metadata — the weights themselves load
+            // inside the first request. Any HTTP response is the signal.
+            readinessPath: '/',
+            readyOnAnyResponse: true,
+            // Cold start can take a while: metadata for a 49 GB model, backend
+            // init, first kernel compile. Give the readiness probe generous
+            // headroom so first launch doesn't trip the restart-budget guard.
+            startupTimeoutMs: 5 * 60 * 1000,
+            // An idle image engine gives its memory back when a chat model is
+            // waiting for it, the same way the chat engines yield to a render.
+            ...(opts.arbiter
+                ? {
+                    memoryPressure: () => opts.arbiter.getMemoryPressureStatus(),
+                    pressureIdleTimeoutMs: pressureIdleGraceMs(),
+                }
+                : {}),
+            resolveLaunch: async () => {
+                const port = cachedPort ?? (await pickFreePort());
+                cachedPort = port;
+                // Prefer the model the provider asked for, then the configured
+                // default, then the first installed — covering a generate with no
+                // explicit model, and a requested (or configured) model having
+                // since been deleted.
+                const requestedId = launchState.modelId ?? defaultLocalModelId;
+                const model = (requestedId ? await findInstalledModel(storageRoots, requestedId) : undefined) ??
+                    (await findFirstInstalledModel(storageRoots));
+                if (!model)
+                    throw new NoLocalImageModelError();
+                launchedModel = model;
+                return {
+                    command: binary,
+                    args: buildSdServerArgs(model, port),
+                    baseUrl: `http://127.0.0.1:${port}`,
+                };
+            },
+        });
+        return new StableDiffusionCppProvider({
+            // The baseUrl here is only the fallback when the supervisor is
+            // not yet resolved; generate() overrides from `ensureRunning()`.
+            baseUrl: 'http://127.0.0.1:9081',
+            modelsRoot,
+            storageRoots,
+            supervisor,
+            launchState,
+            fetchImpl: patientFetch(),
+            ...(defaultLocalModelId ? { defaultModelId: defaultLocalModelId } : {}),
+            ...(opts.arbiter ? { arbiter: opts.arbiter } : {}),
+        });
+    }
+    return new StableDiffusionCppProvider({
+        baseUrl: 'http://127.0.0.1:9081',
+        modelsRoot,
+        storageRoots,
+        ...(defaultLocalModelId ? { defaultModelId: defaultLocalModelId } : {}),
+        // Nothing was wired up. Flag the provider so `health()` can return
+        // `not-configured` (distinct UI guidance) rather than making the user
+        // wait for a generic "unreachable" probe to fail.
+        configured: false,
+    });
+}
+/**
+ * Read one installed model's resolved launch info from its on-disk
+ * `manifest.json`, or undefined if absent / malformed / incomplete.
+ */
+async function resolveInstalledModel(modelsRoot, id, storageRoots) {
+    try {
+        const itemDir = join(modelsRoot, id);
+        const raw = await readFile(join(itemDir, 'manifest.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.id || !parsed.name || !parsed.weightsFilename)
+            return undefined;
+        if (storageRoots &&
+            !(await verifyReadOnlyModelPayload(storageRoots, modelsRoot, id, parsed.fileSha256))) {
+            return undefined;
+        }
+        const aux = [];
+        for (const a of parsed.auxiliaryFiles ?? []) {
+            if (a.role && a.filename)
+                aux.push({ role: a.role, path: join(itemDir, a.filename) });
+        }
+        return {
+            id: parsed.id,
+            name: parsed.name,
+            approxSizeBytes: parsed.approxSizeBytes ?? 0,
+            installedAt: parsed.installedAt ?? new Date().toISOString(),
+            weightsPath: join(itemDir, parsed.weightsFilename),
+            weightsKind: parsed.weightsKind ?? 'checkpoint',
+            auxiliaryFiles: aux,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve a specific installed model by id (the one a request targets). */
+async function findInstalledModel(storageRoots, id) {
+    const root = await findModelRoot(storageRoots, id);
+    return root ? resolveInstalledModel(root, id, storageRoots) : undefined;
+}
+async function findFirstInstalledModel(storageRoots) {
+    const entries = await listOverlayModelIds(storageRoots);
+    entries.sort();
+    for (const id of entries) {
+        const model = await findInstalledModel(storageRoots, id);
+        if (model)
+            return model;
+    }
+    return undefined;
+}
+/**
+ * Translate a resolved on-disk model into stable-diffusion.cpp's `sd-server`
+ * launch flags. `checkpoint` weights load via `--model`; `diffusion-model`
+ * weights are unet-only and ride alongside `--vae`/`--clip_l`/`--clip_g`/
+ * `--t5xxl` from the auxiliary files. Aux roles map 1:1 to flag names.
+ *
+ * Bind flags use `--listen-ip` / `--listen-port` (NOT `--host` / `--port`)
+ * — that's the upstream stable-diffusion.cpp server CLI as of master-587;
+ * earlier llama.cpp-style `--host` / `--port` will be rejected with
+ * `error: unknown argument: --host` and the supervisor restart-loops.
+ *
+ * `--vae-tiling` is the default because SDXL/Flux-class VAE decode at
+ * 800–1024px wants a single ~7 GB Vulkan buffer, which exceeds the
+ * per-allocation cap most consumer drivers enforce (~25–50% of total
+ * VRAM). The OOM lands at the very last step (sampling completes, then
+ * VAE blows up), wasting the entire generation. Tiled decode splits
+ * that buffer into chunks at ~10–20% decode-speed cost; on a 12 GB
+ * card it's the difference between succeeding and dying on `vae alloc
+ * compute buffer failed`. Quality difference is imperceptible for the
+ * tile sizes sd.cpp picks.
+ *
+ * The text encoder never takes flash attention. ggml's CPU kernel sums the
+ * attention values in FP16, which a Qwen-family encoder overflows: FLUX.2
+ * klein on a Windows-on-ARM CPU rendered unrelated shapes with a 200
+ * (native-v0.1.53). It bites wherever the encoder lands on the CPU, and the
+ * encoder runs once per image, so GPUs lose nothing. `--diffusion-fa` means
+ * `--flash-attn off,diffusion=on`, so that branch already leaves it off.
+ */
+export function buildSdServerArgs(model, port) {
+    const args = [];
+    if (model.weightsKind === 'diffusion-model') {
+        args.push('--diffusion-model', model.weightsPath);
+    }
+    else {
+        args.push('--model', model.weightsPath);
+    }
+    for (const aux of model.auxiliaryFiles) {
+        args.push(`--${aux.role}`, aux.path);
+    }
+    const steps = MODEL_SAMPLE_STEP_DEFAULTS.get(model.id);
+    if (steps)
+        args.push('--steps', String(steps));
+    const profile = sdServerLoadProfile(model.id);
+    if (profile.diffusionFlashAttention)
+        args.push('--diffusion-fa');
+    else
+        args.push('--flash-attn', 'auto,te=off');
+    if (profile.bf16TensorPattern) {
+        args.push('--tensor-type-rules', `${profile.bf16TensorPattern}=bf16`);
+    }
+    if (profile.vaeDecode === 'tiled')
+        args.push('--vae-tiling');
+    if (profile.stepCache)
+        args.push('--cache-mode', profile.stepCache);
+    args.push('--listen-ip', '127.0.0.1', '--listen-port', String(port));
+    return args;
+}

package/dist/providers/image/mock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { ImageEngineHealth, ImageGenerationInput, ImageGenerationOutput, ImageModelPullEvent, ImageModelPullSpec, ImageProvider, InstalledImageModelInfo } from './types.js';
+export declare class MockImageProvider implements ImageProvider {
+    readonly name = "mock";
+    private readonly installed;
+    /** Internal counter driving deterministic seed generation on "random" seeds. */
+    private nextSeed;
+    constructor(opts?: {
+        preinstalled?: InstalledImageModelInfo[];
+    });
+    /** Number of input images received on the most recent generate(). Tests use this. */
+    lastInputImageCount: number;
+    generate(input: ImageGenerationInput): Promise<ImageGenerationOutput>;
+    listInstalledModels(): Promise<InstalledImageModelInfo[]>;
+    pullModel(id: string, spec: ImageModelPullSpec, signal?: AbortSignal): AsyncIterable<ImageModelPullEvent>;
+    deleteModel(id: string): Promise<void>;
+    health(): Promise<ImageEngineHealth>;
+}