@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/ds4/cache-adapter.d.ts

@@ -0,0 +1,42 @@
+import type { CacheWarmMessage, EngineCacheAdapter, EngineCacheUsage } from '../../cache/adapter.js';
+export interface Ds4CacheAdapterOptions {
+    /** Live base URL of the ds4-server process, or null when not running. */
+    resolveBaseUrl: () => Promise<string | null> | string | null;
+    /**
+     * True when the engine has anything running or queued. Warms are
+     * strictly lower priority than real work on the single ds4 lane and
+     * skip rather than contend.
+     */
+    isBusy: () => boolean;
+    /**
+     * Run a prefill-only request through the session's own request
+     * assembly (ChatManager: `ensureState` → `session.prefillOnly()`).
+     * Returns false when the session doesn't exist or its provider
+     * session can't prefill; throws on engine errors.
+     */
+    prefillSession: (sessionId: string) => Promise<boolean>;
+}
+export declare class Ds4CacheAdapter implements EngineCacheAdapter {
+    readonly providerName = "ds4";
+    /**
+     * The warm renders the full prompt from live session state — an
+     * empty transcript still warms the (dominant, ~35k-token on a
+     * meester) `[system][tools]` block. `prewarmSession` reads this to
+     * skip its empty-transcript early-return.
+     */
+    readonly warmsFromSessionState = true;
+    private readonly opts;
+    /** Session id of the warm currently in flight, if any. */
+    private warmInFlight;
+    constructor(opts: Ds4CacheAdapterOptions);
+    /** ds4-server keys KV by token text internally — nothing to attach. */
+    buildRequestExtras(_sessionId: string): Record<string, unknown>;
+    /** No per-session eviction API; the engine LRUs its own disk budget. */
+    evict(_sessionIds: readonly string[]): Promise<void>;
+    /** No inspection API — the controller treats ds4 cache as opaque. */
+    reportUsage(): Promise<readonly EngineCacheUsage[]>;
+    /** `_messages` is unused: the prompt is rendered from live session
+     * state (see {@link warmsFromSessionState}); a raw transcript can
+     * never reproduce the real turn's token prefix. */
+    warm(sessionId: string, _messages: readonly CacheWarmMessage[]): Promise<void>;
+}

package/dist/providers/ds4/cache-adapter.js

