@bendyline/gezel-inference 1.0.2 → 1.0.4

package/dist/perf/responsiveness.js

@@ -8,9 +8,10 @@ import { redactPathSecrets } from './redact-path.js';
 /**
  * Main-thread responsiveness monitor.
  *
- * The daemon runs on one event loop. In embedded mode (`pnpm app`, and the
- * packaged fallback) that loop is Electron's main thread, so a synchronous
- * block here freezes the window itself, and Windows labels it "Not Responding"
+ * The daemon runs on one event loop. With an in-process embedded service (the
+ * packaged fallback, E2E, `GEZEL_SERVICE_HOST=in-process`) that loop is
+ * Electron's main thread, so a synchronous block here freezes the window
+ * itself, and Windows labels it "Not Responding"
  * after 5 s. Before this existed a block under the suspend monitor's 10 s floor
  * left no trace, and a longer one was logged as "host resumed after Ns
  * suspended": sleep that never happened (two of them during one catalog

package/dist/providers/audio/kokoro-frontend.js

@@ -75,7 +75,7 @@ export class KokoroFrontend {
                 // put it back, because a packaging slip is the likely cause.
                 throw new Error(`Kokoro pronunciation dictionary is missing at ${file}; rebuild the service (node scripts/build-kokoro-lexicon.mjs stages it).`, { cause });
             }
-            return parseKokoroLexicon(gunzipSync(packed).toString('utf8'));
+            return parseKokoroLexicon(gunzipSync(packed).toString('utf8'), { language });
         })();
         // A failed read must not be cached as a permanent failure.
         void pending.catch(() => this.loaded.delete(language));

package/dist/providers/ds4/build-provider.js

@@ -7,7 +7,7 @@ import { pickFreePort } from '../native/port.js';
 import { NativeEngineSupervisor } from '../native/supervisor.js';
 import { patientFetch } from '../patient-fetch.js';
 import { nativeVisionEnabledFor } from '../vision-capability.js';
-import { ds4DsparkArgs, resolveDs4Dspark } from './dspark.js';
+import { DS4_V41_DRAFTER_RUNTIME_BYTES, ds4DsparkArgs, ds4DsparkStreamsWithSsd, resolveDs4Dspark, } from './dspark.js';
 import { ds4MtpArgs, resolveDs4Mtp } from './mtp.js';
 import { Ds4Provider } from './provider.js';
 const log = createLogger('chat');
@@ -307,36 +307,50 @@ export async function buildDs4Provider(opts) {
     if (config.ds4SsdStreaming === true && ds4Source?.ssdStreamingSupported === false) {
         log.warn(`[ds4] ignored SSD-streaming override for ${effectiveModelId ?? modelPath}; this model keeps its lookup tables on disk but does not implement routed-expert streaming`);
     }
+    const cachePlanWith = (extraResidentBytes) => planDs4ExpertCache({
+        configuredGb: config.ds4CacheExpertsGb,
+        catalogCacheBytes: ds4Source?.cacheExpertsBytes,
+        catalogResidentBytes: (ds4Source?.residentBytes ?? 0) + visionResidentBytes + extraResidentBytes,
+        totalRamBytes: totalRamGb * 1024 ** 3,
+    });
     // DSpark speculative decoding. Resolved here, beside the residency decision
-    // it depends on: ds4 aborts at startup if an external `--mtp-model` is combined with
-    // `--ssd-streaming`, so this can only ever draft on a fully resident launch.
+    // it depends on: ds4 aborts at startup if an external `--mtp-model` is
+    // combined with `--ssd-streaming` for any family but DeepSeek V4.1.
+    const targetArchitecture = installedModel?.architecture;
+    const streamedDrafting = ssdStreaming && ds4DsparkStreamsWithSsd(targetArchitecture);
     const dsparkSupportPath = config.ds4DsparkModelPath ?? installedModel?.draftModelPath;
     // Residency is decided on the weights alone, then the companion is priced
     // against what is left. That precedence is deliberate and not symmetric:
     // residency is worth ~9.5x and drafting ~1.05x, so a companion that would
     // push the model out of memory loses its own flag rather than costing the
-    // launch its residency.
+    // launch its residency. A streamed V4.1 launch keeps its drafter resident
+    // too, so it must still leave room for a minimum expert cache.
     let companionFitsMemory = true;
     let dsparkCompanionBytes = 0;
-    if (dsparkSupportPath && !ssdStreaming) {
+    if (dsparkSupportPath && (!ssdStreaming || streamedDrafting)) {
         const { canUseDs4FullResidency } = await import('./residency.js');
         const { stat: statCompanion } = await import('node:fs/promises');
         const companionBytes = await statCompanion(dsparkSupportPath)
             .then((st) => st.size)
             .catch(() => undefined);
-        dsparkCompanionBytes = companionBytes ?? 0;
-        companionFitsMemory = canUseDs4FullResidency({
-            modelSizeBytes: residentWeightBytes,
-            totalRamBytes,
-            ...(companionBytes !== undefined || visionResidentBytes > 0
-                ? { companionBytes: (companionBytes ?? 0) + visionResidentBytes }
-                : {}),
-        });
+        dsparkCompanionBytes =
+            (companionBytes ?? 0) +
+                (ds4DsparkStreamsWithSsd(targetArchitecture) ? DS4_V41_DRAFTER_RUNTIME_BYTES : 0);
+        companionFitsMemory = ssdStreaming
+            ? cachePlanWith(dsparkCompanionBytes).safe
+            : canUseDs4FullResidency({
+                modelSizeBytes: residentWeightBytes,
+                totalRamBytes,
+                ...(companionBytes !== undefined || visionResidentBytes > 0
+                    ? { companionBytes: dsparkCompanionBytes + visionResidentBytes }
+                    : {}),
+            });
     }
     const dspark = resolveDs4Dspark({
         mode: config.ds4Dspark,
         backend: backendFlag.slice(2),
         ssdStreaming,
+        ...(targetArchitecture ? { targetArchitecture } : {}),
         companionFitsMemory,
         ...(dsparkSupportPath ? { supportModelPath: dsparkSupportPath } : {}),
     });
@@ -365,14 +379,7 @@ export async function buildDs4Provider(opts) {
     });
     if (mtp.unmetRequest)
         log.warn(`[ds4] ${mtp.unmetRequest}`);
-    const cachePlan = planDs4ExpertCache({
-        configuredGb: config.ds4CacheExpertsGb,
-        catalogCacheBytes: ds4Source?.cacheExpertsBytes,
-        catalogResidentBytes: ds4Source?.residentBytes !== undefined || visionResidentBytes > 0
-            ? (ds4Source?.residentBytes ?? 0) + visionResidentBytes
-            : undefined,
-        totalRamBytes: totalRamGb * 1024 ** 3,
-    });
+    const cachePlan = cachePlanWith(dspark.enabled && ssdStreaming ? dsparkCompanionBytes : 0);
     if (ssdStreaming && !cachePlan.safe) {
         const err = new Error(`DwarfStar (ds4) engine: ${effectiveModelId ?? 'the selected model'} cannot keep a safe minimum expert cache while preserving memory for the operating system. Choose a lighter model in Settings → DwarfStar (ds4).`);
         err.isActionable = true;
@@ -526,12 +533,18 @@ export async function buildDs4Provider(opts) {
             return { command: binary, args, baseUrl: `http://127.0.0.1:${port}`, cwd: ds4BundleDir };
         },
     });
+    // Sessions budget prompts, `max_tokens`, and compaction against this window,
+    // so it must be the `--ctx` ds4 actually launches with. Left unset, it fell
+    // back to the 64K llama default: GLM 5.3 (launched at 32K) overflowed with
+    // `context_length_exceeded` long before compaction triggered, and DeepSeek
+    // (launched at 128K) compacted at a third of its window.
     const ds4Inner = new LlamaCppProvider({
         supervisor,
         logFile: ds4LogFile,
         disableThinkingRequestShape: 'deepseek',
         classifyLine: classifyDs4Line,
         visionEnabled: vision.enabled,
+        numCtx,
         ...baseProviderOpts,
     });
     ds4ProviderHolder.current = ds4Inner;

package/dist/providers/ds4/dspark.d.ts

@@ -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
@@ -25,6 +28,18 @@
  */
 /** Which acceleration backend ds4 was launched with. */
 export type Ds4Backend = 'metal' | 'cuda';
