@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/mlx/engine-log-router.js

@@ -0,0 +1,137 @@
+import { createLogger } from '@bendyline/gezel';
+import { classifyMlxFatalErrorLine, classifyMlxQueueLine, classifyMlxStartupLine, } from './stdout-parser.js';
+const log = createLogger('mlx');
+export class EngineLogRouter {
+    deps;
+    /** Last phase delivered, for the repeat filter. Cleared by `ready`. */
+    lastStartupPhase = null;
+    /**
+     * Latest fatal error seen before the engine served. The server's httpd keeps
+     * accepting connections after `_generate` dies, so `/health` cannot be
+     * trusted; while this is non-null a send short-circuits instead of hanging
+     * on an unresponsive completions endpoint. Cleared on `starting`.
+     */
+    fatalError = null;
+    /**
+     * Whether the engine has reported itself ready and is therefore serving.
+     * Gates fatal handling: the classifier reads any `SomeError: …` leaf line as
+     * engine death, which is right during startup and wrong afterwards. A
+     * caught, contained Python exception prints the same shape as a fatal one,
+     * and killing the engine for it takes down every *other* session sharing it
+     * — a spec-decode wave that failed one request, and answered that request,
+     * SIGKILLed a 27B mid-turn and dropped an unrelated session with it.
+     */
+    serving = false;
+    /**
+     * Most recent error line seen while serving. Not fatal — kept so a turn that
+     * dies on a dropped stream can name the real cause instead of "something
+     * closed the HTTP request."
+     */
+    lastRuntimeError = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One raw line from the supervised child. */
+    onLine(line) {
+        // Fatal takes precedence over phase classification — one `ValueError: …`
+        // leaf line in a traceback is enough to mark the engine broken, and
+        // surfacing it immediately beats hanging for the full turn-timeout.
+        // Only before the engine is serving, though: once it is up, the same line
+        // shape carries *contained* per-request failures the sidecar has already
+        // handled and answered.
+        const fatal = classifyMlxFatalErrorLine(line);
+        if (fatal) {
+            if (this.serving)
+                this.noteRuntimeError(fatal);
+            else
+                this.handleFatalError(fatal);
+            return;
+        }
+        // Wave-scheduling markers bypass the repeat filter and never become the
+        // replayed "last phase". A queued request's markers are identical every
+        // few seconds BY DESIGN — each one is liveness that re-arms the waiting
+        // session's watchdog — so filtering repeats is exactly what must not
+        // happen to them. They are always tagged, so delivery stays per-session.
+        const queued = classifyMlxQueueLine(line);
+        if (queued) {
+            this.deps.deliver(queued);
+            return;
+        }
+        const phase = classifyMlxStartupLine(line);
+        if (!phase)
+            return;
+        const name = this.deps.modelDisplayName?.();
+        if (phase.phase === 'loading_model' && name) {
+            phase.detail = `Loading model — ${name}`;
+        }
+        // A fresh child gets a clean slate. Both flags move before the repeat
+        // filter below: an identical phase line returns early, and readiness must
+        // not depend on which line won.
+        if (phase.phase === 'starting') {
+            this.fatalError = null;
+            this.lastRuntimeError = null;
+            this.serving = false;
+        }
+        if (phase.phase === 'ready')
+            this.serving = true;
+        if (this.lastStartupPhase &&
+            this.lastStartupPhase.phase === phase.phase &&
+            this.lastStartupPhase.detail === phase.detail &&
+            // Two subs prefilling in lockstep render identical detail; without the
+            // owner in the key the second one's marker is dropped as a repeat and
+            // that session's bar stalls at whatever it last saw.
+            this.lastStartupPhase.cacheId === phase.cacheId) {
+            return;
+        }
+        this.lastStartupPhase = phase.phase === 'ready' ? null : phase;
+        this.deps.deliver(phase);
+        if (phase.phase === 'ready')
+            this.deps.onReady();
+    }
+    /**
+     * Last delivered phase, replayed to a session that registers mid-run so a
+     * chat opened during a long weight load still shows what the engine is
+     * doing. Null once `ready` clears it — there is nothing to catch up on.
+     */
+    lastPhase() {
+        return this.lastStartupPhase;
+    }
+    /**
+     * Consume the startup fatal, if one was seen. Consumes on read: the caller
+     * still throws it, so the *current* send fails fast, but a later send gets a
+     * fresh shot at respawning — otherwise a fix made out-of-process
+     * (reinstalled deps, a different model, a venv reset) would not take effect
+     * until gezeld itself restarted.
+     */
+    takeFatalError() {
+        const fatal = this.fatalError;
+        this.fatalError = null;
+        return fatal;
+    }
+    /** Consume the last serving-time error, if one was seen. */
+    takeRuntimeError() {
+        const err = this.lastRuntimeError;
+        this.lastRuntimeError = null;
+        return err;
+    }
+    /**
+     * An error from an engine that is up and serving. Deliberately does NOT tear
+     * the engine down: the sidecar prints these from handlers that already
+     * contained the failure and answered the affected request, so the engine is
+     * still correct for everyone else on it.
+     */
+    noteRuntimeError(fatal) {
+        this.lastRuntimeError = fatal;
+        log.warn(`engine error while serving (engine left running): ${fatal.message}`);
+    }
+    handleFatalError(fatal) {
+        // First-seen wins — later traceback frames must not overwrite the leaf
+        // exception with something further up the stack, and a server spamming
+        // the same error must not thrash the supervisor.
+        if (this.fatalError)
+            return;
+        this.fatalError = fatal;
+        log.error(`fatal engine error detected: ${fatal.message}`);
+        this.deps.onFatal(fatal);
+    }
+}

