Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: honor a cleared or disabled speculative decoding setting (#5696)

Daniel Hanb3c401087846
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index b324e8bec40..573abc3ff89 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -5402,6 +5402,8 @@ def _build_ngram_mod_flags(
n_match: int = 24,
n_min: int = 48,
n_max: int = 64,
+ *,
+ chain_with_mtp: bool = False,
) -> list[str]:
"""Emit the right ngram-mod knob flags for the running llama-server.
@@ -5411,6 +5413,9 @@ def _build_ngram_mod_flags(
``probe_server_capabilities``; ``ngram_mod_flavor`` says which set is
real (vs a removal-stub). Returns ``[]`` when neither is available so
the caller can drop ngram-mod entirely.
+
+ ``chain_with_mtp`` omits the legacy ``--draft-min``/``--draft-max`` pair,
+ which a chained MTP invocation owns and would otherwise invert.
"""
flavor = caps.get("ngram_mod_flavor") if caps else None
if flavor == "new":
@@ -5425,14 +5430,10 @@ def _build_ngram_mod_flags(
if flavor == "legacy":
# Pre-rename llama.cpp: same knobs lived under --spec-ngram-size-n
# (lookup length) and generic --draft-min / --draft-max (N range).
- return [
- "--spec-ngram-size-n",
- str(n_match),
- "--draft-min",
- str(n_min),
- "--draft-max",
- str(n_max),
- ]
+ flags = ["--spec-ngram-size-n", str(n_match)]
+ if not chain_with_mtp:
+ flags.extend(["--draft-min", str(n_min), "--draft-max", str(n_max)])
+ return flags
return []
@@ -5456,6 +5457,9 @@ _LEGACY_SPEC_MODE_MAP = {
"draft-dspark": "dspark",
"draft-dflash": "dflash",
"ngram-mod": "ngram",
+ "none": "off",
+ "disable": "off",
+ "disabled": "off",
}
@@ -6854,10 +6858,9 @@ class LlamaCppBackend:
):
return False
# Same rule for the tuning group: requested against requested, so a server
- # launched with a different value is a reload. Compared even when the
- # intent is blank, unlike spec_draft_n_max above: blank is the llama.cpp
- # default and both sides hold what was requested, so two loads that asked
- # for nothing still match, while clearing a knob relaunches.
+ # launched with a different value is a reload. A blank value is the llama.cpp
+ # default, so two loads that asked for nothing still match, while clearing a
+ # knob relaunches.
if not self._is_diffusion and (
_normalized_load_mode(self._requested_load_mode)
!= _normalized_load_mode(intent.load_mode)
@@ -6993,7 +6996,7 @@ class LlamaCppBackend:
# The stand-down the UI asks the user to fix by updating llama.cpp. That leaves
# the request identical, so without this the repaired load never happens.
if (
- speculative_type in ("auto", "mtp", "mtp+ngram", "dspark", "dflash")
+ speculative_type in ("auto", "mtp", "mtp+ngram", "dspark", "dflash", "ngram")
and self.spec_binary_fallback_can_retry()
):
return False
@@ -7021,18 +7024,19 @@ class LlamaCppBackend:
# The MTP-free recovery clears the runtime value but retains the
# user's prior value in its intent. Only a changed value should retry MTP.
compared_draft_n_max = self._last_load_intent.spec_draft_n_max
- if (
- (
- self._speculative_type in ("draft-mtp", "draft-dspark", "draft-dflash")
- # Auto's Hybrid Mamba partial-offload stand-down engaged nothing, so the
- # types above cannot see it -- yet the depth is what priced the rollback
- # copies that made the placement partial, so a change can re-enable MTP.
- or self._spec_fallback_reason in ("runtime_error", "mtp_partial_offload")
- )
- and intent.spec_draft_n_max is not None
- and intent.spec_draft_n_max != (compared_draft_n_max or 0)
- ):
- return False
+ draft_depth_matters = (
+ self._speculative_type in ("draft-mtp", "draft-dspark", "draft-dflash")
+ # Auto's Hybrid Mamba partial-offload stand-down engaged nothing, so the
+ # types above cannot see it. The depth priced the rollback copies that
+ # made the placement partial, so a change can re-enable MTP.
+ or self._spec_fallback_reason in ("runtime_error", "mtp_partial_offload")
+ )
+ if draft_depth_matters:
+ requested_draft_n_max = intent.spec_draft_n_max
+ if (requested_draft_n_max is None) != (compared_draft_n_max is None):
+ return False
+ if requested_draft_n_max is not None and requested_draft_n_max != compared_draft_n_max:
+ return False
if (self._chat_template_override or None) != (intent.chat_template_override or None):
return False
@@ -24743,7 +24747,7 @@ class LlamaCppBackend:
spec_value = mtp_token
ngram_knobs: list[str] = []
if chain_ngram:
- ngram_knobs = _build_ngram_mod_flags(caps)
+ ngram_knobs = _build_ngram_mod_flags(caps, chain_with_mtp = True)
if ngram_knobs:
spec_value = f"ngram-mod,{mtp_token}"
else:
@@ -24760,6 +24764,19 @@ class LlamaCppBackend:
def _emit_ngram_mod() -> bool:
"""Append --spec-type ngram-mod + flag-set knobs."""
+ if not caps.get("supports_ngram_mod"):
+ logger.warning(
+ "Requested ngram-mod speculative decoding but llama-server "
+ "does not advertise ngram-mod support; run `unsloth studio "
+ "update`. Loading without speculative decoding."
+ )
+ # The stand-down the warning tells the user to fix, recorded so the
+ # update actually takes: an unrecorded one leaves the picker adopting
+ # this process forever. "binary_outdated" rather than "binary_no_mtp"
+ # because the retry rule for that one asks _SPEC_KIND_CAPABILITY about
+ # _spec_drafter_kind, which ngram-mod never sets, having no drafter.
+ self._spec_fallback_reason = "binary_outdated"
+ return False
ngram_knobs = _build_ngram_mod_flags(caps)
flags.extend(["--spec-type", "ngram-mod"])
if not ngram_knobs:
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index d4fef26ebe7..cd716b672a0 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -1214,6 +1214,11 @@ def test_build_ngram_mod_flags_legacy():
assert flags == ["--spec-ngram-size-n", "24", "--draft-min", "48", "--draft-max", "64"]
+def test_build_ngram_mod_flags_legacy_chain_omits_shared_draft_range():
+ flags = _build_ngram_mod_flags({"ngram_mod_flavor": "legacy"}, chain_with_mtp = True)
+ assert flags == ["--spec-ngram-size-n", "24"]
+
+
def test_build_ngram_mod_flags_empty_when_unsupported():
assert _build_ngram_mod_flags({"ngram_mod_flavor": None}) == []
assert _build_ngram_mod_flags(None) == []
@@ -1282,10 +1287,18 @@ def _draft_n_max_matches(
def test_already_in_target_state_matches_when_draft_n_max_unset():
- # None on the request means "platform default"; matches any backend.
+ # Both sides use the platform default.
assert _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = None), None)
+def test_already_in_target_state_clears_explicit_draft_n_max_to_default():
+ assert not _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = 4), None)
+
+
+def test_already_in_target_state_sets_draft_n_max_from_default():
+ assert not _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = None), 4)
+
+
def test_already_in_target_state_matches_when_draft_n_max_equals_backend():
assert _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = 4), 4)
@@ -1294,6 +1307,10 @@ def test_mtp_draft_n_max_mismatch_survives_active_runtime_state():
assert not _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = 4), 8, speculative_type = "mtp")
+def test_auto_promoted_mtp_draft_n_max_change_forces_reload():
+ assert not _draft_n_max_matches(_mtp_backend(_spec_draft_n_max = 4), 8)
+
+
@pytest.mark.parametrize(
("saved_draft_n_max", "expected_match"),
[(8, True), (4, False), (None, False)],
@@ -1542,6 +1559,9 @@ def test_backfill_usage_from_timings_passthrough_when_timings_empty():
("draft-mtp", "mtp"),
("draft-dspark", "dspark"),
("ngram-mod", "ngram"),
+ ("none", "off"),
+ ("disable", "off"),
+ ("disabled", "off"),
# Comma-chained legacy values (e.g. from persisted state) collapse
# to the right canonical mode.
("ngram-mod,draft-mtp", "mtp+ngram"),
@@ -1691,6 +1711,94 @@ def test_build_speculative_flags_matrix(
assert "--spec-ngram-mod-n-match" not in parsed
+def test_build_speculative_flags_legacy_mtp_ngram_has_one_draft_max(monkeypatch):
+ caps = {
+ "found": True,
+ "mtp_token": "mtp",
+ "supports_mtp": True,
+ "supports_dspark": False,
+ "mtp_probe_inconclusive": False,
+ "ngram_mod_flavor": "legacy",
+ "supports_ngram_mod": True,
+ "spec_draft_n_max_flag": "--draft-max",
+ }
+ monkeypatch.setattr(
+ LlamaCppBackend,
+ "probe_server_capabilities",
+ classmethod(lambda cls, binary = None: caps),
+ )
+ backend = LlamaCppBackend()
+ backend._nextn_predict_layers = 1
+ flags = backend._build_speculative_flags(
+ speculative_type = "mtp+ngram",
+ spec_draft_n_max = 2,
+ extra_args = None,
+ model_identifier = _MTP_MODEL,
+ model_path = None,
+ gpus = True,
+ binary = "/fake/llama-server",
+ )
+ draft_max_positions = [i for i, flag in enumerate(flags) if flag == "--draft-max"]
+ assert len(draft_max_positions) == 1
+ assert flags[draft_max_positions[0] + 1] == "2"
+ assert "--draft-min" not in flags
+
+
+def test_forced_ngram_without_binary_support_skips_spec(monkeypatch):
+ backend = _resolver_backend(monkeypatch, ngram_supported = False)
+ flags = backend._build_speculative_flags(
+ speculative_type = "ngram",
+ spec_draft_n_max = None,
+ extra_args = None,
+ model_identifier = _NON_MTP_MODEL,
+ model_path = None,
+ gpus = True,
+ binary = "/fake/llama-server",
+ )
+ assert "--spec-type" not in flags
+ assert backend.speculative_type is None
+ assert backend.requested_spec_mode == "ngram"
+ # The warning tells the user to update llama.cpp, so the stand-down has to be
+ # recorded or the update cannot reach a resident process: the reload comparator
+ # dedupes an identical request, and the picker never even sends one.
+ assert backend._spec_fallback_reason == "binary_outdated"
+
+
+def test_forced_ngram_stand_down_reloads_once_the_binary_changes(monkeypatch):
+ backend = _resolver_backend(monkeypatch, ngram_supported = False)
+ backend._build_speculative_flags(
+ speculative_type = "ngram",
+ spec_draft_n_max = None,
+ extra_args = None,
+ model_identifier = _NON_MTP_MODEL,
+ model_path = None,
+ gpus = True,
+ binary = "/fake/llama-server",
+ )
+ backend._launch_binary_revision = "before-the-update"
+ # An untouched binary advertises nothing new, so the repair must not fire on every
+ # Apply; only a replaced one reopens the load.
+ monkeypatch.setattr(type(backend), "_binary_changed_since_launch", lambda self: False)
+ assert not backend.spec_binary_fallback_can_retry()
+ monkeypatch.setattr(type(backend), "_binary_changed_since_launch", lambda self: True)
+ assert backend.spec_binary_fallback_can_retry()
+
+
+def test_forced_ngram_with_binary_support_emits_spec(monkeypatch):
+ backend = _resolver_backend(monkeypatch, ngram_supported = True)
+ flags = backend._build_speculative_flags(
+ speculative_type = "ngram",
+ spec_draft_n_max = None,
+ extra_args = None,
+ model_identifier = _NON_MTP_MODEL,
+ model_path = None,
+ gpus = True,
+ binary = "/fake/llama-server",
+ )
+ assert _flags_dict(flags).get("--spec-type") == "ngram-mod"
+ assert backend.speculative_type == "ngram-mod"
+
+
def test_build_speculative_flags_user_extra_args_owns_spec_type(monkeypatch):
# User --spec-type in extra_args bypasses the dropdown entirely.
backend = _resolver_backend(monkeypatch)
diff --git a/studio/backend/tests/test_model_override_schema_compatibility.py b/studio/backend/tests/test_model_override_schema_compatibility.py
index f3ac00eea65..c91414a0f66 100644
--- a/studio/backend/tests/test_model_override_schema_compatibility.py
+++ b/studio/backend/tests/test_model_override_schema_compatibility.py
@@ -346,3 +346,20 @@ def test_two_keys_that_fold_together_resolve_to_nothing(override_store):
settings.set_model_override("C:\\models\\FOO.gguf", max_seq_length = 8192)
assert settings.resolve_model_override_key("c:/models/foo.gguf") is None
+
+
+def test_the_disable_aliases_survive_override_normalization():
+ """llama.cpp's own "none", plus "disable" / "disabled", reach /load as off.
+
+ ``_clean_str`` drops anything outside the whitelist, so leaving them out filed an
+ explicit disable as no override at all and the model followed the global
+ preference, which enables a drafter whenever that preference is Auto.
+ """
+ for spelling in ("none", "None", " DISABLE ", "disabled"):
+ normalized = settings.normalize_model_override({"speculative_type": spelling})
+ assert normalized.get("speculative_type") == spelling.strip().lower(), spelling
+
+ # An unknown spelling is still dropped, so this widens the set rather than the rule.
+ assert "speculative_type" not in settings.normalize_model_override(
+ {"speculative_type": "bogus"}
+ )
diff --git a/studio/backend/utils/openai_auto_switch_settings.py b/studio/backend/utils/openai_auto_switch_settings.py
index 12dcb206cb1..c32b3122c62 100644
--- a/studio/backend/utils/openai_auto_switch_settings.py
+++ b/studio/backend/utils/openai_auto_switch_settings.py
@@ -426,6 +426,11 @@ VALID_SPECULATIVE_TYPES = frozenset(
"draft-dflash",
"ngram-mod",
"ngram-simple",
+ # /load canonicalizes these three to "off"; without them here _clean_str
+ # drops the field, so a saved disable became no override at all.
+ "none",
+ "disable",
+ "disabled",
}
)
# Only these consume spec_draft_n_max (mirrors DRAFT_N_MAX_SPEC_TYPES in the UI).
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 9f620cf4f58..b1c15bc581f 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -426,7 +426,7 @@ function specFallbackMessage({
updateAvailable,
}: {
reason: string;
- drafter: "MTP" | "DSpark" | "DFlash";
+ drafter: "MTP" | "DSpark" | "DFlash" | "ngram-mod";
isLocalGguf: boolean;
updateAvailable: boolean;
}): string {
@@ -565,15 +565,22 @@ export function ChatSettingsPanel({
const speculativeType = useChatRuntimeStore((s) => s.speculativeType);
const specFallbackReason = useChatRuntimeStore((s) => s.specFallbackReason);
const specDrafterKind = useChatRuntimeStore((s) => s.specDrafterKind);
+ const loadedSpeculativeType = useChatRuntimeStore(
+ (s) => s.loadedSpeculativeType,
+ );
// The loaded model's own kind, not the pending control: the notice explains a
// fallback that already happened, so a staged edit (or a preset applied without
// a reload) must not re-label it and point at the wrong file.
- const speculativeDrafterLabel: "MTP" | "DSpark" | "DFlash" =
- (specDrafterKind ?? speculativeType) === "dspark"
- ? "DSpark"
- : (specDrafterKind ?? speculativeType) === "dflash"
- ? "DFlash"
- : "MTP";
+ const speculativeDrafterLabel: "MTP" | "DSpark" | "DFlash" | "ngram-mod" =
+ // The LOADED mode, per the comment above. Before the drafter kind, not after:
+ // ngram-mod opens none, so spec_drafter_kind still holds the MTP resolution's.
+ loadedSpeculativeType === "ngram"
+ ? "ngram-mod"
+ : (specDrafterKind ?? speculativeType) === "dspark"
+ ? "DSpark"
+ : (specDrafterKind ?? speculativeType) === "dflash"
+ ? "DFlash"
+ : "MTP";
const mtpUpdatable =
specFallbackReason === "binary_no_mtp" ||
specFallbackReason === "binary_outdated";
@@ -609,7 +616,10 @@ export function ChatSettingsPanel({
speculativeType === "mtp" ||
speculativeType === "mtp+ngram" ||
speculativeType === "dspark" ||
- speculativeType === "dflash");
+ speculativeType === "dflash" ||
+ // ngram-mod runs no drafter, so only the binary stand-down reaches it. Without
+ // this the panel shows ngram selected, no speculation running, and no reason.
+ speculativeType === "ngram");
const showContextVramWarning =
!isExternalModel &&
isGguf &&
diff --git a/studio/frontend/src/features/chat/lib/resident-config-match.ts b/studio/frontend/src/features/chat/lib/resident-config-match.ts
index 51f4eba2592..8b45a48448d 100644
--- a/studio/frontend/src/features/chat/lib/resident-config-match.ts
+++ b/studio/frontend/src/features/chat/lib/resident-config-match.ts
@@ -44,6 +44,7 @@ type ResidentRuntime = Pick<
| "gpu_placement_paravirtual"
| "tensor_split"
| "cpu_fallback_reason"
+ | "spec_fallback_reason"
>;
function sameList(
@@ -223,9 +224,15 @@ export function residentSpeculativeNeedsRepair(
) {
return true;
}
+ // ngram-mod is not in SPECULATIVE_MODES because it runs no drafter, so none of the
+ // drafter arms can repair it. It does still stand down on a build that does not
+ // advertise the mode, and that one records "binary_outdated", which an update repairs.
+ const modeCanRepair =
+ SPECULATIVE_MODES.has(mode) ||
+ (mode === "ngram" && status.spec_fallback_reason === "binary_outdated");
if (
!RETRYABLE_SPEC_FALLBACKS.has(status.spec_fallback_reason ?? "") ||
- !SPECULATIVE_MODES.has(mode)
+ !modeCanRepair
) {
return false;
}
@@ -313,11 +320,16 @@ const SETTING_CHECKS: SettingCheck[] = [
standing.speculativeType),
},
{
- // Only when the pick names one, as _runtime_matches_intent is guarded on
- // `intent.spec_draft_n_max is not None`: an unset limit asks for no change, so
- // comparing null against the count the resident load was launched with was a reload.
- pinned: (c) => c.specDraftNMax != null,
- agrees: (c, s) => c.specDraftNMax === (s.spec_draft_n_max ?? null),
+ // Pinned like the rest: _runtime_matches_intent reloads for the null-against-explicit
+ // flip, so an unset limit asks for the default. No `draft_depth_matters` gate here,
+ // as the status carries a count only when a depth-consuming load recorded an override.
+ pinned: () => true,
+ agrees: (c, s) =>
+ // The MTP-free recovery clears the runtime value while _runtime_matches_intent
+ // still compares against _last_load_intent's count, so null here is "unknown",
+ // not "the default". Let /load answer, as RETRYABLE_SPEC_FALLBACKS assumes.
+ s.spec_fallback_reason !== "runtime_error" &&
+ (c.specDraftNMax ?? null) === (s.spec_draft_n_max ?? null),
},
{
chatOnly: true,
@@ -349,11 +361,11 @@ const SETTING_CHECKS: SettingCheck[] = [
},
{
chatOnly: true,
- // Always pinned, unlike spec_draft_n_max: the status echoes what the load
- // REQUESTED, so a resident server that asked for nothing reports null and a
- // blank control agrees with it. Reading blank as "no opinion" instead would
- // mean clearing the dtype back to the f16 default never relaunched, leaving
- // the server on the quantized draft cache the panel no longer shows.
+ // Always pinned: the status echoes what the load requested, so a resident server
+ // that asked for nothing reports null and a blank control agrees with it. Reading
+ // blank as "no opinion" instead would mean clearing the dtype back to the f16
+ // default never relaunched, leaving the server on the quantized draft cache the
+ // panel no longer shows.
pinned: () => true,
agrees: (c, s) =>
(c.specDraftCacheDtype ?? null) ===
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index aab7e2375a4..31975aa00c4 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -2133,7 +2133,13 @@ export function normalizeSpeculativeType(
const s = String(v).trim().toLowerCase();
if (!s) return null;
if (s === "auto" || s === "default") return "auto";
- if (s === "off") return "off";
+ // The same four spellings _LEGACY_SPEC_MODE_MAP reads as "off". A stored override
+ // reaches here raw (model-overrides.ts binds speculative_type unnormalized), so
+ // falling through to Auto would compare Auto against a status the backend already
+ // canonicalised to "off" and re-send /load on every pick.
+ if (s === "off" || s === "none" || s === "disable" || s === "disabled") {
+ return "off";
+ }
if (s === "mtp" || s === "draft-mtp") return "mtp";
if (s === "dspark" || s === "draft-dspark") return "dspark";
if (s === "dflash" || s === "draft-dflash") return "dflash";
diff --git a/studio/frontend/src/features/model-picker/model-config/per-model-config.ts b/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
index 28954fe1e17..e19938dac94 100644
--- a/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
+++ b/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
@@ -439,7 +439,9 @@ function canonicalizeSpeculativeType(value: string): string | null {
if (s === "auto" || s === "default") {
return null;
}
- if (s === "off") {
+ // _LEGACY_SPEC_MODE_MAP's four. A stored override arrives raw, and the null below
+ // is "follow the global preference", which would enable a drafter under Auto.
+ if (s === "off" || s === "none" || s === "disable" || s === "disabled") {
return "off";
}
if (s === "mtp" || s === "draft-mtp") {
diff --git a/studio/frontend/tests/per-model-spec-disable-aliases.test.ts b/studio/frontend/tests/per-model-spec-disable-aliases.test.ts
new file mode 100644
index 00000000000..704d177d565
--- /dev/null
+++ b/studio/frontend/tests/per-model-spec-disable-aliases.test.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { normalizePerModelConfig } = await import(
+ "../src/features/model-picker/model-config/per-model-config.ts"
+);
+
+const specOf = (value: string) =>
+ normalizePerModelConfig({ speculativeType: value }).speculativeType;
+
+/**
+ * A server-side override reaches this canonicalizer with whatever the API caller
+ * wrote, and `/settings` stores `speculative_type` without canonicalizing it. The
+ * backend reads llama.cpp's own "none", plus "disable" / "disabled", as off. Here
+ * null does not mean off, it means follow the global preference, so a spelling that
+ * fell through would turn an explicit disable into Auto and hand the load a drafter.
+ */
+test("a stored disable alias is an override, not a fall-through to the global default", () => {
+ for (const spelling of [
+ "off",
+ "none",
+ "None",
+ "NONE",
+ " none ",
+ "disable",
+ "Disabled",
+ "disabled",
+ ]) {
+ assert.equal(specOf(spelling), "off", `${spelling} must read as off`);
+ }
+});
+
+test("the rest of the mapping still resolves as before", () => {
+ // "auto" and an unknown value are the follow-global sentinel, which is what the
+ // aliases above must not be confused with.
+ assert.equal(specOf("auto"), null);
+ assert.equal(specOf("default"), null);
+ assert.equal(specOf("bogus"), null);
+ assert.equal(specOf("mtp"), "mtp");
+ assert.equal(specOf("draft-mtp"), "mtp");
+ assert.equal(specOf("ngram-mod"), "ngram");
+ assert.equal(specOf("mtp+ngram"), "mtp+ngram");
+});
diff --git a/studio/frontend/tests/resident-config-match.test.ts b/studio/frontend/tests/resident-config-match.test.ts
index 5d3ebdf3fcb..725247c990b 100644
--- a/studio/frontend/tests/resident-config-match.test.ts
+++ b/studio/frontend/tests/resident-config-match.test.ts
@@ -1439,11 +1439,10 @@ test("unset nullable settings ask for the default, not for the resident value",
`${key} pinned on the resident load must not be adopted by a blank config`,
);
}
- // spec_draft_n_max is the exception, and it is the backend's: _runtime_matches_intent
- // rejects a draft-count difference only when `intent.spec_draft_n_max is not None`, so
- // an unset limit asks for no change and /load answers already_loaded. Reloading for it
- // could not deliver the default anyway, since that same answer leaves the count alone.
- assert.equal(matches({ ...DEFAULTS, spec_draft_n_max: 16 }, BLANK), true);
+ // spec_draft_n_max is no exception either: _runtime_matches_intent rejects the
+ // null-against-explicit flip, so a blank pick against a resident override reloads and
+ // that reload does deliver the platform default.
+ assert.equal(matches({ ...DEFAULTS, spec_draft_n_max: 16 }, BLANK), false);
assert.equal(
matches(
{ ...DEFAULTS, spec_draft_n_max: 16 },
@@ -1770,3 +1769,102 @@ test("selectModel asks about a repairable drafter before adopting", () => {
);
assert.ok(repairCheck < confirmPrompt);
});
+
+/**
+ * The store's mapping is what the comparator runs on both sides, so it has to agree with
+ * the backend's `_LEGACY_SPEC_MODE_MAP`. A stored per-model override reaches the config
+ * unnormalized (`model-overrides.ts` binds `speculative_type` straight through), so a
+ * spelling the backend canonicalises to "off" must not read as Auto here: the comparator
+ * would then weigh Auto against a status already reading "off" and re-send /load on every
+ * pick. The store cannot be imported in this suite, its module graph reaching the auth
+ * pages, so the function is lifted out of the source the way chat-model-residency.test.ts
+ * reads it -- but evaluated, so this asserts behavior rather than spelling.
+ */
+test("the speculative normalizer reads llama.cpp's disable spellings as off", () => {
+ const store = readFileSync(
+ new URL(
+ "../src/features/chat/stores/chat-runtime-store.ts",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ const start = store.indexOf("export function normalizeSpeculativeType");
+ assert.ok(start > 0, "normalizeSpeculativeType moved; follow it here");
+ const source = store
+ .slice(start, store.indexOf("\n}\n", start) + 2)
+ .replace("export function", "function")
+ .replace(" v: string | null | undefined,\n): string | null {", "v) {");
+ const normalize = new Function(
+ `${source}; return normalizeSpeculativeType;`,
+ )() as (v: string | null | undefined) => string | null;
+
+ for (const spelling of [
+ "off",
+ "none",
+ "None",
+ "NONE",
+ " none ",
+ "disable",
+ "Disabled",
+ "disabled",
+ ]) {
+ assert.equal(normalize(spelling), "off", `${spelling} must read as off`);
+ }
+ // The rest of the mapping is untouched, so an alias cannot swallow a real mode.
+ assert.equal(normalize("default"), "auto");
+ assert.equal(normalize("draft-mtp"), "mtp");
+ assert.equal(normalize("mtp+ngram"), "mtp+ngram");
+ assert.equal(normalize("bogus"), "auto");
+ assert.equal(normalize(null), null);
+});
+
+/**
+ * Forced ngram-mod on a build that does not advertise the mode stands down and records
+ * "binary_outdated". The settings comparison cannot see that -- the request the picker
+ * would send is identical to the one that stood down -- so the repair check is the only
+ * thing that reloads onto an updated llama.cpp. ngram-mod runs no drafter, so this is the
+ * one reason that reaches it.
+ */
+test("a forced ngram stand-down reloads onto an updated binary", () => {
+ const stoodDown = {
+ spec_fallback_reason: "binary_outdated",
+ spec_fallback_binary_changed: true,
+ };
+ assert.equal(residentSpeculativeNeedsRepair(stoodDown, "ngram"), true);
+ // Same shape as every other binary stand-down: an unchanged binary repairs nothing,
+ // so the prompt must not fire on each re-pick.
+ assert.equal(
+ residentSpeculativeNeedsRepair(
+ { ...stoodDown, spec_fallback_binary_changed: false },
+ "ngram",
+ ),
+ false,
+ );
+ // A healthy forced-ngram runtime still adopts.
+ assert.equal(
+ residentSpeculativeNeedsRepair({ spec_fallback_reason: null }, "ngram"),
+ false,
+ );
+});
+
+/**
+ * The MTP-free recovery clears `_spec_draft_n_max` while `_runtime_matches_intent`
+ * keeps comparing against the count retained in `_last_load_intent`, so the status
+ * reports null for a load the backend still measures against 8. Reading that null as
+ * "the platform default" would agree with a blank pick and skip the reload that
+ * clearing the override is supposed to cause.
+ */
+test("a runtime_error resident does not claim its draft depth is the default", () => {
+ const recovered = { ...DEFAULTS, spec_fallback_reason: "runtime_error" };
+ assert.equal(matches(recovered, BLANK), false);
+ assert.equal(matches(recovered, { ...BLANK, specDraftNMax: 8 }), false);
+ // Every other fallback still compares normally, so this costs one round trip in
+ // exactly the state whose depth the status cannot express.
+ for (const reason of [null, "binary_no_mtp", "drafter_not_found", "mtp_partial_offload"]) {
+ assert.equal(
+ matches({ ...DEFAULTS, spec_fallback_reason: reason }, BLANK),
+ true,
+ `${reason} must still adopt a default-against-default pick`,
+ );
+ }
+});
diff --git a/studio/frontend/tests/spec-fallback-partial-offload-copy.test.ts b/studio/frontend/tests/spec-fallback-partial-offload-copy.test.ts
index d40ab1c4800..f2937f704b7 100644
--- a/studio/frontend/tests/spec-fallback-partial-offload-copy.test.ts
+++ b/studio/frontend/tests/spec-fallback-partial-offload-copy.test.ts
@@ -43,3 +43,38 @@ test("the Hybrid Mamba partial-offload stand-down has its own notice", () => {
);
assert.match(copy, /with mtp|mtp('s)? (extra state|on)|would/i);
});
+
+/**
+ * A forced ngram-mod on a build that does not advertise the mode stands down and
+ * records "binary_outdated". The panel gates its notice on the resolved mode, so
+ * without "ngram" in that set the user sees ngram still selected, no speculation
+ * running, and neither the reason nor the update button.
+ */
+test("the forced-ngram stand-down reaches the settings notice", () => {
+ const gate = settings.match(/const showSpecFallback =[\s\S]*?;\n/);
+ assert.ok(gate, "showSpecFallback moved");
+ assert.match(gate[0], /speculativeType === "ngram"/);
+
+ // And it must not be labelled MTP. ngram-mod opens no drafter, so
+ // spec_drafter_kind still holds whatever the MTP resolution left behind; the
+ // requested mode has to win, which means it is tested before that field.
+ const label = settings.match(
+ /const speculativeDrafterLabel:[\s\S]*?;\n/,
+ );
+ assert.ok(label, "speculativeDrafterLabel moved");
+ assert.match(label[0], /"ngram-mod"/);
+ assert.ok(
+ label[0].indexOf('loadedSpeculativeType === "ngram"') <
+ label[0].indexOf("specDrafterKind"),
+ "the ngram check must precede the drafter-kind checks",
+ );
+
+ // And it reads the LOADED mode, not the pending control. Staging ngram over a
+ // resident MTP failure, or MTP over a forced-ngram stand-down, would otherwise
+ // relabel a notice that explains something already on disk.
+ assert.doesNotMatch(
+ label[0],
+ /(?<!loaded)[sS]peculativeType === "ngram"/,
+ "the label must come from loadedSpeculativeType",
+ );
+});