Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

feat(models): add MTP drafters for Gemma 4 QAT models (#1269)

Alcahest Malus Dienheim860c33b7cdc3
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 51133288b..1e09027a7 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -3724,7 +3724,10 @@ class IPCHandlers {
const modelPath = require("path").join(modelManager.modelsDir, modelInfo.model.fileName);
- await modelManager.serverManager.start(modelPath, modelManager.serverOptions(modelInfo));
+ await modelManager.serverManager.start(
+ modelPath,
+ await modelManager.serverStartOptions(modelInfo)
+ );
modelManager.currentServerModelId = modelId;
this.environmentManager.saveAllKeysToEnvFile().catch(() => {});
diff --git a/src/helpers/llamaServer.js b/src/helpers/llamaServer.js
index f2a20a46c..ca67c2540 100644
--- a/src/helpers/llamaServer.js
+++ b/src/helpers/llamaServer.js
@@ -27,6 +27,10 @@ class LlamaServerManager {
this.port = null;
this.ready = false;
this.modelPath = null;
+ // draftModelPath is the REQUESTED drafter (stable across identical requests, drives
+ // the start() restart check); activeDraftModelPath is the one that actually loaded.
+ this.draftModelPath = null;
+ this.activeDraftModelPath = null;
this.startupPromise = null;
this.healthCheckInterval = null;
this.healthCheckFailures = 0;
@@ -107,7 +111,11 @@ class LlamaServerManager {
async start(modelPath, options = {}) {
if (this.startupPromise) return this.startupPromise;
- if (this.ready && this.modelPath === modelPath) return;
+ // A change in drafter presence for the same model must still restart the
+ // server so the new speculative-decoding flags take effect.
+ const requestedDraftPath = options.draftModelPath || null;
+ if (this.ready && this.modelPath === modelPath && this.draftModelPath === requestedDraftPath)
+ return;
if (this.process) {
await this.stop();
@@ -128,6 +136,10 @@ class LlamaServerManager {
this.port = await this.findAvailablePort();
this.modelPath = modelPath;
+ // Store the REQUESTED drafter so start() compares against a stable value across
+ // identical requests; activeDraftModelPath tracks what actually loaded (see ctor).
+ this.draftModelPath = options.draftModelPath || null;
+ this.activeDraftModelPath = null;
const baseArgs = [
"--model",
@@ -145,8 +157,22 @@ class LlamaServerManager {
"--jinja",
];
+ // Draft flags stay separate from baseArgs so the fallback ladder can retry without
+ // them when a stale (pre-b9763) binary rejects the MTP args at parse time.
+ const draftArgs = options.draftModelPath
+ ? [
+ "--model-draft",
+ options.draftModelPath,
+ "--spec-type",
+ "draft-mtp",
+ "--spec-draft-n-max",
+ "3",
+ ]
+ : [];
+
if (process.platform === "darwin") {
- const args = [...baseArgs, "--n-gpu-layers", String(options.gpuLayers ?? 99)];
+ // The metal binary is always the bundled pin, so it never rejects the draft flags.
+ const args = [...baseArgs, "--n-gpu-layers", String(options.gpuLayers ?? 99), ...draftArgs];
await this._startWithBinary(
binaryPaths.default,
args,
@@ -154,8 +180,9 @@ class LlamaServerManager {
STARTUP_TIMEOUT_MS
);
this.activeBackend = "metal";
+ this.activeDraftModelPath = this.draftModelPath;
} else {
- await this._startWithGpuFallback(binaryPaths, baseArgs, options);
+ await this._startWithGpuFallback(binaryPaths, baseArgs, options, draftArgs);
}
this.startHealthCheck();
@@ -164,41 +191,91 @@ class LlamaServerManager {
port: this.port,
model: path.basename(modelPath),
backend: this.activeBackend,
+ mtp: this.activeDraftModelPath !== null,
});
}
- async _startWithGpuFallback(binaryPaths, baseArgs, options) {
+ async _startWithGpuFallback(binaryPaths, baseArgs, options, draftArgs = []) {
const gpuArgs = [...baseArgs, "--n-gpu-layers", String(options.gpuLayers ?? 99)];
const cpuArgs = baseArgs;
+ const hasDraft = draftArgs.length > 0;
+
+ // Degrade ladder: GPU+MTP, then GPU alone (a live GPU beats speculation), then
+ // CPU+MTP (the bundled pin normally accepts the flags), then plain CPU. The
+ // no-draft rungs collapse into their twins when no drafter is declared, so a
+ // drafterless start keeps today's exact single vulkan->cpu fallback.
+ const rungs = [
+ {
+ backend: "vulkan",
+ name: "Vulkan",
+ binary: binaryPaths.vulkan,
+ args: [...gpuArgs, ...draftArgs],
+ mtp: hasDraft,
+ timeout: VULKAN_STARTUP_TIMEOUT_MS,
+ attemptMsg: "Attempting Vulkan backend startup",
+ },
+ {
+ backend: "vulkan",
+ name: "Vulkan",
+ binary: binaryPaths.vulkan,
+ args: gpuArgs,
+ mtp: false,
+ noDraft: true,
+ timeout: VULKAN_STARTUP_TIMEOUT_MS,
+ attemptMsg: "Attempting Vulkan backend startup",
+ },
+ {
+ backend: "cpu",
+ name: "CPU",
+ binary: binaryPaths.cpu,
+ args: [...cpuArgs, ...draftArgs],
+ mtp: hasDraft,
+ timeout: STARTUP_TIMEOUT_MS,
+ attemptMsg: "Starting with CPU backend",
+ },
+ {
+ backend: "cpu",
+ name: "CPU",
+ binary: binaryPaths.cpu,
+ args: cpuArgs,
+ mtp: false,
+ noDraft: true,
+ timeout: STARTUP_TIMEOUT_MS,
+ attemptMsg: "Starting with CPU backend",
+ },
+ ];
+
+ const ladder = rungs.filter((rung) => rung.binary && !(rung.noDraft && !hasDraft));
+ if (ladder.length === 0) throw new Error("No CPU llama-server binary available");
- if (binaryPaths.vulkan) {
+ let lastError = null;
+ for (let i = 0; i < ladder.length; i++) {
+ const rung = ladder[i];
+ const next = ladder[i + 1];
try {
- debugLogger.debug("Attempting Vulkan backend startup");
+ debugLogger.debug(rung.attemptMsg);
await this._startWithBinary(
- binaryPaths.vulkan,
- gpuArgs,
- this._buildEnv(binaryPaths.vulkan),
- VULKAN_STARTUP_TIMEOUT_MS
+ rung.binary,
+ rung.args,
+ this._buildEnv(rung.binary),
+ rung.timeout
);
- this.activeBackend = "vulkan";
+ this.activeBackend = rung.backend;
+ this.activeDraftModelPath = rung.mtp ? this.draftModelPath : null;
return;
} catch (err) {
- debugLogger.warn("Vulkan backend failed, falling back to CPU", { error: err.message });
- await this._killCurrentProcess();
- this.port = await this.findAvailablePort();
+ lastError = err;
+ if (next) {
+ debugLogger.warn(`${rung.name} backend failed, falling back to ${next.name}`, {
+ error: err.message,
+ });
+ await this._killCurrentProcess();
+ this.port = await this.findAvailablePort();
+ }
}
}
- if (!binaryPaths.cpu) throw new Error("No CPU llama-server binary available");
-
- debugLogger.debug("Starting with CPU backend");
- await this._startWithBinary(
- binaryPaths.cpu,
- cpuArgs,
- this._buildEnv(binaryPaths.cpu),
- STARTUP_TIMEOUT_MS
- );
- this.activeBackend = "cpu";
+ throw lastError || new Error("No CPU llama-server binary available");
}
_buildEnv(binaryPath) {
@@ -554,6 +631,8 @@ class LlamaServerManager {
this.ready = false;
this.port = null;
this.modelPath = null;
+ this.draftModelPath = null;
+ this.activeDraftModelPath = null;
this.activeBackend = null;
}
diff --git a/src/helpers/modelManagerBridge.js b/src/helpers/modelManagerBridge.js
index 7020e9497..6a9f6dc78 100644
--- a/src/helpers/modelManagerBridge.js
+++ b/src/helpers/modelManagerBridge.js
@@ -206,6 +206,13 @@ class ModelManager {
};
}
+ async serverStartOptions(modelInfo) {
+ const options = this.serverOptions(modelInfo);
+ const draftPath = await this.resolveDraftPath(modelInfo.model);
+ if (draftPath) options.draftModelPath = draftPath;
+ return options;
+ }
+
async downloadModel(modelId, onProgress) {
this.ensureInitialized();
const modelInfo = this.findModelById(modelId);
@@ -236,7 +243,12 @@ class ModelManager {
try {
await this.ensureModelsDirExists();
- const requiredBytes = model.sizeBytes || model.sizeMb * 1_000_000 || 0;
+ const hasDrafter = this.modelHasDrafter(model);
+
+ let requiredBytes = model.sizeBytes || model.sizeMb * 1_000_000 || 0;
+ if (requiredBytes > 0 && hasDrafter) {
+ requiredBytes += model.draftSizeBytes;
+ }
if (requiredBytes > 0) {
const spaceCheck = await checkDiskSpace(this.modelsDir, requiredBytes * 1.2);
if (!spaceCheck.ok) {
@@ -251,20 +263,41 @@ class ModelManager {
const downloadUrl = this.getDownloadUrl(provider, model);
+ // With a drafter, weight progress across both files by declared bytes and
+ // clamp it so the bar never regresses across the phase boundary. Without a
+ // drafter, keep today's single-file progress exactly.
+ const combinedTotal = hasDrafter ? (model.sizeBytes || 0) + model.draftSizeBytes : 0;
+ let lastCombined = 0;
+ const emitCombined = (rawCombined) => {
+ let combined = Math.min(rawCombined, combinedTotal);
+ if (combined < lastCombined) combined = lastCombined;
+ else lastCombined = combined;
+ const progress = combinedTotal > 0 ? (combined / combinedTotal) * 100 : 0;
+ this.downloadProgress.set(modelId, {
+ modelId,
+ progress,
+ downloadedSize: combined,
+ totalSize: combinedTotal,
+ });
+ if (onProgress) onProgress(progress, combined, combinedTotal);
+ };
+
await sharedDownloadFile(downloadUrl, modelPath, {
signal,
- onProgress: (downloadedBytes, totalBytes) => {
- const progress = totalBytes > 0 ? (downloadedBytes / totalBytes) * 100 : 0;
- this.downloadProgress.set(modelId, {
- modelId,
- progress,
- downloadedSize: downloadedBytes,
- totalSize: totalBytes,
- });
- if (onProgress) {
- onProgress(progress, downloadedBytes, totalBytes);
- }
- },
+ onProgress: hasDrafter
+ ? (downloadedBytes) => emitCombined(downloadedBytes)
+ : (downloadedBytes, totalBytes) => {
+ const progress = totalBytes > 0 ? (downloadedBytes / totalBytes) * 100 : 0;
+ this.downloadProgress.set(modelId, {
+ modelId,
+ progress,
+ downloadedSize: downloadedBytes,
+ totalSize: totalBytes,
+ });
+ if (onProgress) {
+ onProgress(progress, downloadedBytes, totalBytes);
+ }
+ },
});
const stats = await fsPromises.stat(modelPath);
@@ -277,6 +310,29 @@ class ModelManager {
);
}
+ // Drafter is opportunistic: a failure or cancel here leaves the main model
+ // fully usable, so never fail the download or delete the main file.
+ if (hasDrafter) {
+ const draftPath = path.join(this.modelsDir, model.draftFileName);
+ try {
+ await sharedDownloadFile(this.getDraftDownloadUrl(provider, model), draftPath, {
+ signal,
+ onProgress: (downloadedBytes) => emitCombined(stats.size + downloadedBytes),
+ });
+ const draftStats = await fsPromises.stat(draftPath);
+ if (draftStats.size < MIN_FILE_SIZE) {
+ await fsPromises.unlink(draftPath).catch(() => {});
+ debugLogger.warn("MTP drafter file too small, keeping model without it", { modelId });
+ }
+ } catch (draftError) {
+ await fsPromises.unlink(draftPath).catch(() => {});
+ debugLogger.warn("MTP drafter download failed, keeping model without it", {
+ modelId,
+ error: draftError.message,
+ });
+ }
+ }
+
return modelPath;
} catch (error) {
if (error.isAbort) {
@@ -307,6 +363,24 @@ class ModelManager {
return `${baseUrl}/${model.hfRepo}/resolve/main/${model.fileName}`;
}
+ getDraftDownloadUrl(provider, model) {
+ const baseUrl = provider.baseUrl || "https://huggingface.co";
+ return `${baseUrl}/${model.draftHfRepo}/resolve/main/${model.draftFileName}`;
+ }
+
+ modelHasDrafter(model) {
+ return Boolean(model && model.draftHfRepo && model.draftFileName && model.draftSizeBytes);
+ }
+
+ // Opportunistic MTP drafter path: only when declared and the file passes the
+ // same >1MB validity gate as models. Returns null otherwise (start without MTP).
+ async resolveDraftPath(model) {
+ if (!this.modelHasDrafter(model)) return null;
+ const draftPath = path.join(this.modelsDir, model.draftFileName);
+ if (await this.checkModelValid(draftPath)) return draftPath;
+ return null;
+ }
+
cancelDownload(modelId) {
const entry = this.activeRequests.get(modelId);
if (entry) {
@@ -330,6 +404,12 @@ class ModelManager {
if (await this.checkFileExists(modelPath)) {
await fsPromises.unlink(modelPath);
}
+
+ // Remove the drafter too when present, best effort (ignore ENOENT).
+ if (modelInfo.model.draftFileName) {
+ const draftPath = path.join(this.modelsDir, modelInfo.model.draftFileName);
+ await fsPromises.unlink(draftPath).catch(() => {});
+ }
}
async deleteAllModels() {
@@ -409,7 +489,7 @@ class ModelManager {
serverReady: this.serverManager.ready,
});
- await this.serverManager.start(modelPath, this.serverOptions(modelInfo));
+ await this.serverManager.start(modelPath, await this.serverStartOptions(modelInfo));
this.currentServerModelId = modelId;
debugLogger.logReasoning("INFERENCE_SERVER_STARTED", {
@@ -479,7 +559,7 @@ class ModelManager {
if (!this.serverManager.isAvailable()) return false;
try {
- await this.serverManager.start(modelPath, this.serverOptions(modelInfo));
+ await this.serverManager.start(modelPath, await this.serverStartOptions(modelInfo));
this.currentServerModelId = modelId;
debugLogger.info("llama-server pre-warmed", { modelId });
return true;
diff --git a/src/models/ModelRegistry.ts b/src/models/ModelRegistry.ts
index 837c68967..81adc0f14 100644
--- a/src/models/ModelRegistry.ts
+++ b/src/models/ModelRegistry.ts
@@ -15,6 +15,10 @@ export interface ModelDefinition {
hfRepo: string;
recommended?: boolean;
supportsThinking?: boolean;
+ // Optional MTP speculative-decoding drafter downloaded alongside the main GGUF.
+ draftHfRepo?: string;
+ draftFileName?: string;
+ draftSizeBytes?: number;
}
export interface LocalProviderData {
diff --git a/src/models/modelRegistryData.json b/src/models/modelRegistryData.json
index f9b2b5b1a..732c953ed 100644
--- a/src/models/modelRegistryData.json
+++ b/src/models/modelRegistryData.json
@@ -981,13 +981,16 @@
{
"id": "gemma-4-31b-it-qat-q4_0",
"name": "Gemma 4 31B QAT",
- "size": "17.7GB",
+ "size": "17.9GB",
"sizeBytes": 17651001568,
"description": "Google's official QAT build, smaller with quality preserved",
"fileName": "gemma-4-31B_q4_0-it.gguf",
"quantization": "q4_0",
"contextLength": 262144,
"hfRepo": "google/gemma-4-31B-it-qat-q4_0-gguf",
+ "draftHfRepo": "unsloth/gemma-4-31B-it-qat-GGUF",
+ "draftFileName": "mtp-gemma-4-31B-it.gguf",
+ "draftSizeBytes": 279955968,
"descriptionKey": "models.descriptions.local.gemma_gemma_4_31b_it_qat_q4_0"
},
{
@@ -1005,13 +1008,16 @@
{
"id": "gemma-4-26b-a4b-it-qat-q4_0",
"name": "Gemma 4 26B MoE QAT",
- "size": "14.4GB",
+ "size": "14.7GB",
"sizeBytes": 14439363584,
"description": "Google's official QAT MoE build, smaller with quality preserved",
"fileName": "gemma-4-26B_q4_0-it.gguf",
"quantization": "q4_0",
"contextLength": 262144,
"hfRepo": "google/gemma-4-26B-A4B-it-qat-q4_0-gguf",
+ "draftHfRepo": "unsloth/gemma-4-26B-A4B-it-qat-GGUF",
+ "draftFileName": "mtp-gemma-4-26B-A4B-it.gguf",
+ "draftSizeBytes": 251939328,
"descriptionKey": "models.descriptions.local.gemma_gemma_4_26b_a4b_it_qat_q4_0"
},
{
@@ -1036,6 +1042,9 @@
"quantization": "q4_0",
"contextLength": 262144,
"hfRepo": "google/gemma-4-E4B-it-qat-q4_0-gguf",
+ "draftHfRepo": "unsloth/gemma-4-E4B-it-qat-GGUF",
+ "draftFileName": "mtp-gemma-4-E4B-it.gguf",
+ "draftSizeBytes": 59678016,
"recommended": true,
"descriptionKey": "models.descriptions.local.gemma_gemma_4_e4b_it_qat_q4_0"
},
@@ -1054,13 +1063,16 @@
{
"id": "gemma-4-e2b-it-qat-q4_0",
"name": "Gemma 4 E2B QAT",
- "size": "3.3GB",
+ "size": "3.4GB",
"sizeBytes": 3349516256,
"description": "Google's official compact QAT build, quality preserved",
"fileName": "gemma-4-E2B_q4_0-it.gguf",
"quantization": "q4_0",
"contextLength": 262144,
"hfRepo": "google/gemma-4-E2B-it-qat-q4_0-gguf",
+ "draftHfRepo": "unsloth/gemma-4-E2B-it-qat-GGUF",
+ "draftFileName": "mtp-gemma-4-E2B-it.gguf",
+ "draftSizeBytes": 59235648,
"descriptionKey": "models.descriptions.local.gemma_gemma_4_e2b_it_qat_q4_0"
},
{
diff --git a/test/helpers/gemmaMtpDrafter.test.js b/test/helpers/gemmaMtpDrafter.test.js
new file mode 100644
index 000000000..8904b265d
--- /dev/null
+++ b/test/helpers/gemmaMtpDrafter.test.js
@@ -0,0 +1,268 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Module = require("node:module");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+
+const modelManagerModulePath = require.resolve("../../src/helpers/modelManagerBridge.js");
+const originalLoad = Module._load;
+let electronHome = os.tmpdir();
+
+const QAT_ID = "gemma-4-e2b-it-qat-q4_0";
+const NON_QAT_ID = "gemma-4-e2b-it-q4_k_m";
+
+function loadModelManager() {
+ delete require.cache[modelManagerModulePath];
+
+ Module._load = function loadWithMocks(request) {
+ if (request === "electron") {
+ return {
+ app: {
+ isReady: () => true,
+ getAppPath: () => process.cwd(),
+ getPath: (name) => (name === "home" ? electronHome : path.join(electronHome, name)),
+ },
+ net: {},
+ };
+ }
+ return originalLoad.apply(this, arguments);
+ };
+
+ try {
+ return require("../../src/helpers/modelManagerBridge.js").default;
+ } finally {
+ Module._load = originalLoad;
+ }
+}
+
+async function withHome(prefix, fn) {
+ const home = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+ electronHome = home;
+ try {
+ return await fn(home);
+ } finally {
+ await fs.rm(home, { recursive: true, force: true });
+ }
+}
+
+const OVER_MIN = Buffer.alloc(1_000_001, 1); // > MIN_FILE_SIZE (1MB)
+const UNDER_MIN = Buffer.alloc(500, 1);
+
+test("modelHasDrafter is true only for entries declaring a drafter", () => {
+ const mm = loadModelManager();
+ const qat = mm.findModelById(QAT_ID).model;
+ const plain = mm.findModelById(NON_QAT_ID).model;
+ assert.equal(mm.modelHasDrafter(qat), true);
+ assert.equal(mm.modelHasDrafter(plain), false);
+ assert.equal(mm.modelHasDrafter(undefined), false);
+});
+
+test("getDraftDownloadUrl mirrors the main URL shape", () => {
+ const mm = loadModelManager();
+ const { model, provider } = mm.findModelById(QAT_ID);
+ assert.equal(
+ mm.getDraftDownloadUrl(provider, model),
+ `${provider.baseUrl}/${model.draftHfRepo}/resolve/main/${model.draftFileName}`
+ );
+});
+
+test("resolveDraftPath returns the path only when a valid drafter file exists", async () => {
+ await withHome("openwhispr-draft-resolve-", async () => {
+ const mm = loadModelManager();
+ mm.ensureInitialized();
+ await fs.mkdir(mm.modelsDir, { recursive: true });
+
+ const model = mm.findModelById(QAT_ID).model;
+ const draftPath = path.join(mm.modelsDir, model.draftFileName);
+
+ // Missing drafter → null (keeps today's behavior for pre-feature downloads).
+ assert.equal(await mm.resolveDraftPath(model), null);
+
+ // Too small → fails the >1MB gate → null.
+ await fs.writeFile(draftPath, UNDER_MIN);
+ assert.equal(await mm.resolveDraftPath(model), null);
+
+ // Valid drafter → returns the path.
+ await fs.writeFile(draftPath, OVER_MIN);
+ assert.equal(await mm.resolveDraftPath(model), draftPath);
+
+ // A model with no drafter declared → always null.
+ assert.equal(await mm.resolveDraftPath(mm.findModelById(NON_QAT_ID).model), null);
+ });
+});
+
+test("deleteModel removes the drafter alongside the main file, ignoring a missing drafter", async () => {
+ await withHome("openwhispr-draft-delete-", async () => {
+ const mm = loadModelManager();
+ mm.ensureInitialized();
+ await fs.mkdir(mm.modelsDir, { recursive: true });
+
+ const model = mm.findModelById(QAT_ID).model;
+ const mainPath = path.join(mm.modelsDir, model.fileName);
+ const draftPath = path.join(mm.modelsDir, model.draftFileName);
+
+ await fs.writeFile(mainPath, OVER_MIN);
+ await fs.writeFile(draftPath, OVER_MIN);
+
+ await mm.deleteModel(QAT_ID);
+ assert.equal(await mm.checkFileExists(mainPath), false);
+ assert.equal(await mm.checkFileExists(draftPath), false);
+
+ // Main present, drafter already gone → no throw.
+ await fs.writeFile(mainPath, OVER_MIN);
+ await mm.deleteModel(QAT_ID);
+ assert.equal(await mm.checkFileExists(mainPath), false);
+ });
+});
+
+test("llama-server start restarts only when model or drafter presence changes", async () => {
+ const LlamaServerManager = require("../../src/helpers/llamaServer.js");
+ const manager = new LlamaServerManager();
+
+ const calls = [];
+ manager._doStart = async (modelPath, options) => {
+ manager.ready = true;
+ manager.modelPath = modelPath;
+ manager.draftModelPath = options.draftModelPath || null;
+ calls.push({ modelPath, draftModelPath: manager.draftModelPath });
+ };
+
+ await manager.start("/models/main.gguf", {});
+ assert.equal(calls.length, 1);
+
+ // Same model, no drafter → no restart.
+ await manager.start("/models/main.gguf", {});
+ assert.equal(calls.length, 1);
+
+ // Drafter appears for the same model → restart.
+ await manager.start("/models/main.gguf", { draftModelPath: "/models/draft.gguf" });
+ assert.equal(calls.length, 2);
+ assert.equal(manager.draftModelPath, "/models/draft.gguf");
+
+ // Same model, same drafter → no restart.
+ await manager.start("/models/main.gguf", { draftModelPath: "/models/draft.gguf" });
+ assert.equal(calls.length, 2);
+
+ // Drafter disappears → restart.
+ await manager.start("/models/main.gguf", {});
+ assert.equal(calls.length, 3);
+ assert.equal(manager.draftModelPath, null);
+});
+
+// --- Degrade ladder for stale (pre-b9763) Vulkan binaries ---
+
+const LADDER_BASE_ARGS = ["--model", "/models/main.gguf", "--host", "127.0.0.1", "--port", "8221"];
+const LADDER_DRAFT_ARGS = [
+ "--model-draft",
+ "/models/draft.gguf",
+ "--spec-type",
+ "draft-mtp",
+ "--spec-draft-n-max",
+ "3",
+];
+
+// Builds a manager with _startWithBinary stubbed at the method boundary. shouldFail
+// receives a {binary, draft, gpu} descriptor and decides whether that rung throws.
+function makeLadderManager(shouldFail) {
+ const LlamaServerManager = require("../../src/helpers/llamaServer.js");
+ const manager = new LlamaServerManager();
+ const attempts = [];
+ manager.draftModelPath = "/models/draft.gguf";
+ manager._buildEnv = () => ({});
+ manager._killCurrentProcess = async () => {};
+ manager.findAvailablePort = async () => 8221;
+ manager._startWithBinary = async (binary, args) => {
+ const attempt = {
+ binary,
+ draft: args.includes("--model-draft"),
+ gpu: args.includes("--n-gpu-layers"),
+ };
+ attempts.push(attempt);
+ if (shouldFail(attempt)) throw new Error(`stub fail: ${binary} draft=${attempt.draft}`);
+ };
+ return { manager, attempts };
+}
+
+const LADDER_BINARIES = { vulkan: "/bin/vulkan", cpu: "/bin/cpu" };
+
+test("degrade ladder attempts GPU+MTP, GPU, CPU+MTP, CPU in that order", async () => {
+ const { manager, attempts } = makeLadderManager(() => true);
+ await assert.rejects(() =>
+ manager._startWithGpuFallback(LADDER_BINARIES, LADDER_BASE_ARGS, {}, LADDER_DRAFT_ARGS)
+ );
+ assert.deepEqual(attempts, [
+ { binary: "/bin/vulkan", draft: true, gpu: true },
+ { binary: "/bin/vulkan", draft: false, gpu: true },
+ { binary: "/bin/cpu", draft: true, gpu: false },
+ { binary: "/bin/cpu", draft: false, gpu: false },
+ ]);
+ assert.equal(manager.activeBackend, null);
+ assert.equal(manager.activeDraftModelPath, null);
+});
+
+test("stale vulkan (rejects MTP args) degrades to vulkan WITHOUT draft, not CPU", async () => {
+ const { manager, attempts } = makeLadderManager((a) => a.draft);
+ await manager._startWithGpuFallback(LADDER_BINARIES, LADDER_BASE_ARGS, {}, LADDER_DRAFT_ARGS);
+ assert.deepEqual(attempts, [
+ { binary: "/bin/vulkan", draft: true, gpu: true },
+ { binary: "/bin/vulkan", draft: false, gpu: true },
+ ]);
+ assert.equal(manager.activeBackend, "vulkan");
+ assert.equal(manager.activeDraftModelPath, null);
+});
+
+test("no drafter keeps today's vulkan->cpu order with no extra attempts", async () => {
+ const { manager, attempts } = makeLadderManager(() => true);
+ manager.draftModelPath = null;
+ await assert.rejects(() =>
+ manager._startWithGpuFallback(LADDER_BINARIES, LADDER_BASE_ARGS, {}, [])
+ );
+ assert.deepEqual(attempts, [
+ { binary: "/bin/vulkan", draft: false, gpu: true },
+ { binary: "/bin/cpu", draft: false, gpu: false },
+ ]);
+});
+
+test("degraded start does not churn on identical requests", async () => {
+ const LlamaServerManager = require("../../src/helpers/llamaServer.js");
+ const manager = new LlamaServerManager();
+
+ let starts = 0;
+ manager._doStart = async (modelPath, options) => {
+ starts++;
+ manager.ready = true;
+ manager.modelPath = modelPath;
+ manager.draftModelPath = options.draftModelPath || null; // REQUESTED, stays stable
+ manager.activeDraftModelPath = null; // simulate a degraded start (drafter dropped)
+ };
+
+ await manager.start("/models/main.gguf", { draftModelPath: "/models/draft.gguf" });
+ assert.equal(starts, 1);
+ assert.equal(manager.draftModelPath, "/models/draft.gguf");
+ assert.equal(manager.activeDraftModelPath, null);
+
+ // Identical request must NOT bounce the ready server despite the degrade.
+ await manager.start("/models/main.gguf", { draftModelPath: "/models/draft.gguf" });
+ assert.equal(starts, 1);
+});
+
+test("stop() clears both the requested and active draft paths", async () => {
+ const LlamaServerManager = require("../../src/helpers/llamaServer.js");
+ const manager = new LlamaServerManager();
+
+ manager.draftModelPath = "/models/draft.gguf";
+ manager.activeDraftModelPath = "/models/draft.gguf";
+ manager.ready = true;
+ manager.process = {
+ exitCode: undefined,
+ kill() {},
+ once(event, cb) {
+ if (event === "close") cb();
+ },
+ };
+
+ await manager.stop();
+ assert.equal(manager.draftModelPath, null);
+ assert.equal(manager.activeDraftModelPath, null);
+});
diff --git a/test/helpers/gemmaMtpRegistry.test.js b/test/helpers/gemmaMtpRegistry.test.js
new file mode 100644
index 000000000..0877050b2
--- /dev/null
+++ b/test/helpers/gemmaMtpRegistry.test.js
@@ -0,0 +1,80 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const modelData = require("../../src/models/modelRegistryData.json");
+
+const DRAFT_FIELDS = ["draftHfRepo", "draftFileName", "draftSizeBytes"];
+
+// Exact expected values for the four Gemma 4 QAT entries (HF tree API).
+const EXPECTED = {
+ "gemma-4-31b-it-qat-q4_0": {
+ size: "17.9GB",
+ sizeBytes: 17651001568,
+ draftHfRepo: "unsloth/gemma-4-31B-it-qat-GGUF",
+ draftFileName: "mtp-gemma-4-31B-it.gguf",
+ draftSizeBytes: 279955968,
+ },
+ "gemma-4-26b-a4b-it-qat-q4_0": {
+ size: "14.7GB",
+ sizeBytes: 14439363584,
+ draftHfRepo: "unsloth/gemma-4-26B-A4B-it-qat-GGUF",
+ draftFileName: "mtp-gemma-4-26B-A4B-it.gguf",
+ draftSizeBytes: 251939328,
+ },
+ "gemma-4-e4b-it-qat-q4_0": {
+ size: "5.2GB",
+ sizeBytes: 5154941280,
+ draftHfRepo: "unsloth/gemma-4-E4B-it-qat-GGUF",
+ draftFileName: "mtp-gemma-4-E4B-it.gguf",
+ draftSizeBytes: 59678016,
+ },
+ "gemma-4-e2b-it-qat-q4_0": {
+ size: "3.4GB",
+ sizeBytes: 3349516256,
+ draftHfRepo: "unsloth/gemma-4-E2B-it-qat-GGUF",
+ draftFileName: "mtp-gemma-4-E2B-it.gguf",
+ draftSizeBytes: 59235648,
+ },
+};
+
+function allLocalModels() {
+ return modelData.localProviders.flatMap((provider) =>
+ provider.models.map((model) => ({ provider, model }))
+ );
+}
+
+test("the four Gemma 4 QAT entries carry the exact drafter field triplets", () => {
+ const byId = new Map(allLocalModels().map(({ model }) => [model.id, model]));
+
+ for (const [id, expected] of Object.entries(EXPECTED)) {
+ const model = byId.get(id);
+ assert.ok(model, `missing QAT entry ${id}`);
+ assert.equal(model.size, expected.size, `${id} size label`);
+ assert.equal(model.sizeBytes, expected.sizeBytes, `${id} main sizeBytes unchanged`);
+ assert.equal(model.draftHfRepo, expected.draftHfRepo, `${id} draftHfRepo`);
+ assert.equal(model.draftFileName, expected.draftFileName, `${id} draftFileName`);
+ assert.equal(model.draftSizeBytes, expected.draftSizeBytes, `${id} draftSizeBytes`);
+ }
+});
+
+test("no entry outside the four QAT ids gained any drafter field", () => {
+ for (const { model } of allLocalModels()) {
+ if (EXPECTED[model.id]) continue;
+ for (const field of DRAFT_FIELDS) {
+ assert.equal(
+ model[field],
+ undefined,
+ `${model.id} unexpectedly has ${field}=${model[field]}`
+ );
+ }
+ }
+});
+
+test("combined size label equals (main + drafter) bytes rounded to one decimal", () => {
+ const byId = new Map(allLocalModels().map(({ model }) => [model.id, model]));
+ for (const id of Object.keys(EXPECTED)) {
+ const model = byId.get(id);
+ const combined = (model.sizeBytes + model.draftSizeBytes) / 1e9;
+ assert.equal(model.size, `${combined.toFixed(1)}GB`, `${id} combined size label`);
+ }
+});