@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/constrained-turn.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime runs the same loop; see core/src/local-loop.
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/deliverable-read-pacing.d.ts

@@ -0,0 +1 @@
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/deliverable-read-pacing.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime runs the same loop; see core/src/local-loop.
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/direct-file-work-prompt.d.ts

@@ -0,0 +1 @@
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/direct-file-work-prompt.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime runs the same loop; see core/src/local-loop.
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/ds4/build-provider.d.ts

@@ -0,0 +1,100 @@
+import { type GezelConfig } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import { Ds4Provider } from './provider.js';
+/**
+ * Default ds4 context window for the host's unified-memory tier.
+ *
+ * The old two-tier policy gave every machine below 192 GiB a 128K window.
+ * That was calibrated on DeepSeek V4's small resident core and was too
+ * aggressive for a 64 GiB Mac running Qwen3.8 Flash Next, whose main/MTP
+ * weights alone occupy about 42 GiB. Keep 64 GiB-class machines at 64K,
+ * while 96 GiB+ machines retain the measured 128K default.
+ */
+export declare function ds4RamTieredContext(totalRamBytes: number): number;
+/**
+ * Resolve ds4's launch `--ctx` from the device tier and the model's catalog
+ * cap.
+ *
+ * A high explicit `config.ds4NumCtx` wins. A lower value cannot push a
+ * long-context model below Gezel's viability floor (64K, or 32K on a
+ * memory-constrained host); a catalog model whose native launch cap is
+ * genuinely smaller retains that smaller cap. Otherwise the RAM tier is an
+ * upper bound that a model may lower but never raise — the tier is calibrated
+ * on DeepSeek V4 Flash's ~4 GiB of resident non-routed weights, and a model
+ * holding five times that much cannot afford the same KV allocation on the
+ * same machine.
+ */
+export declare function resolveDs4LaunchCtx(opts: {
+    configured?: number | undefined;
+    ramTieredCtx: number;
+    catalogMaxCtx?: number | undefined;
+    minViableContextTokens?: number | undefined;
+}): number;
+/**
+ * Resolve the one vision configuration the launch arguments, request wire
+ * shape, and turn-level capability gate must agree on.
+ *
+ * An explicit language-model path must never silently borrow an encoder from
+ * a catalog install: ds4 encoders are checkpoint-specific, and a mismatched
+ * pair is worse than an honest text-only launch. External servers own their
+ * argv, so Gezel cannot claim they support vision without a future capability
+ * handshake.
+ */
+export declare function resolveDs4VisionLaunch(opts: {
+    modelId?: string | undefined;
+    nativeVision?: Record<string, boolean> | undefined;
+    installedVisionEncoderPath?: string | undefined;
+    explicitModelPath?: string | undefined;
+    explicitVisionEncoderPath?: string | undefined;
+    externalBaseUrl?: string | undefined;
+}): {
+    visionEncoderPath?: string;
+    enabled: boolean;
+};
+/** Command-line fragment for the resolved ds4 vision state. */
+export declare function ds4VisionArgs(vision: {
+    visionEncoderPath?: string;
+    enabled: boolean;
+}): string[];
+/** Model-specific memory/graph flags that must stay aligned with residency policy. */
+export declare function ds4RuntimeArgs(opts: {
+    ssdStreaming: boolean;
+    cacheExpertsGb?: number | undefined;
+    prefillChunk?: number | undefined;
+}): string[];
+/**
+ * Build a ds4 (DwarfStar) provider. `ds4-server` is wire-compatible with
+ * `llama-server` (OpenAI `/v1/chat/completions` SSE), so this returns a
+ * {@link Ds4Provider} wrapping a {@link LlamaCppProvider} pointed at either an
+ * external ds4-server (`config.ds4BaseUrl` / `GEZEL_DS4_SERVER_URL`) or a
+ * supervised bundled `ds4-server` (`GEZEL_DS4_SERVER_BIN`).
+ *
+ * ds4 is not a general GGUF runner: it loads the specific DeepSeek V4/V4.1,
+ * GLM 5.2/5.3, and Qwen3.8 Flash Next quants its engine was built for,
+ * detecting the family at load time from the GGUF's `general.architecture`.
+ * Models reach the supervised path through the catalog's `ds4` source block,
+ * or an EXPLICIT GGUF via
+ * `config.ds4ModelPath` / `GEZEL_DS4_MODEL`. GPU-only: `--metal` on darwin,
+ * `--cuda` on linux (ds4's CPU path crashes the macOS kernel, so we never fall
+ * back to it). Readiness probes `GET /v1/models` because ds4 has no `/health`
+ * endpoint.
+ */
+export declare function buildDs4Provider(opts: {
+    config: GezelConfig;
+    affinity: boolean | undefined;
+    home: string;
+    /**
+     * ds4 GGUF store (a `LlamaCppModelManager` with engine:'ds4'). When set, the
+     * supervised path resolves the catalog modelId to an installed weights file
+     * — so the model picker's "install" flow works without a manual path.
+     */
+    ds4Models?: import('../llama-cpp/index.js').LlamaCppModelManager;
+    /** Catalog metadata drives the model-specific streaming cache and fit gate. */
+    catalog?: CatalogService;
+    modelOverride?: {
+        modelId: string;
+        replicaIdx: number;
+    };
+    broker?: import('../native/capacity-broker.js').CapacityBroker;
+    arbiter?: import('../gpu-arbiter.js').GpuArbiter;
+}): Promise<Ds4Provider>;

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