@@ -0,0 +1,110 @@
+/**
+ * ds4 (DwarfStar) `EngineCacheAdapter`.
+ *
+ * ds4-server manages its own KV persistence internally: it keys live and
+ * on-disk KV snapshots by token-text hash (`--kv-disk-dir`, LRU'd under
+ * `--kv-disk-space-mb`) and restores on prefix match without any
+ * client-visible handle. That inverts the shape of the other adapters:
+ *
+ *   - There is NO `cache_id`/slot to attach per request —
+ *     {@link buildRequestExtras} is empty.
+ *   - There is NO per-session eviction or inspection API — the engine
+ *     can't map a sessionId to its token-text keys, so `evict()` is a
+ *     best-effort no-op and `reportUsage()` reports nothing (both
+ *     explicitly allowed by the contract).
+ *
+ * What the adapter DOES contribute is {@link warm}: run the next real
+ * turn's prefill early, while the user is still reading/thinking (the
+ * UI fires `POST /api/cache/warm` whenever a session gains focus). On a
+ * 284B SSD-streamed model a cold conversation prefill takes minutes;
+ * warming converts that wait into background work — the real turn then
+ * lands on hot live KV or a disk prefix hit.
+ *
+ * CRITICAL: the warm request must be BYTE-IDENTICAL to the prefix of
+ * the next real request — ds4 KV is prefix-keyed from token 0, so a
+ * warm that renders the prompt even slightly differently (missing
+ * system block, missing tool schemas, different reasoning replay)
+ * stores a key no real turn can ever hit AND pollutes the disk-KV LRU
+ * with a junk chunk. That is why `warm` does NOT build a request from
+ * the raw transcript: it delegates to {@link Ds4CacheAdapterOptions.prefillSession},
+ * which routes through the live session's own request assembly
+ * (`LlamaCppSession.prefillOnly`) — the same wire-message transforms,
+ * tool schemas, and tuning the real turn will use.
+ *
+ * Safety: ds4 runs a single request lane (`concurrency: 1`, no
+ * background slot — foreground and background generations must never
+ * overlap). A warm therefore SKIPS entirely when anything is running or
+ * queued, and at most one warm is in flight at a time. If the user
+ * sends a real turn while a warm is mid-prefill, the engine serializes
+ * it behind the warm — near-lossless, because the warm's prefill IS the
+ * turn's prefill (same token prefix, so the turn resumes from the
+ * warmed KV).
+ */
+import { createLogger } from '@bendyline/gezel';
+const log = createLogger('ds4-cache');
+export class Ds4CacheAdapter {
+    providerName = 'ds4';
+    /**
+     * The warm renders the full prompt from live session state — an
+     * empty transcript still warms the (dominant, ~35k-token on a
+     * meester) `[system][tools]` block. `prewarmSession` reads this to
+     * skip its empty-transcript early-return.
+     */
+    warmsFromSessionState = true;
+    opts;
+    /** Session id of the warm currently in flight, if any. */
+    warmInFlight = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** ds4-server keys KV by token text internally — nothing to attach. */
+    buildRequestExtras(_sessionId) {
+        return {};
+    }
+    /** No per-session eviction API; the engine LRUs its own disk budget. */
+    async evict(_sessionIds) { }
+    /** No inspection API — the controller treats ds4 cache as opaque. */
+    async reportUsage() {
+        return [];
+    }
+    /** `_messages` is unused: the prompt is rendered from live session
+     * state (see {@link warmsFromSessionState}); a raw transcript can
+     * never reproduce the real turn's token prefix. */
+    async warm(sessionId, _messages) {
+        if (this.warmInFlight) {
+            log.debug(`warm skipped for ${sessionId.slice(0, 8)} — warm already in flight`);
+            return;
+        }
+        if (this.opts.isBusy()) {
+            log.debug(`warm skipped for ${sessionId.slice(0, 8)} — engine busy`);
+            return;
+        }
+        // Claim the in-flight guard SYNCHRONOUSLY — before any await — so two
+        // near-simultaneous warms can't both slip past the check above.
+        this.warmInFlight = sessionId;
+        const t0 = Date.now();
+        try {
+            const baseUrl = await this.opts.resolveBaseUrl();
+            if (!baseUrl) {
+                // Engine not resident. Deliberately do NOT spawn it here — focusing
+                // a session must never trigger a multi-minute 284B model load (the
+                // user may just be browsing). Warm only accelerates an engine that
+                // is already up.
+                log.debug(`warm skipped for ${sessionId.slice(0, 8)} — engine not running`);
+                return;
+            }
+            const ran = await this.opts.prefillSession(sessionId);
+            if (!ran) {
+                log.debug(`warm skipped for ${sessionId.slice(0, 8)} — session cannot prefill`);
+                return;
+            }
+            log.info(`warmed session ${sessionId.slice(0, 8)} in ${Date.now() - t0}ms`);
+        }
+        catch (err) {
+            log.warn(`warm for ${sessionId.slice(0, 8)} failed after ${Date.now() - t0}ms:`, err instanceof Error ? err.message : err);
+        }
+        finally {
+            this.warmInFlight = null;
+        }
+    }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * DSpark speculative decoding for ds4 (`--dspark --mtp-model <support.gguf>`).
+ *
+ * ds4 can draft several tokens ahead with a small companion GGUF and verify
+ * them against the target model in one batched pass. Two hard constraints and
+ * 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.
+ *  - **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
+ *    Flash IQ2_XXS at full residency, seed-pinned A/B/C/A: baseline 38.4 tok/s
+ *    against 38.5 opportunistic and 36.7 exact, with ds4's own
+ *    `DS4_DSPARK_STATS` reporting net_saved of -1301 ms and -1038 ms. Verifying
+ *    a 5-token block through a 284B MoE costs more than the single-token
+ *    decodes it skips.
+ *
+ * Hence `auto` keys on the **backend**, not on unified memory: Apple Silicon
+ * reports `gpuMemoryKind: 'unified'` exactly as GB10 does, so a
+ * residency-or-unified predicate would enable drafting on the one platform
+ * where it was measured to lose.
+ */
+/** Which acceleration backend ds4 was launched with. */
+export type Ds4Backend = 'metal' | 'cuda';
+export type Ds4DsparkMode = 'off' | 'on' | 'auto';
+export interface Ds4DsparkOptions {
+    /** `config.ds4Dspark`. Absent → `auto`. */
+    mode?: Ds4DsparkMode;
+    /** Resolved backend for this launch. */
+    backend: Ds4Backend;
+    /** Whether this launch streams experts from SSD. */
+    ssdStreaming: boolean;
+    /** Absolute path to a DSpark support GGUF, if one resolved. */
+    supportModelPath?: string;
+    /**
+     * Whether the companion still fits once the resident weights 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 —
+     * residency is worth ~9.5x and drafting ~1.05x, so the flag is what yields.
+     */
+    companionFitsMemory?: boolean;
+}
+export interface Ds4DsparkDecision {
+    enabled: boolean;
+    /** Support model to pass to `--mtp-model`. Only set when {@link enabled}. */
+    supportModelPath?: string;
+    /**
+     * Why drafting is on or off, in launch-log voice. Always populated: a
+     * silently absent flag is indistinguishable from one the engine rejected,
+     * and this is the only record of which branch ran.
+     */
+    reason: string;
+    /**
+     * Set when the user explicitly asked for `on` and it could not be honored.
+     * The caller surfaces this as a warning — it must not be swallowed, because
+     * the alternative to reporting it is a user who believes they are drafting.
+     */
+    unmetRequest?: string;
+}
+/**
+ * Resolve whether this launch drafts, and with what.
+ *
+ * Never throws. An impossible `on` degrades to a plain launch with
+ * {@link Ds4DsparkDecision.unmetRequest} set rather than failing the session:
+ * drafting is an optimization, and refusing to serve chat over it would trade
+ * a missing speedup for an outage.
+ */
+export declare function resolveDs4Dspark(opts: Ds4DsparkOptions): Ds4DsparkDecision;
+/**
+ * Launch arguments for a decision. Empty when drafting is off, so the caller
+ * can spread this unconditionally.
+ *
+ * Deliberately does NOT emit `--mtp-draft`: for a DSpark support model the
+ * draft width comes from the companion's own `block_size` (ds4 returns
+ * `dspark_weights.block_size` from `ds4_engine_mtp_draft_tokens`). `--mtp-draft`
+ * only moves the legacy-MTP path, where the server's default of 1 would
+ * otherwise disable drafting outright — which makes it look load-bearing here
+ * when it is inert.
+ */
+export declare function ds4DsparkArgs(decision: Ds4DsparkDecision): string[];

package/dist/providers/ds4/dspark.js

@@ -0,0 +1,107 @@
+/**
+ * DSpark speculative decoding for ds4 (`--dspark --mtp-model <support.gguf>`).
+ *
+ * ds4 can draft several tokens ahead with a small companion GGUF and verify
+ * them against the target model in one batched pass. Two hard constraints and
+ * 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.
+ *  - **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
+ *    Flash IQ2_XXS at full residency, seed-pinned A/B/C/A: baseline 38.4 tok/s
+ *    against 38.5 opportunistic and 36.7 exact, with ds4's own
+ *    `DS4_DSPARK_STATS` reporting net_saved of -1301 ms and -1038 ms. Verifying
+ *    a 5-token block through a 284B MoE costs more than the single-token
+ *    decodes it skips.
+ *
+ * Hence `auto` keys on the **backend**, not on unified memory: Apple Silicon
+ * reports `gpuMemoryKind: 'unified'` exactly as GB10 does, so a
+ * residency-or-unified predicate would enable drafting on the one platform
+ * where it was measured to lose.
+ */
+/**
+ * Resolve whether this launch drafts, and with what.
+ *
+ * Never throws. An impossible `on` degrades to a plain launch with
+ * {@link Ds4DsparkDecision.unmetRequest} set rather than failing the session:
+ * drafting is an optimization, and refusing to serve chat over it would trade
+ * a missing speedup for an outage.
+ */
+export function resolveDs4Dspark(opts) {
+    const mode = opts.mode ?? 'auto';
+    if (mode === 'off') {
+        return { enabled: false, reason: 'disabled by config (ds4Dspark=off)' };
+    }
+    if (!opts.supportModelPath) {
+        return {
+            enabled: false,
+            reason: 'no DSpark support model available',
+            ...(mode === 'on'
+                ? {
+                    unmetRequest: 'ds4Dspark=on but no DSpark support model is available. Install a model whose catalog entry ships one, or set ds4DsparkModelPath to a support GGUF.',
+                }
+                : {}),
+        };
+    }
+    if (opts.ssdStreaming) {
+        return {
+            enabled: false,
+            reason: 'SSD streaming is on; ds4 rejects --mtp-model with --ssd-streaming',
+            ...(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).',
+                }
+                : {}),
+        };
+    }
+    if (opts.companionFitsMemory === false) {
+        return {
+            enabled: false,
+            reason: 'support model does not fit alongside the resident weights',
+            ...(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.',
+                }
+                : {}),
+        };
+    }
+    if (mode === 'on') {
+        return {
+            enabled: true,
+            supportModelPath: opts.supportModelPath,
+            reason: 'enabled by config (ds4Dspark=on)',
+        };
+    }
+    // auto
+    if (opts.backend !== 'cuda') {
+        return {
+            enabled: false,
+            reason: `auto: backend is ${opts.backend}; drafting measured net-negative on Metal`,
+        };
+    }
+    return {
+        enabled: true,
+        supportModelPath: opts.supportModelPath,
+        reason: 'auto: CUDA backend with a fully resident model',
+    };
+}
+/**
+ * Launch arguments for a decision. Empty when drafting is off, so the caller
+ * can spread this unconditionally.
+ *
+ * Deliberately does NOT emit `--mtp-draft`: for a DSpark support model the
+ * draft width comes from the companion's own `block_size` (ds4 returns
+ * `dspark_weights.block_size` from `ds4_engine_mtp_draft_tokens`). `--mtp-draft`
+ * only moves the legacy-MTP path, where the server's default of 1 would
+ * otherwise disable drafting outright — which makes it look load-bearing here
+ * when it is inert.
+ */
+export function ds4DsparkArgs(decision) {
+    if (!decision.enabled || !decision.supportModelPath)
+        return [];
+    return ['--dspark', '--mtp-model', decision.supportModelPath];
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Model-embedded multi-token prediction for ds4 (`--mtp`).
+ *
+ * Qwen3.8 Flash Next and GLM 5.3 carry their draft block inside the language
+ * GGUF, unlike DeepSeek DSpark's external `--mtp-model` companion. Catalog
+ * presence is therefore both a capability declaration and the `auto` opt-in:
+ * older/unknown GGUFs never receive a flag they may reject.
+ */
+export type Ds4MtpMode = 'off' | 'on' | 'auto';
+export interface Ds4EmbeddedMtpCatalog {
+    /** Pass `--mtp-exact-sampling` so non-zero-temperature requests stay distribution-correct. */
+    exactSampling?: boolean;
+}
+export interface Ds4MtpOptions {
+    /** `config.ds4Mtp`. Absent means `auto`. */
+    mode?: Ds4MtpMode;
+    /** Embedded-MTP capability declared by the selected catalog source. */
+    catalog?: Ds4EmbeddedMtpCatalog;
+    /** Optional operator override; absent inherits the catalog recommendation. */
+    exactSampling?: boolean;
+    /** External DSpark and embedded MTP are alternative draft paths, never stacked. */
+    dsparkEnabled?: boolean;
+}
+export interface Ds4MtpDecision {
+    enabled: boolean;
+    exactSampling: boolean;
+    reason: string;
+    /** Populated only when an explicit `on` request could not be honored. */
+    unmetRequest?: string;
+}
+export declare function resolveDs4Mtp(opts: Ds4MtpOptions): Ds4MtpDecision;
+export declare function ds4MtpArgs(decision: Ds4MtpDecision): string[];

package/dist/providers/ds4/mtp.js

@@ -0,0 +1,46 @@
+/**
+ * Model-embedded multi-token prediction for ds4 (`--mtp`).
+ *
+ * Qwen3.8 Flash Next and GLM 5.3 carry their draft block inside the language
+ * GGUF, unlike DeepSeek DSpark's external `--mtp-model` companion. Catalog
+ * presence is therefore both a capability declaration and the `auto` opt-in:
+ * older/unknown GGUFs never receive a flag they may reject.
+ */
+export function resolveDs4Mtp(opts) {
+    const mode = opts.mode ?? 'auto';
+    const exactSampling = opts.exactSampling ?? opts.catalog?.exactSampling ?? false;
+    if (mode === 'off') {
+        return { enabled: false, exactSampling: false, reason: 'disabled by config (ds4Mtp=off)' };
+    }
+    if (opts.dsparkEnabled) {
+        return {
+            enabled: false,
+            exactSampling: false,
+            reason: 'external DSpark is active; embedded MTP is an alternative draft path',
+            ...(mode === 'on'
+                ? {
+                    unmetRequest: 'ds4Mtp=on cannot be combined with the active DSpark support model. Disable ds4Dspark or select a model with embedded MTP and no external draft companion.',
+                }
+                : {}),
+        };
+    }
+    if (mode === 'auto' && !opts.catalog) {
+        return {
+            enabled: false,
+            exactSampling: false,
+            reason: 'auto: selected catalog model does not declare embedded MTP',
+        };
+    }
+    return {
+        enabled: true,
+        exactSampling,
+        reason: mode === 'on'
+            ? 'enabled by config (ds4Mtp=on)'
+            : `auto: catalog declares embedded MTP${exactSampling ? ' with exact sampling' : ''}`,
+    };
+}
+export function ds4MtpArgs(decision) {
+    if (!decision.enabled)
+        return [];
+    return ['--mtp', ...(decision.exactSampling ? ['--mtp-exact-sampling'] : [])];
+}

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

@@ -0,0 +1,67 @@
+import type { LlamaCppProvider } from '../llama-cpp/index.js';
+import type { LlamaCppLogFile } from '../llama-cpp/log.js';
+import type { NativeEngineLifecycleSnapshot } from '../native/supervisor.js';
+import type { LLMProvider, LLMSession, ModelInfo, SessionOpts } from '../types.js';
+import type { Ds4CacheAdapter } from './cache-adapter.js';
+/** Levels accepted by ds4-server's request parser for every supported family. */
+export declare const DS4_REASONING_EFFORTS: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * ds4 (DwarfStar) provider — antirez's specialized DeepSeek-V4/GLM inference
+ * engine. `ds4-server` speaks the *identical* OpenAI-compatible
+ * `/v1/chat/completions` SSE dialect as `llama-server`, and ds4 models
+ * are GGUF, so rather than duplicate the ~4000-line llama.cpp turn loop
+ * (request shaping, SSE pump, tool-call accumulation, reasoning-channel
+ * parsing, idle watchdogs, queue) we COMPOSE: a {@link Ds4Provider}
+ * wraps an inner {@link LlamaCppProvider} configured to drive a ds4
+ * supervisor (or external URL), and only relabels its identity to
+ * `'ds4'` so engine-key routing, the pool, and the capacity broker see
+ * a first-class engine.
+ *
+ * What ds4 does NOT share with llama-server is process management: the
+ * launch args (`--metal`, `--ssd-streaming`, `--ssd-streaming-cache-experts`,
+ * `--kv-disk-dir`) and readiness probe (`GET /v1/models` — ds4 has no
+ * `/health`) live in `buildDs4Provider` (chat/manager.ts), which hands
+ * this class a ready-built `LlamaCppProvider`.
+ *
+ * The inner session emits llama.cpp-tagged telemetry; ChatManager relabels
+ * those events from the owning session's `providerName` before publishing,
+ * so the global engine pill and queue surfaces correctly identify DS4 without
+ * forking the mature llama.cpp turn loop. Routing/eviction key directly off
+ * this class's `name`.
+ */
+export declare class Ds4Provider implements LLMProvider {
+    readonly name: "ds4";
+    /** Inner llama.cpp-compatible engine driving the ds4-server process. */
+    private readonly inner;
+    /**
+     * The ds4 cache adapter — held HERE, never forwarded to the inner
+     * llama provider. The inner send path calls llama-specific adapter
+     * methods (slot allocation, prepareForSend); the ds4 adapter is a
+     * different shape (warm-only, no slots) and is reached exclusively
+     * through `getCacheAdapter()` by `prewarmSession` and the controller.
+     */
+    private cacheAdapter;
+    constructor(opts: {
+        inner: LlamaCppProvider;
+    });
+    setCacheAdapter(adapter: Ds4CacheAdapter): void;
+    getCacheAdapter(): Ds4CacheAdapter | null;
+    /** The wrapped engine — exposed so the cache adapter / freeze hook in
+     * `buildDs4Provider` can reach the same instance this provider drives. */
+    get llamaCpp(): LlamaCppProvider;
+    get supportsImageInput(): boolean;
+    isEngineBusy(): boolean;
+    engineLifecycleSnapshot(): NativeEngineLifecycleSnapshot | undefined;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    createSession(opts: SessionOpts): Promise<LLMSession>;
+    listModels(): Promise<ModelInfo[]>;
+    getEffectiveModelId(): string | undefined;
+    getContextWindow(): number | undefined;
+    /** Persistent ds4-server stdout/stderr, exposed to diagnostics/routes. */
+    getLogFile(): LlamaCppLogFile | undefined;
+    get queue(): LLMProvider['queue'];
+    get batch(): LLMProvider['batch'];
+    get supportsExternalTools(): LLMProvider['supportsExternalTools'];
+    get supportsPriorMessages(): LLMProvider['supportsPriorMessages'];
+}

package/dist/providers/ds4/provider.js

@@ -0,0 +1,104 @@
+/** Levels accepted by ds4-server's request parser for every supported family. */
+export const DS4_REASONING_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+/**
+ * ds4 (DwarfStar) provider — antirez's specialized DeepSeek-V4/GLM inference
+ * engine. `ds4-server` speaks the *identical* OpenAI-compatible
+ * `/v1/chat/completions` SSE dialect as `llama-server`, and ds4 models
+ * are GGUF, so rather than duplicate the ~4000-line llama.cpp turn loop
+ * (request shaping, SSE pump, tool-call accumulation, reasoning-channel
+ * parsing, idle watchdogs, queue) we COMPOSE: a {@link Ds4Provider}
+ * wraps an inner {@link LlamaCppProvider} configured to drive a ds4
+ * supervisor (or external URL), and only relabels its identity to
+ * `'ds4'` so engine-key routing, the pool, and the capacity broker see
+ * a first-class engine.
+ *
+ * What ds4 does NOT share with llama-server is process management: the
+ * launch args (`--metal`, `--ssd-streaming`, `--ssd-streaming-cache-experts`,
+ * `--kv-disk-dir`) and readiness probe (`GET /v1/models` — ds4 has no
+ * `/health`) live in `buildDs4Provider` (chat/manager.ts), which hands
+ * this class a ready-built `LlamaCppProvider`.
+ *
+ * The inner session emits llama.cpp-tagged telemetry; ChatManager relabels
+ * those events from the owning session's `providerName` before publishing,
+ * so the global engine pill and queue surfaces correctly identify DS4 without
+ * forking the mature llama.cpp turn loop. Routing/eviction key directly off
+ * this class's `name`.
+ */
+export class Ds4Provider {
+    name = 'ds4';
+    /** Inner llama.cpp-compatible engine driving the ds4-server process. */
+    inner;
+    /**
+     * The ds4 cache adapter — held HERE, never forwarded to the inner
+     * llama provider. The inner send path calls llama-specific adapter
+     * methods (slot allocation, prepareForSend); the ds4 adapter is a
+     * different shape (warm-only, no slots) and is reached exclusively
+     * through `getCacheAdapter()` by `prewarmSession` and the controller.
+     */
+    cacheAdapter = null;
+    constructor(opts) {
+        this.inner = opts.inner;
+    }
+    setCacheAdapter(adapter) {
+        this.cacheAdapter = adapter;
+    }
+    getCacheAdapter() {
+        return this.cacheAdapter;
+    }
+    /** The wrapped engine — exposed so the cache adapter / freeze hook in
+     * `buildDs4Provider` can reach the same instance this provider drives. */
+    get llamaCpp() {
+        return this.inner;
+    }
+    get supportsImageInput() {
+        return this.inner.supportsImageInput;
+    }
+    isEngineBusy() {
+        return this.inner.isEngineBusy();
+    }
+    engineLifecycleSnapshot() {
+        return this.inner.engineLifecycleSnapshot();
+    }
+    initialize() {
+        return this.inner.initialize();
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    createSession(opts) {
+        return this.inner.createSession(opts);
+    }
+    async listModels() {
+        const models = await this.inner.listModels();
+        return models.map((model) => ({
+            ...model,
+            supportsReasoning: true,
+            reasoningEfforts: [...DS4_REASONING_EFFORTS],
+            // This matches ds4-server's default when neither a catalog profile nor
+            // a per-gezel override supplies an effort.
+            defaultReasoningEffort: 'high',
+        }));
+    }
+    getEffectiveModelId() {
+        return this.inner.getEffectiveModelId();
+    }
+    getContextWindow() {
+        return this.inner.getContextWindow();
+    }
+    /** Persistent ds4-server stdout/stderr, exposed to diagnostics/routes. */
+    getLogFile() {
+        return this.inner.getLogFile();
+    }
+    get queue() {
+        return this.inner.queue;
+    }
+    get batch() {
+        return this.inner.batch;
+    }
+    get supportsExternalTools() {
+        return this.inner.supportsExternalTools;
+    }
+    get supportsPriorMessages() {
+        return this.inner.supportsPriorMessages;
+    }
+}