package/dist/providers/mlx/engine-stats-sampler.d.ts

@@ -0,0 +1,36 @@
+import type { EngineStatsEvent } from '../streaming-session.js';
+/**
+ * Sample how much memory the engine is holding, a moment after it reports
+ * itself ready — mlx_lm doesn't log buffer allocations the way llama.cpp
+ * does. We delay 2s so memory-mapped weights have settled; earlier samples
+ * undercount.
+ *
+ * Physical footprint, not RSS. Metal's unified-memory allocations — KV,
+ * activation buffers, MLX's retained buffer cache — never appear in RSS, so
+ * RSS reported 30 GB for an engine whose real footprint was ~103 GB, and
+ * the pill disagreed 3.6x with the memory strip (which samples footprint)
+ * about the same process. RSS stays as the fallback for hosts where
+ * `footprint` is unavailable; it is a floor, not a lie.
+ */
+export declare class MlxEngineStatsSampler {
+    private readonly opts;
+    /**
+     * Replayed to sessions that register after the engine finishes loading —
+     * same pattern as llama-cpp's `lastEngineStats` — so a chat started mid-run
+     * can surface the memory footprint in the pill dropdown without restarting
+     * the engine.
+     */
+    private last;
+    /**
+     * Guards against multiple samples from a single "ready" line (e.g. when
+     * uvicorn logs both "Application startup complete" and "Uvicorn running" —
+     * both classify as `ready`).
+     */
+    private pending;
+    constructor(opts: {
+        pid: () => number | undefined;
+        publish: (stats: EngineStatsEvent) => void;
+    });
+    get latest(): EngineStatsEvent | null;
+    schedule(): void;
+}

package/dist/providers/mlx/engine-stats-sampler.js

@@ -0,0 +1,59 @@
+import { readProcessRssBytes } from './runtime-diagnostics.js';
+/**
+ * Sample how much memory the engine is holding, a moment after it reports
+ * itself ready — mlx_lm doesn't log buffer allocations the way llama.cpp
+ * does. We delay 2s so memory-mapped weights have settled; earlier samples
+ * undercount.
+ *
+ * Physical footprint, not RSS. Metal's unified-memory allocations — KV,
+ * activation buffers, MLX's retained buffer cache — never appear in RSS, so
+ * RSS reported 30 GB for an engine whose real footprint was ~103 GB, and
+ * the pill disagreed 3.6x with the memory strip (which samples footprint)
+ * about the same process. RSS stays as the fallback for hosts where
+ * `footprint` is unavailable; it is a floor, not a lie.
+ */
+export class MlxEngineStatsSampler {
+    opts;
+    /**
+     * Replayed to sessions that register after the engine finishes loading —
+     * same pattern as llama-cpp's `lastEngineStats` — so a chat started mid-run
+     * can surface the memory footprint in the pill dropdown without restarting
+     * the engine.
+     */
+    last = null;
+    /**
+     * Guards against multiple samples from a single "ready" line (e.g. when
+     * uvicorn logs both "Application startup complete" and "Uvicorn running" —
+     * both classify as `ready`).
+     */
+    pending = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get latest() {
+        return this.last;
+    }
+    schedule() {
+        if (this.pending)
+            return;
+        this.pending = true;
+        setTimeout(async () => {
+            try {
+                const pid = this.opts.pid();
+                if (!pid)
+                    return;
+                const { sampleDarwinProcessFootprintBytes } = await import('../../system/gezel-process-memory.js');
+                const footprintBytes = await sampleDarwinProcessFootprintBytes({ pid });
+                const rssBytes = footprintBytes ?? (await readProcessRssBytes(pid));
+                if (rssBytes === null)
+                    return;
+                const stats = { provider: 'mlx', ramAllocBytes: rssBytes };
+                this.last = stats;
+                this.opts.publish(stats);
+            }
+            finally {
+                this.pending = false;
+            }
+        }, 2_000).unref?.();
+    }
+}