+/**
+ * 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 declare function ds4DsparkStreamsWithSsd(architecture: string | undefined): boolean;
+/**
+ * Buffers ds4 allocates beside a V4.1 drafter's weights; its startup memory
+ * plan charges `mtp_model.size + 64 MiB` for them.
+ */
+export declare const DS4_V41_DRAFTER_RUNTIME_BYTES: number;
 export type Ds4DsparkMode = 'off' | 'on' | 'auto';
 export interface Ds4DsparkOptions {
     /** `config.ds4Dspark`. Absent → `auto`. */
@@ -33,12 +48,15 @@ export interface Ds4DsparkOptions {
     backend: Ds4Backend;
     /** Whether this launch streams experts from SSD. */
     ssdStreaming: boolean;
+    /** The target GGUF's `general.architecture`, when known. */
+    targetArchitecture?: string;
     /** Absolute path to a DSpark support GGUF, if one resolved. */
     supportModelPath?: string;
     /**
-     * Whether the companion still fits once the resident weights are accounted
+     * Whether the companion still fits once the resident weights (or, when
+     * streaming, the resident set plus a minimum expert cache) are accounted
      * for. Defaults to true so callers that cannot weigh it keep the old
-     * behavior. When false the launch keeps its residency and drops drafting —
+     * behavior. When false the launch keeps its memory plan and drops drafting —
      * residency is worth ~9.5x and drafting ~1.05x, so the flag is what yields.
      */
     companionFitsMemory?: boolean;

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[];