@@ -0,0 +1,539 @@
+import { basename, dirname, join } from 'node:path';
+import { DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS, createLogger, } from '@bendyline/gezel';
+import { gezelPaths } from '@bendyline/gezel/paths';
+import { LlamaCppProvider } from '../llama-cpp/index.js';
+import { minViableLocalContextTokens, pressureIdleGraceMs } from '../native/capacity-broker.js';
+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 { ds4MtpArgs, resolveDs4Mtp } from './mtp.js';
+import { Ds4Provider } from './provider.js';
+const log = createLogger('chat');
+/**
+ * Default ds4 context window for the host's unified-memory tier.
+ *
+ * The old two-tier policy gave every machine below 192 GiB a 128K window.
+ * That was calibrated on DeepSeek V4's small resident core and was too
+ * aggressive for a 64 GiB Mac running Qwen3.8 Flash Next, whose main/MTP
+ * weights alone occupy about 42 GiB. Keep 64 GiB-class machines at 64K,
+ * while 96 GiB+ machines retain the measured 128K default.
+ */
+export function ds4RamTieredContext(totalRamBytes) {
+    const totalRamGb = totalRamBytes / 1024 ** 3;
+    if (totalRamGb >= 192)
+        return 262_144;
+    if (totalRamGb >= 96)
+        return 131_072;
+    return 65_536;
+}
+/**
+ * Resolve ds4's launch `--ctx` from the device tier and the model's catalog
+ * cap.
+ *
+ * A high explicit `config.ds4NumCtx` wins. A lower value cannot push a
+ * long-context model below Gezel's viability floor (64K, or 32K on a
+ * memory-constrained host); a catalog model whose native launch cap is
+ * genuinely smaller retains that smaller cap. Otherwise the RAM tier is an
+ * upper bound that a model may lower but never raise — the tier is calibrated
+ * on DeepSeek V4 Flash's ~4 GiB of resident non-routed weights, and a model
+ * holding five times that much cannot afford the same KV allocation on the
+ * same machine.
+ */
+export function resolveDs4LaunchCtx(opts) {
+    const floor = opts.minViableContextTokens && opts.minViableContextTokens > 0
+        ? opts.minViableContextTokens
+        : minViableLocalContextTokens();
+    const resolved = opts.configured ??
+        (opts.catalogMaxCtx ? Math.min(opts.ramTieredCtx, opts.catalogMaxCtx) : opts.ramTieredCtx);
+    if (opts.catalogMaxCtx && opts.catalogMaxCtx < floor) {
+        return opts.catalogMaxCtx;
+    }
+    return Math.max(floor, resolved);
+}
+/**
+ * Resolve the one vision configuration the launch arguments, request wire
+ * shape, and turn-level capability gate must agree on.
+ *
+ * An explicit language-model path must never silently borrow an encoder from
+ * a catalog install: ds4 encoders are checkpoint-specific, and a mismatched
+ * pair is worse than an honest text-only launch. External servers own their
+ * argv, so Gezel cannot claim they support vision without a future capability
+ * handshake.
+ */
+export function resolveDs4VisionLaunch(opts) {
+    if (opts.externalBaseUrl)
+        return { enabled: false };
+    const visionEncoderPath = opts.explicitVisionEncoderPath ??
+        (opts.explicitModelPath ? undefined : opts.installedVisionEncoderPath);
+    const enabled = Boolean(visionEncoderPath) &&
+        (opts.modelId ? nativeVisionEnabledFor(opts.nativeVision, opts.modelId) : true);
+    return {
+        ...(visionEncoderPath ? { visionEncoderPath } : {}),
+        enabled,
+    };
+}
+/** Command-line fragment for the resolved ds4 vision state. */
+export function ds4VisionArgs(vision) {
+    return vision.enabled && vision.visionEncoderPath ? ['--vision', vision.visionEncoderPath] : [];
+}
+/** Model-specific memory/graph flags that must stay aligned with residency policy. */
+export function ds4RuntimeArgs(opts) {
+    const args = [];
+    if (opts.ssdStreaming) {
+        args.push('--ssd-streaming');
+        if (opts.cacheExpertsGb && opts.cacheExpertsGb > 0) {
+            args.push('--ssd-streaming-cache-experts', `${opts.cacheExpertsGb}GB`);
+        }
+    }
+    if (opts.prefillChunk)
+        args.push('--prefill-chunk', String(opts.prefillChunk));
+    return args;
+}
+/**
+ * Build a ds4 (DwarfStar) provider. `ds4-server` is wire-compatible with
+ * `llama-server` (OpenAI `/v1/chat/completions` SSE), so this returns a
+ * {@link Ds4Provider} wrapping a {@link LlamaCppProvider} pointed at either an
+ * external ds4-server (`config.ds4BaseUrl` / `GEZEL_DS4_SERVER_URL`) or a
+ * supervised bundled `ds4-server` (`GEZEL_DS4_SERVER_BIN`).
+ *
+ * ds4 is not a general GGUF runner: it loads the specific DeepSeek V4/V4.1,
+ * GLM 5.2/5.3, and Qwen3.8 Flash Next quants its engine was built for,
+ * detecting the family at load time from the GGUF's `general.architecture`.
+ * Models reach the supervised path through the catalog's `ds4` source block,
+ * or an EXPLICIT GGUF via
+ * `config.ds4ModelPath` / `GEZEL_DS4_MODEL`. GPU-only: `--metal` on darwin,
+ * `--cuda` on linux (ds4's CPU path crashes the macOS kernel, so we never fall
+ * back to it). Readiness probes `GET /v1/models` because ds4 has no `/health`
+ * endpoint.
+ */
+export async function buildDs4Provider(opts) {
+    const { config, affinity, home } = opts;
+    const defaultModelId = opts.modelOverride?.modelId ?? config.defaultModel?.ds4;
+    // ds4 models support ~1M context and SSD-STREAM their KV cache to disk, so
+    // the practical ceiling on a given box is RAM for the Metal context buffers
+    // (~0.75 GiB at 24K, scaling with ctx) — which share RAM with the expert
+    // cache. Scale ctx with device RAM, far above llama.cpp-class defaults to use
+    // the engine's headline strength, but bounded so buffers + expert cache still
+    // fit and the KV stays under ds4-server's ~4 GiB disk budget. A small window
+    // throws away exactly what ds4 is for and overflows on large specialist
+    // handoffs. (Full 1M needs a 128 GB+ box AND a raised ds4 --kv-disk-budget.)
+    //
+    // This tier assumes DeepSeek-V4's small resident footprint. A model whose
+    // non-routed weights are much larger caps it further via the catalog's
+    // `ds4.maxLaunchCtx`; see `resolveDs4LaunchCtx` below.
+    const totalRamBytes = (await import('node:os')).totalmem();
+    const totalRamGb = totalRamBytes / 1024 ** 3;
+    const ramTieredCtx = ds4RamTieredContext(totalRamBytes);
+    const ds4ConstrainedToolNoSignalMs = (() => {
+        const raw = process.env.GEZEL_DS4_CONSTRAINED_TOOL_NO_SIGNAL_MS;
+        if (raw) {
+            const parsed = Number.parseInt(raw, 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
+        return 600_000;
+    })();
+    const baseProviderOpts = {
+        fetchImpl: patientFetch(),
+        ...(defaultModelId ? { defaultModel: defaultModelId } : {}),
+        ...(affinity !== undefined ? { affinity } : {}),
+        // ds4-server emits per-turn token usage only when the request asks via
+        // stream_options.include_usage — opt in so usage/tok-s telemetry works.
+        includeUsageInStream: true,
+        // Reasoning is a per-request server control. Mirror Gezel's selected
+        // effort into both the OpenAI-compatible field and Qwen-style template
+        // kwargs; the standalone agent's launch-time control is intentionally not
+        // part of the server argv.
+        reasoningEffortRequestShape: 'ds4',
+        // ds4-server replays assistant turns as `<think>{reasoning_content}</think>`
+        // and keeps per-call DSML by tool-call id. Echoing the captured reasoning
+        // back keeps the re-rendered history byte-identical to what was generated,
+        // so the engine's live-KV prefix survives each tool iteration and a
+        // continuation prefills only the new tool results — instead of the
+        // `live kv cache miss … reason=token-mismatch` full-tail re-prefill
+        // (minutes per iteration at SSD-streamed prefill speeds). The env var is
+        // a no-rebuild kill switch while the replay path is field-tuned.
+        replayReasoningContent: process.env.GEZEL_DS4_NO_REASONING_REPLAY !== '1',
+        // DS4 prefill can exceed three minutes even on compact tool prompts when
+        // a continuation misses the live KV prefix and re-streams expert weights.
+        // Keep the constrained mutation watchdog active, but give the engine a
+        // model-appropriate prefill allowance. Override with
+        // GEZEL_DS4_CONSTRAINED_TOOL_NO_SIGNAL_MS.
+        constrainedToolNoSignalMs: ds4ConstrainedToolNoSignalMs,
+        // ds4-server is a hard singleton backed by an unusually large SSD-streamed
+        // model. Never overlap foreground and background generations: concurrent
+        // expert reads can saturate the SSD and make the whole workstation
+        // unresponsive even when the bounded resident cache itself fits.
+        concurrency: 1,
+        reserveBackgroundSlot: false,
+    };
+    // External ds4-server (dev iteration / LAN). Wins whenever set — a single
+    // external server already holds the model, so model resolution is moot.
+    // This is the path validated against a locally-run `ds4-server` while the
+    // bundled-binary vendoring (M2) lands.
+    const externalBaseUrl = process.env.GEZEL_DS4_SERVER_URL ?? config.ds4BaseUrl;
+    // Per-model context override (Settings → Local models → Context size…),
+    // more specific than the machine-wide ds4NumCtx.
+    const perModelCtxOverride = defaultModelId
+        ? config.modelContextOverrides?.[`ds4:${defaultModelId}`]
+        : undefined;
+    if (externalBaseUrl) {
+        return new Ds4Provider({
+            inner: new LlamaCppProvider({
+                baseUrl: externalBaseUrl,
+                disableThinkingRequestShape: 'deepseek',
+                // The external server owns its own `--ctx`; we only need a window to
+                // reason about pressure with, so the catalog cap can't apply here.
+                numCtx: perModelCtxOverride ?? config.ds4NumCtx ?? ramTieredCtx,
+                ...baseProviderOpts,
+            }),
+        });
+    }
+    // Supervised: bundled ds4-server binary (set by the Electron supervisor /
+    // eval harness once vendored).
+    const binary = process.env.GEZEL_DS4_SERVER_BIN;
+    if (!binary) {
+        const err = new Error('DwarfStar (ds4) engine: no ds4-server is available. Point Settings → DwarfStar (ds4) → External URL at a running ds4-server, or install a Gezel build that bundles ds4-server for this platform (Apple-Silicon Metal or Linux CUDA only).');
+        err.isActionable = true;
+        throw err;
+    }
+    // Model path: explicit env/config wins; otherwise resolve the catalog
+    // modelId through the ds4 GGUF store (installed via the model picker into
+    // `engines/ds4/models`). Mirrors buildLlamaCppProvider's precedence.
+    const explicitModelPath = process.env.GEZEL_DS4_MODEL ?? config.ds4ModelPath;
+    let modelPath = explicitModelPath;
+    let installedModel;
+    if (!modelPath && opts.ds4Models) {
+        if (defaultModelId) {
+            installedModel = await opts.ds4Models.resolveModel(defaultModelId);
+            if (installedModel)
+                modelPath = installedModel.weightsPath;
+        }
+        if (!modelPath && !opts.modelOverride) {
+            installedModel = await opts.ds4Models.resolveDefaultModel();
+            if (installedModel)
+                modelPath = installedModel.weightsPath;
+        }
+    }
+    if (!modelPath) {
+        const err = new Error(defaultModelId
+            ? `DwarfStar (ds4) engine: model "${defaultModelId}" isn't available locally yet — download it from Settings → DwarfStar (ds4), or set config.ds4ModelPath / GEZEL_DS4_MODEL to a GGUF DwarfStar supports.`
+            : 'DwarfStar (ds4) engine: no DwarfStar model is available locally — download one from Settings → DwarfStar (ds4), or set config.ds4ModelPath / GEZEL_DS4_MODEL. DwarfStar is not a general GGUF runner; it runs the specific DeepSeek-V4 and GLM 5.2/5.3 builds its engine supports.');
+        err.isActionable = true;
+        throw err;
+    }
+    // GPU backend: Metal on Apple Silicon, CUDA on Linux. ds4's CPU path
+    // crashes the macOS kernel, so it is never selected on darwin.
+    const backendFlag = process.platform === 'darwin' ? '--metal' : '--cuda';
+    const effectiveModelId = defaultModelId ?? installedModel?.id;
+    const vision = resolveDs4VisionLaunch({
+        ...(effectiveModelId ? { modelId: effectiveModelId } : {}),
+        ...(config.nativeVision ? { nativeVision: config.nativeVision } : {}),
+        ...(installedModel?.visionEncoderPath
+            ? { installedVisionEncoderPath: installedModel.visionEncoderPath }
+            : {}),
+        ...(explicitModelPath ? { explicitModelPath } : {}),
+        ...((process.env.GEZEL_DS4_VISION_ENCODER ?? config.ds4VisionEncoderPath)
+            ? {
+                explicitVisionEncoderPath: process.env.GEZEL_DS4_VISION_ENCODER ?? config.ds4VisionEncoderPath,
+            }
+            : {}),
+    });
+    const catalogDetail = effectiveModelId
+        ? await opts.catalog?.get('chat-model', effectiveModelId).catch(() => null)
+        : null;
+    const ds4Source = catalogDetail?.manifest.kind === 'chat-model' ? catalogDetail.manifest.ds4 : undefined;
+    let modelSizeBytes = installedModel?.approxSizeBytes ?? ds4Source?.approxSizeBytes;
+    if (!modelSizeBytes) {
+        const { stat: statDs4Model } = await import('node:fs/promises');
+        modelSizeBytes = await statDs4Model(modelPath)
+            .then((st) => st.size)
+            .catch(() => undefined);
+    }
+    // Some ds4 GGUFs deliberately contain very large tables that never become
+    // resident: Qwen3.8 n-grams and DeepSeek V4.1 Engrams are read row-wise from
+    // disk in every mode. Charge the full-residency gate only for the weights
+    // that can actually enter RAM; older catalog entries fall back to file size.
+    const residentWeightBytes = ds4Source?.residentWeightBytes ?? modelSizeBytes;
+    // The supervised launch may resolve its model by scanning installed models
+    // (resolveDefaultModel above), so re-read the override against the id that
+    // actually launches when the config carried none.
+    const launchCtxOverride = perModelCtxOverride ??
+        (effectiveModelId ? config.modelContextOverrides?.[`ds4:${effectiveModelId}`] : undefined);
+    // An override below the host floor is deliberate user intent — lower the
+    // floor to the override instead of raising the request back to 64K.
+    const ds4Floor = launchCtxOverride !== undefined
+        ? Math.min(minViableLocalContextTokens(), launchCtxOverride)
+        : minViableLocalContextTokens();
+    const numCtx = resolveDs4LaunchCtx({
+        configured: launchCtxOverride ?? config.ds4NumCtx,
+        ramTieredCtx,
+        catalogMaxCtx: ds4Source?.maxLaunchCtx,
+        minViableContextTokens: ds4Floor,
+    });
+    if (numCtx !== (launchCtxOverride ?? config.ds4NumCtx ?? ramTieredCtx)) {
+        log.info(`[ds4] ${effectiveModelId ?? basename(modelPath)} caps launch context at ${numCtx} ` +
+            `(device tier would allow ${ramTieredCtx})`);
+    }
+    // Residency is the default wherever the model fits — streaming costs roughly
+    // an order of magnitude (1.85 vs 18.1 tok/s measured on the same IQ2_XXS
+    // build). `shouldUseDs4SsdStreaming` still refuses a model that cannot fit,
+    // which is what keeps the flip safe: overriding that on a 90.89 GiB build
+    // OOM-killed the engine mid-load on a 121.63 GiB host.
+    const { ds4VisionResidentBytes, planDs4ExpertCache, shouldUseDs4SsdStreaming } = await import('./residency.js');
+    let visionEncoderSizeBytes = installedModel?.visionEncoderSizeBytes;
+    if (vision.enabled && vision.visionEncoderPath && !visionEncoderSizeBytes) {
+        const { stat: statVisionEncoder } = await import('node:fs/promises');
+        visionEncoderSizeBytes = await statVisionEncoder(vision.visionEncoderPath)
+            .then((st) => st.size)
+            .catch(() => undefined);
+    }
+    const visionResidentBytes = ds4VisionResidentBytes(vision.enabled ? visionEncoderSizeBytes : undefined);
+    const ssdStreaming = shouldUseDs4SsdStreaming({
+        configured: config.ds4SsdStreaming,
+        ...(ds4Source?.ssdStreamingSupported !== undefined
+            ? { ssdStreamingSupported: ds4Source.ssdStreamingSupported }
+            : {}),
+        modelSizeBytes: residentWeightBytes,
+        totalRamBytes,
+        ...(visionResidentBytes > 0 ? { companionBytes: visionResidentBytes } : {}),
+    });
+    if (config.ds4SsdStreaming === false && ssdStreaming) {
+        log.warn(`[ds4] ignored unsafe full-residency override for ${effectiveModelId ?? modelPath}; ` +
+            `model=${modelSizeBytes ?? 'unknown'} bytes, system=${Math.round(totalRamGb)} GiB`);
+    }
+    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`);
+    }
+    // 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.
+    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.
+    let companionFitsMemory = true;
+    let dsparkCompanionBytes = 0;
+    if (dsparkSupportPath && !ssdStreaming) {
+        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 }
+                : {}),
+        });
+    }
+    const dspark = resolveDs4Dspark({
+        mode: config.ds4Dspark,
+        backend: backendFlag.slice(2),
+        ssdStreaming,
+        companionFitsMemory,
+        ...(dsparkSupportPath ? { supportModelPath: dsparkSupportPath } : {}),
+    });
+    if (dspark.unmetRequest)
+        log.warn(`[ds4] ${dspark.unmetRequest}`);
+    // Model-embedded MTP (Qwen3.8 / GLM 5.3) is independent of DSpark's
+    // external support GGUF. `auto` requires an explicit catalog capability so
+    // older or hand-supplied models never receive a flag they may reject.
+    const mtpMode = (() => {
+        const raw = process.env.GEZEL_DS4_MTP;
+        return raw === 'off' || raw === 'on' || raw === 'auto' ? raw : config.ds4Mtp;
+    })();
+    const mtpExactSampling = (() => {
+        const raw = process.env.GEZEL_DS4_MTP_EXACT_SAMPLING;
+        if (raw === '1' || raw === 'true')
+            return true;
+        if (raw === '0' || raw === 'false')
+            return false;
+        return config.ds4MtpExactSampling;
+    })();
+    const mtp = resolveDs4Mtp({
+        mode: mtpMode,
+        ...(ds4Source?.mtp ? { catalog: ds4Source.mtp } : {}),
+        ...(mtpExactSampling !== undefined ? { exactSampling: mtpExactSampling } : {}),
+        dsparkEnabled: dspark.enabled,
+    });
+    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,
+    });
+    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;
+        throw err;
+    }
+    if (cachePlan.clamped) {
+        log.warn(`[ds4] clamped expert cache ${cachePlan.requestedGb} → ${cachePlan.cacheGb} GiB to preserve system headroom`);
+    }
+    const cacheExpertsGb = cachePlan.cacheGb;
+    const kvDir = join(home, 'engines', 'ds4', 'kv');
+    const { mkdir: mkdirDs4 } = await import('node:fs/promises');
+    await mkdirDs4(kvDir, { recursive: true }).catch(() => { });
+    // ds4-server compiles its Metal shaders from `./metal/*.metal` resolved
+    // relative to its working directory (each source is only overridable by a
+    // separate env var — cwd is the clean lever). build.sh stages `metal/` next
+    // to the binary, and the dev/external `GEZEL_DS4_SERVER_BIN` points at the
+    // ds4 checkout which also has `metal/`, so cwd = the binary's directory.
+    // Without this, startup aborts with "metal backend unavailable".
+    const { dirname: ds4Dirname } = await import('node:path');
+    const ds4BundleDir = process.env.GEZEL_DS4_CWD ?? ds4Dirname(binary);
+    // Cold mmap of an 87GB GGUF + first-run Metal shader compile is minutes,
+    // not seconds. Default 10 min; env-overridable for slow cold SSD reads.
+    const startupTimeoutMs = (() => {
+        const env = process.env.GEZEL_DS4_STARTUP_TIMEOUT_MS;
+        if (env) {
+            const n = Number.parseInt(env, 10);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        return 600_000;
+    })();
+    const idleMs = config.localEngineIdleTimeoutMs ?? DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS;
+    // Persist DS4 stdout/stderr independently from llama.cpp. Dev embedded mode
+    // has no service-*.log capture, so without this file a force-quit erases the
+    // only evidence of model loading, cache sizing, or a native-engine failure.
+    const { LlamaCppLogFile: Ds4LogFile } = await import('../llama-cpp/log.js');
+    const ds4LogFile = new Ds4LogFile(gezelPaths(home).logs, 'ds4-server');
+    // Same holder pattern as buildLlamaCppProvider: the supervisor is
+    // constructed before the provider, so onRawLine closes over a ref that's
+    // filled in below. Routing stderr through onStdoutLine (with the ds4
+    // classifier) is what turns ds4's prefill-chunk / decode / page-warming
+    // lines into live engine_phase progress in the chat — without it a
+    // multi-minute DS4 prefill is a silent spinner.
+    const ds4ProviderHolder = { current: null };
+    const { classifyDs4Line } = await import('./stdout-parser.js');
+    let cachedDs4Port;
+    const supervisor = new NativeEngineSupervisor({
+        capacity: {
+            home,
+            priority: () => (ds4ProviderHolder.current?.queue.describe().runningInteractive ?? 0) > 0
+                ? 'interactive'
+                : 'background',
+            requirement: async () => {
+                const { ds4AdmissionGpuBytes, ds4BaseResidentBytes, ds4ResidentLine, ds4ProjectedResidentBytes, ds4ResidentBytesForMode, } = await import('./residency.js');
+                const line = ds4ResidentLine(ds4Source ?? {});
+                const projected = line ? ds4ProjectedResidentBytes(line, numCtx) : ds4Source?.residentBytes;
+                const base = ssdStreaming
+                    ? Math.max(0, (projected ?? 8 * 1024 ** 3) - (ds4Source?.cacheExpertsBytes ?? 0)) +
+                        cacheExpertsGb * 1024 ** 3
+                    : ds4BaseResidentBytes({
+                        projectedBytes: projected,
+                        modelSizeBytes: residentWeightBytes,
+                    });
+                const workingSetBytes = base + visionResidentBytes + (dspark.enabled ? dsparkCompanionBytes : 0);
+                const bytes = ds4ResidentBytesForMode(workingSetBytes, ssdStreaming, ds4Source?.ssdStreamingSupported);
+                const gpuBytes = ds4AdmissionGpuBytes({
+                    workingSetBytes,
+                    reservationBytes: bytes,
+                    kvBytesPerToken: ds4Source?.kvBytesPerToken,
+                    numCtx,
+                });
+                return {
+                    bytes,
+                    ...(gpuBytes !== undefined ? { gpuBytes } : {}),
+                    exclusive: !ssdStreaming,
+                };
+            },
+        },
+        logPrefix: '[ds4-server]',
+        startupTimeoutMs,
+        idleTimeoutMs: idleMs,
+        isBusy: () => ds4ProviderHolder.current?.isEngineBusy() ?? false,
+        ...(opts.arbiter
+            ? {
+                memoryPressure: () => opts.arbiter.getMemoryPressureStatus(),
+                pressureIdleTimeoutMs: pressureIdleGraceMs(),
+            }
+            : {}),
+        // ds4 exposes no /health — a 200 on /v1/models is the readiness signal.
+        readinessPath: '/v1/models',
+        onLog: (line) => {
+            log.info(line);
+            ds4LogFile.write(line);
+        },
+        onRawLine: (line) => ds4ProviderHolder.current?.onStdoutLine(line),
+        resolveLaunch: async () => {
+            const port = cachedDs4Port ?? (await pickFreePort());
+            cachedDs4Port = port;
+            const args = [
+                '--model',
+                modelPath,
+                backendFlag,
+                '--ctx',
+                String(numCtx),
+                '--host',
+                '127.0.0.1',
+                '--port',
+                String(port),
+                '--kv-disk-dir',
+                kvDir,
+                // ds4-server's default disk budget is 4096 MiB — about 7 large
+                // (40k-token ≈ 540 MiB) session chunks, which a busy multi-session
+                // install churns through in minutes and the LRU then evicts the
+                // very chunk a resumed session needs. Disk is the cheap resource
+                // here; 16 GiB keeps ~30 large chunks live. Override with
+                // GEZEL_DS4_KV_DISK_MB.
+                '--kv-disk-space-mb',
+                String((() => {
+                    const raw = process.env.GEZEL_DS4_KV_DISK_MB;
+                    if (raw) {
+                        const parsed = Number.parseInt(raw, 10);
+                        if (Number.isFinite(parsed) && parsed > 0)
+                            return parsed;
+                    }
+                    return 16_384;
+                })()),
+                // NOT `--cors`. ds4 leaves Access-Control-Allow-* headers OFF by
+                // default and that flag opts into them, which would let any web page
+                // the user has open drive this engine and read the answer, given the
+                // port. Nothing in Gezel needs it: the daemon talks to the engine
+                // server-side, where CORS — a browser policy — does not apply.
+            ];
+            args.push(...ds4RuntimeArgs({
+                ssdStreaming,
+                cacheExpertsGb,
+                ...(ds4Source?.prefillChunk ? { prefillChunk: ds4Source.prefillChunk } : {}),
+            }));
+            args.push(...ds4VisionArgs(vision));
+            args.push(...ds4MtpArgs(mtp));
+            args.push(...ds4DsparkArgs(dspark));
+            // Record the effective safety policy before spawn. ds4-server's own
+            // stdout does not reliably echo its argv, and a hard lockup/force-quit
+            // otherwise leaves no way to tell whether streaming was actually on.
+            ds4LogFile.write(`[ds4-server] launch model=${effectiveModelId ?? basename(modelPath)} ` +
+                `sizeGiB=${modelSizeBytes ? (modelSizeBytes / 1024 ** 3).toFixed(1) : 'unknown'} ` +
+                `backend=${backendFlag.slice(2)} ctx=${numCtx} ` +
+                `prefillChunk=${ds4Source?.prefillChunk ?? 'engine-default'} ` +
+                `ssdStreaming=${ssdStreaming} cacheExpertsGiB=${ssdStreaming ? cacheExpertsGb : 0} ` +
+                `vision=${vision.enabled} mtp=${mtp.enabled} exactSampling=${mtp.exactSampling} (${mtp.reason}) ` +
+                `dspark=${dspark.enabled} (${dspark.reason})`);
+            return { command: binary, args, baseUrl: `http://127.0.0.1:${port}`, cwd: ds4BundleDir };
+        },
+    });
+    const ds4Inner = new LlamaCppProvider({
+        supervisor,
+        logFile: ds4LogFile,
+        disableThinkingRequestShape: 'deepseek',
+        classifyLine: classifyDs4Line,
+        visionEnabled: vision.enabled,
+        ...baseProviderOpts,
+    });
+    ds4ProviderHolder.current = ds4Inner;
+    return new Ds4Provider({ inner: ds4Inner });
+}