package/dist/providers/mlx/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the MLX provider package. Other parts of the
+ * service import from this barrel rather than reaching into sub-files;
+ * the layout (`provider.ts`, `models.ts`, `config-parser.ts`,
+ * `stdout-parser.ts`) is internal.
+ */
+export { MlxProvider } from './provider.js';
+export { readMlxSummary, type MlxModelSummary } from './config-parser.js';
+export { MlxModelManager, type MlxInstallEvent, type InstalledMlxModel, type MlxModelManagerOptions, } from './models.js';
+export { MLX_DEFAULT_PACKAGE_SPEC, MLX_VENV_NAME, mlxVenvPackages } from './venv.js';

package/dist/providers/mlx/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the MLX provider package. Other parts of the
+ * service import from this barrel rather than reaching into sub-files;
+ * the layout (`provider.ts`, `models.ts`, `config-parser.ts`,
+ * `stdout-parser.ts`) is internal.
+ */
+export { MlxProvider } from './provider.js';
+export { readMlxSummary } from './config-parser.js';
+export { MlxModelManager, } from './models.js';
+export { MLX_DEFAULT_PACKAGE_SPEC, MLX_VENV_NAME, mlxVenvPackages } from './venv.js';

package/dist/providers/mlx/log.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rolling append-only log for the MLX server's stdout/stderr (the
+ * wrapped `gezel_mlx_server.py`). Mirrors `LlamaCppLogFile` exactly —
+ * different filename prefix, same rotation semantics. The duplication
+ * is deliberate: the alternative is a shared package boundary, which
+ * costs more than two files of trivial rotation logic at this scale
+ * (same rationale captured in `LlamaCppLogFile`'s header).
+ *
+ * Files live at `<dir>/mlx-server-YYYY-MM-DD.log`, roll to `-1.log`
+ * / `-2.log` when the active file crosses 10 MB, and ones older than
+ * 7 days are swept on open.
+ *
+ * Why this exists: the MLX supervisor's `onLog` previously routed
+ * only to `console.log`, so the python wrapper's `[cache] miss/hit/
+ * saved`, `Prefill: …`, model-load, and `[stream] client
+ * disconnected` lines vanished into the embedded gezeld's stdout
+ * (visible only when launched from a terminal). Diagnosing the
+ * "prefilling 3-4 times in a row" pattern requires the cache log
+ * lines on disk; this class is the persistent trail.
+ */
+export declare class MlxLogFile {
+    private readonly dir;
+    private stream;
+    private currentPath;
+    private currentDay;
+    private rollIndex;
+    private bytesWritten;
+    private readonly maxBytes;
+    private readonly retentionDays;
+    private readonly readyPromise;
+    private pendingWrites;
+    constructor(dir: string);
+    private init;
+    private today;
+    private openForToday;
+    private rollIfNeeded;
+    /**
+     * Fire-and-forget append. Serializes writes via an internal promise
+     * chain so rotation + ordering stay correct even under bursty
+     * stdout. The caller doesn't need to await individual lines; any
+     * subsequent `tail()` / `close()` awaits the drain.
+     */
+    write(line: string): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Read the last `bytes` chars of the current file. Useful for a
+     * Settings → On-device → MLX engine log disclosure (mirrors the
+     * llama-cpp tail surface).
+     */
+    tail(bytes: number): Promise<string>;
+    /** Absolute path of the current log file (for surfacing in UI). */
+    currentFile(): string | null;
+    private sweepOldFiles;
+}

package/dist/providers/mlx/log.js

@@ -0,0 +1,157 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { redactCredentials } from '@bendyline/gezel';
+/**
+ * Rolling append-only log for the MLX server's stdout/stderr (the
+ * wrapped `gezel_mlx_server.py`). Mirrors `LlamaCppLogFile` exactly —
+ * different filename prefix, same rotation semantics. The duplication
+ * is deliberate: the alternative is a shared package boundary, which
+ * costs more than two files of trivial rotation logic at this scale
+ * (same rationale captured in `LlamaCppLogFile`'s header).
+ *
+ * Files live at `<dir>/mlx-server-YYYY-MM-DD.log`, roll to `-1.log`
+ * / `-2.log` when the active file crosses 10 MB, and ones older than
+ * 7 days are swept on open.
+ *
+ * Why this exists: the MLX supervisor's `onLog` previously routed
+ * only to `console.log`, so the python wrapper's `[cache] miss/hit/
+ * saved`, `Prefill: …`, model-load, and `[stream] client
+ * disconnected` lines vanished into the embedded gezeld's stdout
+ * (visible only when launched from a terminal). Diagnosing the
+ * "prefilling 3-4 times in a row" pattern requires the cache log
+ * lines on disk; this class is the persistent trail.
+ */
+export class MlxLogFile {
+    dir;
+    stream = null;
+    currentPath = null;
+    currentDay = null;
+    rollIndex = 0;
+    bytesWritten = 0;
+    maxBytes = 10 * 1024 * 1024;
+    retentionDays = 7;
+    readyPromise;
+    pendingWrites = Promise.resolve();
+    constructor(dir) {
+        this.dir = dir;
+        this.readyPromise = this.init();
+    }
+    async init() {
+        await mkdir(this.dir, { recursive: true });
+        await this.sweepOldFiles();
+        await this.openForToday();
+    }
+    today() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    async openForToday() {
+        this.currentDay = this.today();
+        this.rollIndex = 0;
+        const base = join(this.dir, `mlx-server-${this.currentDay}.log`);
+        let existingSize = 0;
+        try {
+            const st = await stat(base);
+            existingSize = st.size;
+        }
+        catch {
+            /* not present yet */
+        }
+        this.currentPath = base;
+        this.bytesWritten = existingSize;
+        this.stream = createWriteStream(base, { flags: 'a' });
+    }
+    async rollIfNeeded() {
+        if (this.today() !== this.currentDay) {
+            await this.close();
+            await this.openForToday();
+            return;
+        }
+        if (this.bytesWritten < this.maxBytes)
+            return;
+        await this.close();
+        this.rollIndex += 1;
+        const rolled = join(this.dir, `mlx-server-${this.currentDay}-${this.rollIndex}.log`);
+        this.currentPath = rolled;
+        this.bytesWritten = 0;
+        this.stream = createWriteStream(rolled, { flags: 'a' });
+    }
+    /**
+     * Fire-and-forget append. Serializes writes via an internal promise
+     * chain so rotation + ordering stay correct even under bursty
+     * stdout. The caller doesn't need to await individual lines; any
+     * subsequent `tail()` / `close()` awaits the drain.
+     */
+    write(line) {
+        const safe = redactCredentials(line);
+        const run = async () => {
+            await this.readyPromise;
+            await this.rollIfNeeded();
+            if (!this.stream)
+                return;
+            const buf = Buffer.from(safe.endsWith('\n') ? safe : `${safe}\n`, 'utf8');
+            await new Promise((resolve) => {
+                this.stream?.write(buf, () => resolve());
+            });
+            this.bytesWritten += buf.length;
+        };
+        this.pendingWrites = this.pendingWrites.then(run, run);
+    }
+    async flush() {
+        await this.pendingWrites;
+    }
+    async close() {
+        await this.pendingWrites;
+        if (!this.stream)
+            return;
+        const s = this.stream;
+        this.stream = null;
+        await new Promise((resolve) => s.end(() => resolve()));
+    }
+    /**
+     * Read the last `bytes` chars of the current file. Useful for a
+     * Settings → On-device → MLX engine log disclosure (mirrors the
+     * llama-cpp tail surface).
+     */
+    async tail(bytes) {
+        await this.readyPromise;
+        await this.flush();
+        if (!this.currentPath)
+            return '';
+        try {
+            const content = await readFile(this.currentPath, 'utf8');
+            return content.length <= bytes ? content : content.slice(content.length - bytes);
+        }
+        catch {
+            return '';
+        }
+    }
+    /** Absolute path of the current log file (for surfacing in UI). */
+    currentFile() {
+        return this.currentPath;
+    }
+    async sweepOldFiles() {
+        const horizonMs = Date.now() - this.retentionDays * 24 * 60 * 60 * 1000;
+        let entries;
+        try {
+            entries = await readdir(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (!name.startsWith('mlx-server-') || !name.endsWith('.log'))
+                continue;
+            const p = join(this.dir, name);
+            try {
+                const st = await stat(p);
+                if (st.mtimeMs < horizonMs) {
+                    await unlink(p);
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}

package/dist/providers/mlx/model-geometry.d.ts

@@ -0,0 +1,35 @@
+import type { WindowedKvInput } from '../llama-cpp/offload-planner.js';
+/**
+ * Attention geometry from an MLX model directory's `config.json` — the
+ * safetensors-world equivalent of the GGUF header read, feeding the same
+ * KV estimators (`estimateExactPerSlotKvBytesF16` /
+ * `estimateWindowedKvLinearization`). Before this, MLX memory math could
+ * only use the weights-scaled heuristic, which under-prices small dense
+ * models ~3× and knows nothing about sliding-window layers.
+ *
+ * Shapes handled (fields live under `text_config` on multimodal configs,
+ * top-level otherwise):
+ * - Dense full-attention (qwen3.5): `num_hidden_layers`,
+ *   `num_key_value_heads`, `head_dim` (or hidden/heads).
+ * - Sliding-window (gemma4): `layer_types` of
+ *   `sliding_attention`/`full_attention`, `sliding_window`, SWA layers at
+ *   `head_dim` × `num_key_value_heads`, global layers at
+ *   `global_head_dim` × `num_global_key_value_heads`. The E-series also sets
+ *   `num_kv_shared_layers`: mlx-vlm's `make_cache` builds caches only for the
+ *   layers before the shared tail, so E4B holds 4 full-attention caches, not
+ *   7 — pricing all 7 overstated its KV ~1.75x.
+ * - Linear-attention hybrids (qwen3.6-a3b): `linear_attention` layers
+ *   carry a small context-independent recurrent state; approximated as a
+ *   window-capped layer with a synthetic 1024-token window — the right
+ *   order of magnitude, and the full-attention layers dominate either
+ *   way. Pricing such a hybrid with full math overstates ~4×.
+ * - Qwen4-Exp / Qwen3.8 Flash Next: its QSA layers (`full_attention` in the
+ *   released config, `qwen_sparse_attention` in some converted configs) retain
+ *   ordinary K/V plus raw sparse-indexer keys, compressed block keys, and
+ *   MRoPE positions. The latter are folded into the global key width so
+ *   context admission doesn't under-price the checkpoint's auxiliary cache.
+ *
+ * Returns undefined (never guesses) when the layer count or head dims
+ * are unreadable — callers fall back to the heuristic.
+ */
+export declare function readMlxModelGeometry(modelDir: string): Omit<WindowedKvInput, 'kvCacheType'> | undefined;

package/dist/providers/mlx/model-geometry.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+const log = createLogger('mlx');
+/**
+ * Attention geometry from an MLX model directory's `config.json` — the
+ * safetensors-world equivalent of the GGUF header read, feeding the same
+ * KV estimators (`estimateExactPerSlotKvBytesF16` /
+ * `estimateWindowedKvLinearization`). Before this, MLX memory math could
+ * only use the weights-scaled heuristic, which under-prices small dense
+ * models ~3× and knows nothing about sliding-window layers.
+ *
+ * Shapes handled (fields live under `text_config` on multimodal configs,
+ * top-level otherwise):
+ * - Dense full-attention (qwen3.5): `num_hidden_layers`,
+ *   `num_key_value_heads`, `head_dim` (or hidden/heads).
+ * - Sliding-window (gemma4): `layer_types` of
+ *   `sliding_attention`/`full_attention`, `sliding_window`, SWA layers at
+ *   `head_dim` × `num_key_value_heads`, global layers at
+ *   `global_head_dim` × `num_global_key_value_heads`. The E-series also sets
+ *   `num_kv_shared_layers`: mlx-vlm's `make_cache` builds caches only for the
+ *   layers before the shared tail, so E4B holds 4 full-attention caches, not
+ *   7 — pricing all 7 overstated its KV ~1.75x.
+ * - Linear-attention hybrids (qwen3.6-a3b): `linear_attention` layers
+ *   carry a small context-independent recurrent state; approximated as a
+ *   window-capped layer with a synthetic 1024-token window — the right
+ *   order of magnitude, and the full-attention layers dominate either
+ *   way. Pricing such a hybrid with full math overstates ~4×.
+ * - Qwen4-Exp / Qwen3.8 Flash Next: its QSA layers (`full_attention` in the
+ *   released config, `qwen_sparse_attention` in some converted configs) retain
+ *   ordinary K/V plus raw sparse-indexer keys, compressed block keys, and
+ *   MRoPE positions. The latter are folded into the global key width so
+ *   context admission doesn't under-price the checkpoint's auxiliary cache.
+ *
+ * Returns undefined (never guesses) when the layer count or head dims
+ * are unreadable — callers fall back to the heuristic.
+ */
+export function readMlxModelGeometry(modelDir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(modelDir, 'config.json'), 'utf8'));
+    }
+    catch (err) {
+        log.debug(`model geometry unreadable in ${modelDir}: ${String(err)}`);
+        return undefined;
+    }
+    const cfg = (typeof raw.text_config === 'object' && raw.text_config !== null ? raw.text_config : raw);
+    const num = (key) => {
+        const v = cfg[key];
+        return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined;
+    };
+    const blockCount = num('num_hidden_layers');
+    if (!blockCount)
+        return undefined;
+    const headCountKv = num('num_key_value_heads');
+    const headDim = num('head_dim') ??
+        (num('hidden_size') && num('num_attention_heads')
+            ? Math.floor(num('hidden_size') / num('num_attention_heads'))
+            : undefined);
+    if (!headCountKv || !headDim)
+        return undefined;
+    const layerTypes = Array.isArray(cfg.layer_types) ? cfg.layer_types : undefined;
+    if (!layerTypes || layerTypes.length !== blockCount) {
+        // Uniform full attention: every layer scales with context.
+        return {
+            blockCount,
+            headCountKv,
+            keyLength: headDim,
+            valueLength: headDim,
+        };
+    }
+    const boundedTypes = new Set(['sliding_attention', 'linear_attention']);
+    const pattern = layerTypes.map((t) => boundedTypes.has(String(t)));
+    if (!pattern.some(Boolean)) {
+        return {
+            blockCount,
+            headCountKv,
+            keyLength: headDim,
+            valueLength: headDim,
+        };
+    }
+    const globalHeadDim = num('global_head_dim') ?? headDim;
+    const globalKvHeads = num('num_global_key_value_heads') ?? headCountKv;
+    const modelType = String(cfg.model_type ?? raw.model_type ?? '');
+    const rootModelType = String(raw.model_type ?? '');
+    const isQwen4Exp = modelType === 'qwen4_exp' || modelType === 'qwen4_exp_text' || rootModelType === 'qwen4_exp';
+    // Released Qwen3.8 Flash Next configs call these `full_attention`; the
+    // implementation class/cache calls them QSA. Accept the class-oriented
+    // spelling too for converted checkpoints that expose it directly.
+    const hasQwenSparseAttention = layerTypes.some((type) => String(type) === 'qwen_sparse_attention' || (isQwen4Exp && String(type) === 'full_attention'));
+    let globalKeyLength = globalHeadDim;
+    if (isQwen4Exp && hasQwenSparseAttention) {
+        const indexerKvHeads = num('indexer_kv_heads') ?? 1;
+        const indexerHeadDim = num('indexer_head_dim') ?? 128;
+        const indexerCompressRatio = num('indexer_compress_ratio') ?? 4;
+        // QSAKVCache keeps one raw index key per token and one normalized block
+        // key per `indexerCompressRatio` tokens. The 0.7.1 tower constructs
+        // position ids as int64 and multimodal inputs can carry three MRoPE axes,
+        // hence twelve f16-equivalent elements per token in the worst case.
+        const auxiliaryF16ElementsPerToken = indexerKvHeads * indexerHeadDim * (1 + 1 / indexerCompressRatio) + 12;
+        globalKeyLength += Math.ceil(auxiliaryF16ElementsPerToken / globalKvHeads);
+    }
+    const LINEAR_STATE_WINDOW_TOKENS = 1024;
+    const slidingWindow = num('sliding_window') ?? LINEAR_STATE_WINDOW_TOKENS;
+    const sharedKvLayers = num('num_kv_shared_layers');
+    return {
+        blockCount,
+        headCountKv,
+        headCountKvPerLayer: pattern.map((bounded) => (bounded ? headCountKv : globalKvHeads)),
+        slidingWindow,
+        slidingWindowPattern: pattern,
+        ...(sharedKvLayers !== undefined ? { sharedKvLayers } : {}),
+        keyLength: globalKeyLength,
+        valueLength: globalHeadDim,
+        keyLengthSwa: headDim,
+        valueLengthSwa: headDim,
+    };
+}