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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Stop `unsloth start claude` from opening with a model it cannot use (#10089)
Nilayc59cd2d0403b
diff --git a/studio/frontend/src/features/settings/components/agent-command.ts b/studio/frontend/src/features/settings/components/agent-command.tsindex 7b3df8c2c0f..83564b9ce89 100644--- a/studio/frontend/src/features/settings/components/agent-command.ts+++ b/studio/frontend/src/features/settings/components/agent-command.ts@@ -128,3 +128,114 @@ export function buildAgentShellCommands(dryRun: `${buildAgentCommand(base, null, os, "claude")} --no-launch`,};}++// Codex (/v1/responses) and Claude Code (/v1/messages) are llama-server only; the rest use+// /v1/chat/completions, which also serves safetensors and MLX.+export const GGUF_ONLY_AGENTS: readonly string[] = ["codex", "claude"];++export function agentRunsOnActiveModel(+ agent: string,+ isGguf: boolean,+): boolean {+ return isGguf || !GGUF_ONLY_AGENTS.includes(agent);+}++// The non-GGUF reset target: DEFAULT_AGENT is itself GGUF-only.+export const UNIVERSAL_AGENT = "opencode";++// Stays inside `offered`, or a narrower backend list names an agent with no chip. null =+// nothing offered runs.+export function fallbackAgent(+ isGguf: boolean,+ offered: readonly string[] = [],+): string | null {+ const runs = (agent: string) => agentRunsOnActiveModel(agent, isGguf);+ if (offered.length === 0) {+ return runs(DEFAULT_AGENT) ? DEFAULT_AGENT : UNIVERSAL_AGENT;+ }+ for (const preference of [DEFAULT_AGENT, UNIVERSAL_AGENT]) {+ if (offered.includes(preference) && runs(preference)) {+ return preference;+ }+ }+ return offered.find(runs) ?? null;+}++export function pickCompatibleAgent(+ detectedAgents: readonly string[],+ currentAgent: string,+ isGguf: boolean,+ offered: readonly string[] = [],+): string | null {+ const preferred = detectedAgents.find((agent) =>+ agentRunsOnActiveModel(agent, isGguf),+ );+ if (preferred) {+ return preferred;+ }+ return agentRunsOnActiveModel(currentAgent, isGguf)+ ? null+ : fallbackAgent(isGguf, offered);+}++// The server wins: only it sees a swap this tab did not make. The store covers the routes+// that never mount useChatModelRuntime, and the moment after a switch made here. null from+// both is unknown, which is not false and gates nothing.+export function resolveGgufCompatibility(+ fromStore: boolean | null,+ fromServer: boolean | null,+): boolean | null {+ return fromServer ?? fromStore;+}++// is_gguf carries a False default, so an idle server answers false while naming no model.+// Only a status that names what it holds is a verdict.+export function statusGgufVerdict(+ resident: string | null | undefined,+ isGguf: boolean | null | undefined,+): boolean | null {+ if (resident == null) return null;+ return isGguf ?? null;+}++// Same model, ignoring any ":quant" a caller pinned.+export function sameBaseModelId(a: string, b: string): boolean {+ const base = (id: string) => id.trim().toLowerCase().split(":")[0];+ return (+ a.trim().toLowerCase() === b.trim().toLowerCase() || base(a) === base(b)+ );+}++// The status and catalog polls run on separate timers, so a swap reaches one first; without+// this the panel pairs a newly named model with the previous verdict. Neither side naming+// anything is silence, not a contradiction.+export function verdictDescribesModel(+ resident: string | null | undefined,+ named: string | null | undefined,+): boolean {+ if (resident == null || named == null) return true;+ return sameBaseModelId(resident, named);+}++/** A status answer already collapsed onto the identity /v1/models publishes. */+export interface StatusAnswer {+ resident: string | null;+ isGguf: boolean | null;+}++// The panel's single compatibility rule; `status` is null when the last answer is not about+// the store state on screen. Disagreeing polls leave the question unknown rather than+// falling back to the store, which is blind to the very swap that caused the disagreement.+export function compatibilityFromSources(+ fromStore: boolean | null,+ status: StatusAnswer | null,+ namedModel: string | null,+): boolean | null {+ if (status === null) {+ return fromStore;+ }+ if (!verdictDescribesModel(status.resident, namedModel)) {+ return null;+ }+ return resolveGgufCompatibility(fromStore, status.isGguf);+}diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsxindex 116b6949ea9..066870abd5f 100644--- a/studio/frontend/src/features/settings/components/usage-examples.tsx+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx@@ -13,7 +13,12 @@ import {TooltipTrigger,} from "@/components/ui/tooltip";import { fetchDeviceType, usePlatformStore } from "@/config/env";-import { useChatRuntimeStore } from "@/features/chat";+import {+ getInferenceStatus,+ isExternalModelId,+ useChatRuntimeStore,+} from "@/features/chat";+import { publicModelId } from "@/features/hub";import { isServedByLlamaCpp } from "@/features/model-picker";import { useT } from "@/i18n";import type { TranslationKey } from "@/i18n";@@ -38,11 +43,17 @@ import { loadOpenAIAutoSwitchSettings } from "../api/openai-auto-switch";import { type OpenAIModel, listOpenAIModels } from "../api/openai-models";import { useSettingsPanelPrefsStore } from "../stores/settings-panel-prefs-store";import {+ agentRunsOnActiveModel,buildAgentCommand,+ compatibilityFromSources,+ fallbackAgent,isLoopbackHost,normalizeHost,+ pickCompatibleAgent,psSingle,+ sameBaseModelId,shSingle,+ statusGgufVerdict,} from "./agent-command";import { keylessBaseEligible } from "./keyless-example-eligibility";@@ -382,14 +393,6 @@ function looksLikePath(id: string): boolean {);}-// Same model, ignoring any ":quant" a caller pinned.-function sameBaseModelId(a: string, b: string): boolean {- const base = (id: string) => id.trim().toLowerCase().split(":")[0];- return (- a.trim().toLowerCase() === b.trim().toLowerCase() || base(a) === base(b)- );-}-// The model the examples name: always an id /v1 resolves against, null when there is none.function useExampleModelName(keylessOnly: boolean): string | null {const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);@@ -589,11 +592,109 @@ export function UsageExamples({// True once the user has picked an agent themselves; guards the detection// effect below from clobbering that choice if it resolves afterward.const agentPickedByUserRef = useRef(storedPrefs.apiExampleAgent != null);+ // isGguf at the moment of a hand-made pick, null if there has been none this session.+ // A manual pick is kept only until the model's GGUF-ness changes under it.+ const clickedUnderGgufRef = useRef<boolean | null>(null);const [useTunnel, setUseTunnel] = useState<boolean>(readUseTunnelPref);const origin = typeof window !== "undefined" ? window.location.origin : "";const base =useTunnel && cloudflareUrl ? cloudflareUrl : (serverUrl ?? origin);const localAgentDetection = canUseLocalAgentDetection(base);+ // isServedByLlamaCpp owns which store fields count; a context length is not among them,+ // since MLX reports one too.+ const activeGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);+ const activeNativePathToken = useChatRuntimeStore(+ (s) => s.activeNativePathToken,+ );+ const loadedIsGguf = useChatRuntimeStore((s) => s.loadedIsGguf);+ // null when these fields do not describe the model the snippet names: before status+ // lands they all read like a non-GGUF model, and under an external selection+ // use-chat-model-runtime stops updating them while the snippet still follows /v1/models.+ const activeCheckpoint = useChatRuntimeStore((s) => s.params.checkpoint);+ const storeIsGguf: boolean | null =+ !activeCheckpoint || isExternalModelId(activeCheckpoint)+ ? null+ : isServedByLlamaCpp({+ loadedIsGguf,+ activeGgufVariant,+ activeNativePathToken,+ checkpoint: activeCheckpoint,+ });++ // Only the chat and hub pages mount useChatModelRuntime, and local checkpoints are not+ // persisted, so off those routes the store never answers and the server has to. Tags the+ // answer below, so a switch made here invalidates it. JSON because each part can be a+ // path or a repo id, leaving no separator safe to assume absent.+ const storeModelKey = JSON.stringify([+ activeCheckpoint,+ activeGgufVariant,+ activeNativePathToken,+ ]);+ // Above the derivation below, which checks the verdict against the model named here.+ const keylessBase =+ !(useTunnel && cloudflareUrl) &&+ keylessBaseEligible(base, keylessScope, keylessExposure);+ const model = useExampleModelName(keylessBase && !apiKey);++ const [statusAnswer, setStatusAnswer] = useState<{+ key: string;+ resident: string | null;+ isGguf: boolean | null;+ } | null>(null);+ // useChatModelRuntime re-reads status on mount, on model-list changes and on focus,+ // never on a timer, so only this poll notices a swap made while the tab stays focused.+ useEffect(() => {+ let cancelled = false;+ let timeoutId: number | null = null;++ const update = () => {+ void getInferenceStatus()+ .then((status) => {+ if (cancelled) return false;+ // Two silences, both unknown, as the CLI gate reads them: a server that does+ // not report the field, and is_gguf's False default with no model named.+ const resident =+ status.active_model ?? status.model_identifier ?? null;+ const answer = statusGgufVerdict(resident, status.is_gguf);+ setStatusAnswer({ key: storeModelKey, resident, isGguf: answer });+ return answer !== null;+ })+ .catch(() => {+ // Keep the last answer: a failed probe is no evidence about the model.+ return false;+ })+ .then((resolved) => {+ if (cancelled) return;+ timeoutId = window.setTimeout(+ update,+ resolved ? CATALOG_IDLE_MS : CATALOG_RETRY_MS,+ );+ });+ };++ update();+ return () => {+ cancelled = true;+ if (timeoutId !== null) window.clearTimeout(timeoutId);+ };+ }, [storeModelKey]);++ // status reports active_model_name raw while /v1/models publishes public_model_id(...),+ // so collapse it the same way or a path-loaded model never matches and the verdict is+ // dropped for good. A stale key means the switch was made here, and the store is fresher.+ const isGguf: boolean | null = compatibilityFromSources(+ storeIsGguf,+ statusAnswer !== null && statusAnswer.key === storeModelKey+ ? {+ isGguf: statusAnswer.isGguf,+ resident:+ statusAnswer.resident === null+ ? null+ : publicModelId(statusAnswer.resident),+ }+ : null,+ model,+ );useEffect(() => {void fetchDeviceType({ force: true });@@ -613,6 +714,7 @@ export function UsageExamples({// longer targets a loopback base -- don't leave it selected, but// never touch a choice the user made by hand.if (!agentPickedByUserRef.current) {+ // The effect below corrects this; isGguf read here would be a stale closure.setAgent(DEFAULT_AGENT);}return;@@ -636,73 +738,56 @@ export function UsageExamples({};}, [localAgentDetection]);- // a restored agent this build no longer offers cannot build a command.+ // Drop a restored preference this build no longer offers, or that cannot run the model.useEffect(() => {if (!agentPickedByUserRef.current) return;+ if (isGguf === null) return;+ if (clickedUnderGgufRef.current === isGguf) return;if (localAgentDetection && !agentsLoaded) return;- if (availableAgents.includes(agent)) return;+ if (+ availableAgents.includes(agent) &&+ agentRunsOnActiveModel(agent, isGguf)+ ) {+ return;+ }+ const reset = fallbackAgent(isGguf, availableAgents);+ if (reset === null) return; // nothing offered runs; moving would not helpagentPickedByUserRef.current = false;setStoredAgent(null);- setAgent(DEFAULT_AGENT);+ setAgent(reset);}, [agent,agentsLoaded,availableAgents,+ isGguf,localAgentDetection,setStoredAgent,]);- // Single source of truth for the auto-picked agent, re-derived whenever- // the detected list or the loaded model's GGUF-ness changes -- in either- // direction. `codex` needs a GGUF model (unsloth_cli's- // _require_gguf_for_codex exits otherwise), so it's only preferred once- // the loaded model actually qualifies; loading a GGUF model *after* a- // non-GGUF-gated fallback picked something else re-steers back to codex- // just as loading a non-GGUF model steers away from it. Never overrides a- // choice the user made by hand.- // activeGgufVariant alone only covers an HF-repo GGUF pick (a specific- // quant variant string) -- a direct local .gguf file (custom folder /- // LM Studio / drag-drop) is just as much a GGUF the codex preflight would- // accept, but never has a "variant" to report, and would otherwise read as- // non-GGUF here.- const activeGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);- const activeNativePathToken = useChatRuntimeStore(- (s) => s.activeNativePathToken,- );- const loadedIsGguf = useChatRuntimeStore((s) => s.loadedIsGguf);- const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);+ // The guard is "detection has not answered", not "the list is empty": empty is a valid+ // answer, and acting on an unresolved list flips the command between paints.useEffect(() => {if (agentPickedByUserRef.current) return;- if (detectedAgents.length === 0) return;- const isGguf = isServedByLlamaCpp({- loadedIsGguf,- activeGgufVariant,- activeNativePathToken,- checkpoint,- });- const preferred = detectedAgents.find((a) => a !== "codex" || isGguf);- if (preferred) {- setAgent(preferred);- } else if (agent === "codex" && !isGguf) {- // codex was auto-picked while a GGUF model was active and it's the- // only detected agent; now that the model isn't GGUF anymore, nothing- // detected is actually runnable, so fall back to the default instead- // of leaving a codex command unsloth_cli will reject.- setAgent(DEFAULT_AGENT);+ if (isGguf === null) return;+ if (localAgentDetection && !agentsLoaded) return;+ const next = pickCompatibleAgent(+ detectedAgents,+ agent,+ isGguf,+ availableAgents,+ );+ if (next !== null) {+ setAgent(next);}}, [agent,+ agentsLoaded,+ availableAgents,detectedAgents,- activeGgufVariant,- activeNativePathToken,- loadedIsGguf,- checkpoint,+ isGguf,+ localAgentDetection,]);- const keylessBase =- !(useTunnel && cloudflareUrl) &&- keylessBaseEligible(base, keylessScope, keylessExposure);- const model = useExampleModelName(keylessBase && !apiKey);// The approved SDK dummy is printed only for a transport the backend can admit.const key =apiKey || (keylessBase ? KEYLESS_KEY_PLACEHOLDER : KEY_PLACEHOLDER);@@ -931,6 +1016,7 @@ export function UsageExamples({type="button"onClick={() => {agentPickedByUserRef.current = true;+ clickedUnderGgufRef.current = isGguf;setAgent(id);setStoredAgent(id);}}diff --git a/studio/frontend/src/features/settings/tabs/agents-tab.tsx b/studio/frontend/src/features/settings/tabs/agents-tab.tsxindex a85c1eb8f6b..5f33ebd22de 100644--- a/studio/frontend/src/features/settings/tabs/agents-tab.tsx+++ b/studio/frontend/src/features/settings/tabs/agents-tab.tsx@@ -1277,8 +1277,8 @@ export function AgentsTab() {selectedModel,]);- // No GGUF warning for `codex` (unsloth_cli's _require_gguf_for_codex): the- // picker only ever offers GGUF models.+ // No GGUF warning for `codex` or `claude` (unsloth_cli's+ // _require_gguf_for_agent): the picker only ever offers GGUF models.return (<div className="flex min-w-0 max-w-full flex-col gap-8">diff --git a/studio/frontend/tests/agent-gguf-compatibility.test.ts b/studio/frontend/tests/agent-gguf-compatibility.test.tsnew file mode 100644index 00000000000..6ae9db4a0cb--- /dev/null+++ b/studio/frontend/tests/agent-gguf-compatibility.test.ts@@ -0,0 +1,59 @@+// 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 {+ agentRunsOnActiveModel,+ fallbackAgent,+ pickCompatibleAgent,+} from "../src/features/settings/components/agent-command.ts";++test("only the llama-server-only agents are gated on GGUF", () => {+ for (const agent of ["codex", "claude"]) {+ assert.equal(agentRunsOnActiveModel(agent, false), false);+ assert.equal(agentRunsOnActiveModel(agent, true), true);+ }+ for (const agent of ["opencode", "openclaw", "hermes"]) {+ assert.equal(agentRunsOnActiveModel(agent, false), true);+ assert.equal(agentRunsOnActiveModel(agent, true), true);+ }+});++test("a safetensors model never falls back to a GGUF-only agent", () => {+ assert.equal(fallbackAgent(false), "opencode");+ assert.equal(fallbackAgent(true), "claude");+});++test("the first detected agent that can run the active model wins", () => {+ assert.equal(+ pickCompatibleAgent(["claude", "codex", "opencode"], "opencode", true),+ "claude",+ );+ assert.equal(+ pickCompatibleAgent(["claude", "codex", "opencode"], "claude", false),+ "opencode",+ );+});++test("only GGUF-only agents detected on a safetensors model resets the pick", () => {+ assert.equal(pickCompatibleAgent(["claude"], "claude", false), "opencode");+ assert.equal(pickCompatibleAgent(["codex"], "codex", false), "opencode");+ assert.equal(pickCompatibleAgent(["claude", "codex"], "claude", false), "opencode");+});++test("a compatible current pick is left alone", () => {+ assert.equal(pickCompatibleAgent(["codex"], "opencode", false), null);+ assert.equal(pickCompatibleAgent([], "opencode", false), null);+ assert.equal(pickCompatibleAgent([], "claude", true), null);+});++test("nothing detected still corrects a pick that cannot run", () => {+ // The non-loopback reset clears the detected list, so this is the only correction point.+ assert.equal(pickCompatibleAgent([], "claude", false), "opencode");+});++test("loading a GGUF re-steers back to the GGUF-only agents", () => {+ assert.equal(pickCompatibleAgent(["claude", "codex"], "opencode", true), "claude");+ assert.equal(pickCompatibleAgent(["codex", "opencode"], "codex", false), "opencode");+});diff --git a/studio/frontend/tests/agent-picker-state-space.test.ts b/studio/frontend/tests/agent-picker-state-space.test.tsnew file mode 100644index 00000000000..bb652f9e5e1--- /dev/null+++ b/studio/frontend/tests/agent-picker-state-space.test.ts@@ -0,0 +1,441 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++// The effect re-runs on its own output, so what matters is that it settles, runnably.++import assert from "node:assert/strict";+import test from "node:test";+import {+ GGUF_ONLY_AGENTS,+ compatibilityFromSources,+ UNIVERSAL_AGENT,+ agentRunsOnActiveModel,+ fallbackAgent,+ pickCompatibleAgent,+ resolveGgufCompatibility,+ statusGgufVerdict,+ verdictDescribesModel,+} from "../src/features/settings/components/agent-command.ts";+import { publicModelId } from "../src/features/hub/lib/model-identity.ts";++// DEFAULT_AGENTS in usage-examples.tsx = CODING_AGENTS minus HIDDEN_AGENTS ("pi").+const VISIBLE_AGENTS = ["claude", "codex", "openclaw", "opencode", "hermes"];++function powerset<T>(items: readonly T[]): T[][] {+ return items.reduce<T[][]>(+ (acc, item) => [...acc, ...acc.map((subset) => [...subset, item])],+ [[]],+ );+}++// Orderings are not enumerated: the frontend only filters the backend's order.+const DETECTED_SETS = powerset(VISIBLE_AGENTS);++function settle(+ detected: readonly string[],+ start: string,+ isGguf: boolean,+ offered: readonly string[],+): { agent: string; steps: number } {+ let agent = start;+ for (let steps = 1; steps <= 10; steps++) {+ const next = pickCompatibleAgent(detected, agent, isGguf, offered);+ if (next === null || next === agent) {+ return { agent, steps };+ }+ agent = next;+ }+ throw new Error(+ `did not settle: detected=${JSON.stringify(detected)} start=${start} isGguf=${isGguf}`,+ );+}++test("the state space is the size we think it is", () => {+ assert.equal(DETECTED_SETS.length, 32);+ assert.equal(DETECTED_SETS.length * VISIBLE_AGENTS.length * 2, 320);+});++test("every reachable state settles, and settles in one step", () => {+ let checked = 0;+ for (const detected of DETECTED_SETS) {+ for (const start of VISIBLE_AGENTS) {+ for (const isGguf of [true, false]) {+ const { steps } = settle(detected, start, isGguf, VISIBLE_AGENTS);+ // >1 step is a visible flip between paints, not just churn.+ assert.ok(+ steps <= 2,+ `took ${steps} steps: detected=${JSON.stringify(detected)} start=${start}`,+ );+ checked++;+ }+ }+ }+ assert.equal(checked, 320);+});++test("the settled agent always runs on the active model", () => {+ for (const detected of DETECTED_SETS) {+ for (const start of VISIBLE_AGENTS) {+ for (const isGguf of [true, false]) {+ const { agent } = settle(detected, start, isGguf, VISIBLE_AGENTS);+ assert.ok(+ agentRunsOnActiveModel(agent, isGguf),+ `settled on ${agent} with isGguf=${isGguf}, detected=${JSON.stringify(detected)}`,+ );+ }+ }+ }+});++test("the settled agent is always one the panel offers", () => {+ for (const offered of DETECTED_SETS.filter((s) => s.length > 0)) {+ for (const detected of [[], offered]) {+ for (const start of offered) {+ for (const isGguf of [true, false]) {+ const { agent } = settle(detected, start, isGguf, offered);+ assert.ok(+ offered.includes(agent),+ `settled on ${agent}, not in offered=${JSON.stringify(offered)}`,+ );+ }+ }+ }+ }+});++test("settling is idempotent", () => {+ for (const detected of DETECTED_SETS) {+ for (const start of VISIBLE_AGENTS) {+ for (const isGguf of [true, false]) {+ const first = settle(detected, start, isGguf, VISIBLE_AGENTS).agent;+ const second = settle(detected, first, isGguf, VISIBLE_AGENTS).agent;+ assert.equal(second, first);+ }+ }+ }+});++test("a GGUF model never steers away from a detected GGUF-only agent", () => {+ for (const detected of DETECTED_SETS) {+ const firstGgufOnly = detected.find((a) => GGUF_ONLY_AGENTS.includes(a));+ if (firstGgufOnly === undefined) continue;+ const { agent } = settle(detected, UNIVERSAL_AGENT, true, VISIBLE_AGENTS);+ assert.equal(agent, detected[0]);+ }+});++test("the pre-PR rule and the current rule differ only where Claude was unrunnable", () => {+ // The old auto-pick, verbatim from usage-examples.tsx before this change.+ const before = (+ detected: readonly string[],+ agent: string,+ isGguf: boolean,+ ) => {+ const preferred = detected.find((a) => a !== "codex" || isGguf);+ if (preferred) return preferred;+ if (agent === "codex" && !isGguf) return "claude";+ return null;+ };+ const deltas: string[] = [];+ for (const detected of DETECTED_SETS) {+ for (const start of VISIBLE_AGENTS) {+ for (const isGguf of [true, false]) {+ const b = before(detected, start, isGguf) ?? start;+ const a =+ pickCompatibleAgent(detected, start, isGguf, VISIBLE_AGENTS) ?? start;+ if (a !== b) {+ assert.ok(+ !agentRunsOnActiveModel(b, isGguf),+ `changed a runnable answer: ${b} -> ${a} (isGguf=${isGguf})`,+ );+ assert.ok(agentRunsOnActiveModel(a, isGguf));+ deltas.push(+ `${JSON.stringify(detected)}/${start}/${isGguf}: ${b} -> ${a}`,+ );+ }+ }+ }+ }+ assert.ok(deltas.length > 0);+});++test("UNIVERSAL_AGENT is an agent the panel actually offers", () => {+ // Dropping opencode from CODING_AGENTS should break here, not in the UI.+ assert.ok(VISIBLE_AGENTS.includes(UNIVERSAL_AGENT));+ assert.ok(agentRunsOnActiveModel(UNIVERSAL_AGENT, false));+ assert.ok(agentRunsOnActiveModel(UNIVERSAL_AGENT, true));+});++test("fallbackAgent stays inside a narrowed offered list", () => {+ assert.equal(fallbackAgent(false, ["claude", "codex", "hermes"]), "hermes");+ assert.equal(fallbackAgent(false, ["claude", "codex"]), null); // nothing offered runs+ assert.equal(fallbackAgent(false, []), UNIVERSAL_AGENT); // caller had no list+ assert.equal(fallbackAgent(true, ["claude", "codex"]), "claude");+ assert.equal(fallbackAgent(false, VISIBLE_AGENTS), UNIVERSAL_AGENT);+});++test("a panel offering only GGUF-only agents leaves the pick alone", () => {+ for (const start of ["claude", "codex"]) {+ assert.equal(+ pickCompatibleAgent([], start, false, ["claude", "codex"]),+ null,+ );+ assert.equal(+ pickCompatibleAgent(["claude"], start, false, ["claude", "codex"]),+ null,+ );+ }+});++// The two effects consume isGguf as a tri-state: null while /api/inference/status has not+// resolved. These pin the sequences that reading null as `false` produced.++function browserSession(ggufAfterHydration: boolean) {+ // Not Tauri, so detection never runs and detectedAgents stays empty for good.+ const detected: string[] = [];+ let agent = "claude"; // DEFAULT_AGENT+ const step = (isGguf: boolean | null) => {+ if (isGguf === null) return; // the guard under test+ const next = pickCompatibleAgent(detected, agent, isGguf, VISIBLE_AGENTS);+ if (next !== null) agent = next;+ };+ step(null); // first paint: store still holds its null defaults+ step(ggufAfterHydration); // status lands+ return agent;+}++test("an unresolved model status never re-steers the pick", () => {+ // Was: paint 1 read null as non-GGUF and moved claude -> opencode, then paint 2 could+ // not move back, because pickCompatibleAgent([], "opencode", true) is null.+ assert.equal(browserSession(true), "claude");+ assert.equal(browserSession(false), "opencode");+});++test("reading an unresolved status as non-GGUF is a one-way trip", () => {+ // The reason the guard has to be in the effect and not just in the helper.+ let agent = "claude";+ agent = pickCompatibleAgent([], agent, false, VISIBLE_AGENTS) ?? agent;+ assert.equal(agent, "opencode");+ assert.equal(pickCompatibleAgent([], agent, true, VISIBLE_AGENTS), null);+});++function manualPick(clickedUnder: boolean, now: boolean, agent: string) {+ // The revalidation guard: a hand-made pick survives until GGUF-ness changes under it.+ if (clickedUnder === now) return "kept";+ return agentRunsOnActiveModel(agent, now) ? "kept" : "corrected";+}++test("a manual pick is revalidated when the model changes under it", () => {+ assert.equal(manualPick(true, true, "claude"), "kept");+ assert.equal(manualPick(true, false, "claude"), "corrected");+ assert.equal(manualPick(true, false, "opencode"), "kept");+ assert.equal(manualPick(false, true, "opencode"), "kept");+});++// An external chat selection freezes the local GGUF fields (use-chat-model-runtime stops+// applying status while one is active) while the snippet keeps naming the resident model+// from /v1/models, so the two can drift with no way back. Compatibility is unknown there.+function ggufState(+ checkpoint: string,+ fields: { variant?: string; ctx?: number },+) {+ const external = checkpoint.startsWith("external::");+ if (!checkpoint || external) return null;+ return fields.variant != null || fields.ctx != null;+}++test("an external selection makes GGUF-ness unknown, not stale-true", () => {+ assert.equal(+ ggufState("unsloth/Qwen3-1.7B-GGUF", { variant: "Q4_K_M" }),+ true,+ );+ assert.equal(ggufState("unsloth/Qwen3-1.7B", {}), false);+ // Frozen fields from before the external switch must not read as a live verdict.+ assert.equal(+ ggufState("external::openai::gpt-5", { variant: "Q4_K_M" }),+ null,+ );+ assert.equal(ggufState("", { variant: "Q4_K_M" }), null);+});++test("unknown GGUF-ness leaves both the pick and the stored preference alone", () => {+ const state = ggufState("external::openai::gpt-5", { variant: "Q4_K_M" });+ assert.equal(state, null);+ // Both effects bail on null, so nothing is re-steered and nothing is cleared.+ assert.equal(state === null, true);+});++test("a route that never mounts the chat runtime still learns the model kind", () => {+ // The store fields and params.checkpoint are populated only by useChatModelRuntime,+ // mounted on chat-page and hub-page alone, and local checkpoints are not persisted.+ // Settings opens from every route (api-monitor-page has its own button into this+ // panel), so a store-only reading left the gate permanently unknown there and the+ // panel kept offering a GGUF-only agent for a safetensors model.+ assert.equal(resolveGgufCompatibility(null, false), false);+ assert.equal(resolveGgufCompatibility(null, true), true);+ // With the answer available, the gate is live again on those routes.+ assert.equal(+ pickCompatibleAgent([], "claude", false, VISIBLE_AGENTS),+ UNIVERSAL_AGENT,+ );+});++test("the server wins over the store when both have an answer", () => {+ // A swap made from another tab, the CLI, or an auto-switching API request is invisible+ // to the store: useChatModelRuntime re-reads status on mount, on model-list changes and+ // on tab focus, never on a timer. Reading the store first left the panel gating on the+ // model that had already gone while the snippet already named the new one.+ assert.equal(resolveGgufCompatibility(true, false), false);+ assert.equal(resolveGgufCompatibility(false, true), true);+});++test("a switch made in this tab is not gated on the previous model", () => {+ // The component tags each answer with the store's model identity and discards it once+ // that identity changes, so the server's stale reading arrives here as null, not as a+ // verdict about a model that is no longer loaded.+ assert.equal(resolveGgufCompatibility(true, null), true);+ assert.equal(resolveGgufCompatibility(false, null), false);+});++test("unknown from both sources stays unknown", () => {+ // A server that omits is_gguf, or a probe that failed, is not evidence of "not GGUF".+ assert.equal(resolveGgufCompatibility(null, null), null);+});++test("an idle server decides nothing about a model it is not holding", () => {+ // InferenceStatusResponse gives is_gguf a False default and active_model is Optional,+ // so a server with nothing resident answers false while naming no model. Reading that+ // as "not GGUF" cleared a saved Claude preference for a model that was never there.+ assert.equal(statusGgufVerdict(null, false), null);+ assert.equal(statusGgufVerdict(undefined, false), null);+ assert.equal(statusGgufVerdict(null, true), null);+ // And an unknown verdict leaves the pick and the stored preference alone.+ assert.equal(pickCompatibleAgent([], "claude", true, VISIBLE_AGENTS), null);+});++test("a server that names what it holds still decides", () => {+ assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B", false), false);+ assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B-GGUF", true), true);+ // Named, but the field is missing: an older server, so still unknown.+ assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B", undefined), null);+});++test("a verdict about one model never gates a different one", () => {+ // The status poll and useExampleModelName's catalog poll run on separate timers, so a+ // swap made from the CLI or another tab reaches one of them first. For up to a poll the+ // panel would otherwise pair a newly named safetensors model with the previous GGUF+ // verdict and go on offering a Claude command the CLI refuses.+ assert.equal(+ verdictDescribesModel("unsloth/Qwen3-1.7B-GGUF", "unsloth/Qwen3-1.7B"),+ false,+ );+ assert.equal(+ verdictDescribesModel("unsloth/Qwen3-1.7B-GGUF", "unsloth/Qwen3-1.7B-GGUF"),+ true,+ );+});++test("the quant suffix is not part of the model's identity", () => {+ // useExampleModelName appends ":quant" to pin the file on disk; the status route reports+ // the repo. Treating that as a different model would discard every verdict.+ assert.equal(+ verdictDescribesModel(+ "unsloth/Qwen3-1.7B-GGUF",+ "unsloth/Qwen3-1.7B-GGUF:Q4_K_M",+ ),+ true,+ );+ assert.equal(+ verdictDescribesModel(+ "Unsloth/Qwen3-1.7B-GGUF ",+ "unsloth/qwen3-1.7b-gguf",+ ),+ true,+ );+});++test("nothing named on either side is not a contradiction", () => {+ // An idle server names nothing, and the catalog names nothing until it answers. Neither+ // is evidence that the verdict is about some other model.+ assert.equal(verdictDescribesModel(null, "unsloth/Qwen3-1.7B"), true);+ assert.equal(verdictDescribesModel("unsloth/Qwen3-1.7B", null), true);+ assert.equal(verdictDescribesModel(null, null), true);+});++// How the component composes the two: the status side is collapsed the way the backend+// collapses it for /v1/models before the identities are compared.+const statusMatchesCatalog = (resident: string | null, named: string | null) =>+ verdictDescribesModel(+ resident === null ? null : publicModelId(resident),+ named,+ );++test("a path-loaded model is compared on the identity the catalog publishes", () => {+ // /api/inference/status reports backend.active_model_name raw; /v1/models passes it+ // through public_model_id. Comparing them literally never matched for a local path, so+ // the verdict was discarded for good and the gate went dead on routes with no store.+ assert.equal(statusMatchesCatalog("/models/foo", "foo"), true);+ assert.equal(+ statusMatchesCatalog(+ "/srv/models/Qwen3-30B-A3B-Q4_K_M.gguf",+ "Qwen3-30B-A3B-Q4_K_M",+ ),+ true,+ );+ assert.equal(+ statusMatchesCatalog(+ "~/.cache/huggingface/hub/models--unsloth--Qwen3-1.7B-GGUF/snapshots/abc123",+ "unsloth/Qwen3-1.7B-GGUF",+ ),+ true,+ );+ // Still a real mismatch once collapsed.+ assert.equal(statusMatchesCatalog("/models/foo", "bar"), false);+});++test("polls that name different models leave the question unknown", () => {+ // The store is not a tiebreaker here: an external swap is precisely what it does not+ // see, so reading it kept a Claude command on screen for a model that had been replaced.+ assert.equal(+ compatibilityFromSources(+ true,+ { resident: "unsloth/Qwen3-1.7B", isGguf: false },+ "unsloth/Qwen3-1.7B-GGUF",+ ),+ null,+ );+ assert.equal(+ compatibilityFromSources(+ false,+ { resident: "unsloth/Qwen3-1.7B-GGUF", isGguf: true },+ "unsloth/Qwen3-1.7B",+ ),+ null,+ );+});++test("an answer about the model on screen still decides, and the server wins", () => {+ assert.equal(+ compatibilityFromSources(+ true,+ { resident: "unsloth/Qwen3-1.7B", isGguf: false },+ "unsloth/Qwen3-1.7B",+ ),+ false,+ );+ // No answer for this store state: the store carries it.+ assert.equal(+ compatibilityFromSources(true, null, "unsloth/Qwen3-1.7B-GGUF"),+ true,+ );+ assert.equal(compatibilityFromSources(null, null, null), null);+ // An idle server names nothing, so the store is left to answer.+ assert.equal(+ compatibilityFromSources(+ true,+ { resident: null, isGguf: null },+ "unsloth/X-GGUF",+ ),+ true,+ );+});diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.pyindex 013ce3f7a8a..98308519318 100644--- a/unsloth_cli/commands/start.py+++ b/unsloth_cli/commands/start.py@@ -7,7 +7,9 @@ import atexitimport base64import contextlibimport errno+import functoolsimport hashlib+import http.clientimport jsonimport osimport re@@ -2519,7 +2521,16 @@ def _answer_offers_variant(return False-def _fail_codex_variant_missing(model_id: str, variant: str, variants: list) -> NoReturn:+class _GgufAgent(NamedTuple):+ label: str+ command: str+++_CODEX_GGUF_AGENT = _GgufAgent("Codex", "codex")+_CLAUDE_GGUF_AGENT = _GgufAgent("Claude Code", "claude")+++def _fail_gguf_variant_missing(model_id: str, variant: str, variants: list) -> NoReturn:offered = [row.get("quant")for row in variants@@ -2531,23 +2542,26 @@ def _fail_codex_variant_missing(model_id: str, variant: str, variants: list) ->_fail(message)-def _fail_codex_needs_gguf(model_id: str) -> NoReturn:- message = f"Codex needs a GGUF model served by llama-server, but {model_id} is not one."+def _fail_agent_needs_gguf(agent: _GgufAgent, model_id: str) -> NoReturn:+ message = (+ f"{agent.label} needs a GGUF model served by llama-server, " f"but {model_id} is not one."+ )guess = f"{model_id}-GGUF"if "gguf" not in model_id.lower() and _is_hub_model_id(guess) and _hub_gguf_files(guess):- message += f" Try: unsloth start codex --model {guess}"+ message += f" Try: unsloth start {agent.command} --model {guess}"_fail(message)-def _preflight_codex_gguf(+def _preflight_agent_gguf(+ agent: _GgufAgent,model: Optional[str],*,serve: bool = True,launch: bool = True,) -> None:# Hub-listing preflight for the auto-start path only: with a server running, identifiers- # resolve against its cwd/cache/token, so _attach_gguf_check_for_codex asks the server- # instead. Only a complete listing with no .gguf files rejects; unknown defers to the+ # resolve against its cwd/cache/token, so _attach_gguf_check asks the server instead.+ # Only a complete listing with no .gguf files rejects; unknown defers to the# post-connect check. Mirrors _require_studio's auto-start condition, so with no start# possible its "no running server" error comes first, without a hub probe.if not (serve and launch and model):@@ -2572,10 +2586,11 @@ def _preflight_codex_gguf(returnfiles = _hub_gguf_files(repo)if files is not None and not files:- _fail_codex_needs_gguf(repo)+ _fail_agent_needs_gguf(agent, repo)-def _attach_gguf_check_for_codex(+def _attach_gguf_check(+ agent: _GgufAgent,base: str,key: str,model: Optional[str],@@ -2615,7 +2630,7 @@ def _attach_gguf_check_for_codex(# consults it only for a DIRECTORY), though an explicit one still reaches the probe.refused = _direct_gguf_is_companion(repo) or _direct_gguf_is_big_endian(repo)if refused:- _fail_codex_needs_gguf(repo)+ _fail_agent_needs_gguf(agent, repo)# A drafter folder further up is the server's call.uncertain = _direct_gguf_companion_is_uncertain(repo)# The variant does not exempt this: a direct file is loaded as itself, so a complete@@ -2651,11 +2666,14 @@ def _attach_gguf_check_for_codex(except OSError:missing = Falseif missing:- _fail(f"{repo} does not exist. Check the path before pointing Codex at it.")+ _fail(+ f"{repo} does not exist. Check the path before "+ f"pointing {agent.label} at it."+ )if not _direct_gguf_file_is_ready(repo):_fail(f"{repo} is incomplete (zero bytes or a split missing shards); "- "re-download or re-copy it before pointing Codex at it."+ f"re-download or re-copy it before pointing {agent.label} at it.")# Only a spelling this OS can judge is settled here: a Windows path read# from WSL skipped the absence check above and reads as ready, so returning@@ -2707,18 +2725,18 @@ def _attach_gguf_check_for_codex(# the variantless verdict decides. Only a server omitting the field falls through.if variant and offered is None and isinstance(info.get("loadable"), bool):if not info["loadable"]:- _fail_codex_needs_gguf(candidate)+ _fail_agent_needs_gguf(agent, candidate)returnif variant and isinstance(offered, list):wanted_variant = str(variant).strip().lower()if not any(isinstance(q, str) and q.strip().lower() == wanted_variant for q in offered):- _fail_codex_variant_missing(candidate, variant, variants)+ _fail_gguf_variant_missing(candidate, variant, variants)returnif not variant and isinstance(info.get("loadable"), bool):if not info["loadable"]:- _fail_codex_needs_gguf(candidate)+ _fail_agent_needs_gguf(agent, candidate)returnif isinstance(variants, list) and variants:# llama.cpp kills the resident model before resolving the quant, so a quant this@@ -2745,7 +2763,7 @@ def _attach_gguf_check_for_codex():_fail(f"{candidate} has only incomplete GGUF weights on the server; "- "finish or re-copy the download before pointing Codex at it."+ f"finish or re-copy the download before pointing {agent.label} at it.")# A variantless local load picks from the directory's top level, so rows living# only in quant subdirectories need the variant that resolves them -- else this@@ -2774,7 +2792,7 @@ def _attach_gguf_check_for_codex(+ (f" (available: {offered})." if offered else "."))if variant and not _answer_offers_variant(variants, variant, strict = local_answer):- _fail_codex_variant_missing(candidate, variant, variants)+ _fail_gguf_variant_missing(candidate, variant, variants)returnif isinstance(variants, list):# Explicit local syntax resolves locally on every server version, so its live empty@@ -2792,20 +2810,32 @@ def _attach_gguf_check_for_codex(returnexcept OSError:return- _fail_codex_needs_gguf(candidate)+ _fail_agent_needs_gguf(agent, candidate)-def _require_gguf_for_codex(base: str, key: str, model_id: str) -> None:- # Codex always streams, and Unsloth only streams /v1/responses from llama-server.+def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: str) -> None:+ # Only a definite "no" rejects: the callers wrap this in `except BaseException:+ # _shutdown_auto_served()`, so guessing kills a server that may have just loaded a GGUF.try:status = _http_json("GET", f"{base}/api/inference/status", key)- except urllib.error.HTTPError as exc:- if exc.code == 404:- return # older server without the endpoint; don't block the launch- raise- if status.get("is_gguf"):+ except urllib.error.HTTPError:+ # Not evidence: get_status 500s from its own probes with a GGUF resident.return- _fail_codex_needs_gguf(model_id)+ except (OSError, ValueError, http.client.HTTPException):+ # Named explicitly, not `except Exception`, so typer.Exit and real bugs still surface.+ return+ if not isinstance(status, dict):+ return+ is_gguf = status.get("is_gguf")+ # InferenceStatusResponse declares is_gguf non-optional under a response_model, so a+ # current server always sends it. Absent means "not that endpoint", never "non-GGUF".+ if is_gguf is None or is_gguf:+ return+ # is_gguf carries a False default, so an idle server answers False while naming no+ # model. The request that follows gets the server's own "No GGUF model loaded" anyway.+ if not (status.get("active_model") or status.get("model_identifier")):+ return+ _fail_agent_needs_gguf(agent, model_id)_DYNAMIC_SECTIONS_FLAG = "--exclude-dynamic-system-prompt-sections"@@ -4899,6 +4929,9 @@ def claude(if os.name == "nt"else "curl -fsSL https://claude.ai/install.sh | bash")+ # Before the install prompt: _install_agent runs a remote installer, and this can+ # refuse outright, so asking first fetches a tool the run cannot use.+ _preflight_agent_gguf(_CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch)_require_agent_for_launch("claude", install_hint, launch)base, key, entry = _connect(api_key,@@ -4908,6 +4941,7 @@ def claude(),serve = serve,launch = launch,+ preload_check = functools.partial(_attach_gguf_check, _CLAUDE_GGUF_AGENT),server_options = ServerOptions(enable_tools = enable_tools,tool_call_healing = tool_call_healing,@@ -4922,6 +4956,12 @@ def claude(presence_penalty = presence_penalty,),)+ # Before the launch owns the server, so a rejection tears it down, not atexit.+ try:+ _require_gguf_for_agent(_CLAUDE_GGUF_AGENT, base, key, entry["id"])+ except BaseException:+ _shutdown_auto_served()+ raisemodel_id = entry["id"]if as_subagent:subagent_id = _subagent_model_id(base, key, entry, model, gguf_variant)@@ -5021,8 +5061,10 @@ def codex(# Route a leading `org/name` positional to --model; forward the rest to the agent.model, ctx.args[:] = _consume_positional_model(model, ctx.args)install_hint = _npm_install_hint("@openai/codex")+ # Before the install prompt: _install_agent runs a remote installer, and this can+ # refuse outright, so asking first fetches a tool the run cannot use.+ _preflight_agent_gguf(_CODEX_GGUF_AGENT, model, serve = serve, launch = launch)_require_agent_for_launch("codex", install_hint, launch)- _preflight_codex_gguf(model, serve = serve, launch = launch)base, key, entry = _connect(api_key,model,@@ -5031,7 +5073,7 @@ def codex(),serve = serve,launch = launch,- preload_check = _attach_gguf_check_for_codex,+ preload_check = functools.partial(_attach_gguf_check, _CODEX_GGUF_AGENT),server_options = ServerOptions(enable_tools = enable_tools,tool_call_healing = tool_call_healing,@@ -5050,7 +5092,7 @@ def codex(# takes over its lifecycle, so tear the server down here if it rejects the model# (e.g. a transformers-backend model) rather than leaving it on the atexit backstop.try:- _require_gguf_for_codex(base, key, entry["id"])+ _require_gguf_for_agent(_CODEX_GGUF_AGENT, base, key, entry["id"])except BaseException:_shutdown_auto_served()raisediff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.pyindex 0cb085bad16..127d5b1ec5b 100644--- a/unsloth_cli/tests/test_start.py+++ b/unsloth_cli/tests/test_start.py@@ -5,6 +5,7 @@from __future__ import annotations+import http.clientimport ioimport jsonimport os@@ -3483,7 +3484,8 @@ def test_connect_requested_model_not_loaded_fails(fake_studio, monkeypatch):assert "unsloth/Missing-7B" in result.output-def test_connect_codex_rejects_non_gguf_model(fake_studio, monkeypatch):+def test_connect_gguf_only_agents_reject_non_gguf_model(fake_studio, monkeypatch):+ # opencode is the control: /v1/chat/completions serves this model, so it must pass.inner = start._http_jsondef http_json(@@ -3501,8 +3503,11 @@ def test_connect_codex_rejects_non_gguf_model(fake_studio, monkeypatch):monkeypatch.setattr(start, "_http_json", http_json)result = CliRunner().invoke(start.start_app, ["codex", "--no-launch"])assert result.exit_code == 1- assert "GGUF" in result.output+ assert "Codex needs a GGUF model" in result.outputresult = CliRunner().invoke(start.start_app, ["claude", "--no-launch"])+ assert result.exit_code == 1+ assert "Claude Code needs a GGUF model" in result.output+ result = CliRunner().invoke(start.start_app, ["opencode", "--no-launch"])assert result.exit_code == 0, result.output@@ -4397,8 +4402,7 @@ def test_startup_failure_output_redacts_minted_key(monkeypatch, tmp_path, capsysdef test_codex_preflight_failure_tears_down_auto_served(fake_studio, monkeypatch):- # Listing unavailable: the check falls back to post-connect and must still tear down an- # auto-started server instead of leaving it to atexit.+ # Listing unavailable, so the post-connect check decides and must still tear down.monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)monkeypatch.setattr(start, "find_studio_server", lambda: None)started = {}@@ -6710,7 +6714,7 @@ def _fake_hub_listing(monkeypatch, files_by_repo):def test_codex_preflight_rejects_non_gguf_repo(monkeypatch, capsys):_fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})with pytest.raises(typer.Exit) as excinfo:- start._preflight_codex_gguf("mlx-community/Qwen3-0.6B-4bit")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit")assert excinfo.value.exit_code == 1err = capsys.readouterr().errassert "Codex needs a GGUF model" in err@@ -6719,19 +6723,19 @@ def test_codex_preflight_rejects_non_gguf_repo(monkeypatch, capsys):def test_codex_preflight_passes_gguf_repo_and_splits_variant(monkeypatch):calls = _fake_hub_listing(monkeypatch, {"unsloth/Qwen3-0.6B-GGUF": ["Qwen3-0.6B-Q4_K_M.gguf"]})- start._preflight_codex_gguf("unsloth/Qwen3-0.6B-GGUF:Q4_K_M")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "unsloth/Qwen3-0.6B-GGUF:Q4_K_M")assert calls == ["unsloth/Qwen3-0.6B-GGUF"]def test_codex_preflight_defers_when_listing_unavailable(monkeypatch):_fake_hub_listing(monkeypatch, {})- start._preflight_codex_gguf("owner/private-model")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "owner/private-model")def test_codex_preflight_skips_paths_and_empty_model(monkeypatch):calls = _fake_hub_listing(monkeypatch, {})- start._preflight_codex_gguf("./models/foo.gguf")- start._preflight_codex_gguf(None)+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "./models/foo.gguf")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, None)assert calls == []@@ -6739,14 +6743,14 @@ def test_codex_preflight_skips_remote_studio(monkeypatch):# A one-slash server-side path can look like a hub id; do not reject it from here.calls = _fake_hub_listing(monkeypatch, {"models/qwen-finetune": []})monkeypatch.setenv("UNSLOTH_STUDIO_URL", "http://studio.example:8888")- start._preflight_codex_gguf("models/qwen-finetune")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "models/qwen-finetune")assert calls == []def test_codex_gguf_failure_suggests_only_a_verified_sibling(monkeypatch, capsys):_fake_hub_listing(monkeypatch, {"owner/model-GGUF": ["model-Q4_K_M.gguf"]})with pytest.raises(typer.Exit):- start._fail_codex_needs_gguf("owner/model")+ start._fail_agent_needs_gguf(start._CODEX_GGUF_AGENT, "owner/model")assert "Try: unsloth start codex --model owner/model-GGUF" in capsys.readouterr().err@@ -6795,7 +6799,7 @@ def test_codex_rejects_non_gguf_model_before_connect(monkeypatch):def test_codex_preflight_normalizes_ownerless_shorthand(monkeypatch):calls = _fake_hub_listing(monkeypatch, {"unsloth/Qwen3-0.6B": []})with pytest.raises(typer.Exit):- start._preflight_codex_gguf("Qwen3-0.6B")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "Qwen3-0.6B")assert calls[0] == "unsloth/Qwen3-0.6B"@@ -6803,7 +6807,7 @@ def test_codex_preflight_shorthand_skips_existing_local_dir(monkeypatch, tmp_patcalls = _fake_hub_listing(monkeypatch, {})(tmp_path / "Qwen3-0.6B").mkdir()monkeypatch.chdir(tmp_path)- start._preflight_codex_gguf("Qwen3-0.6B")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "Qwen3-0.6B")assert calls == []@@ -6876,7 +6880,7 @@ def test_codex_preflight_defers_to_running_server(monkeypatch):# check asks it rather than guessing here.calls = _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})monkeypatch.setattr(start, "find_studio_server", lambda: "http://127.0.0.1:8888")- start._preflight_codex_gguf("mlx-community/Qwen3-0.6B-4bit")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit")assert calls == []@@ -6904,13 +6908,17 @@ def test_codex_attach_check_rejects_on_empty_variants(monkeypatch, capsys):monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)_fake_variants(monkeypatch, {"variants": [], "has_vision": False})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "mlx-community/Qwen3-0.6B-4bit")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "mlx-community/Qwen3-0.6B-4bit"+ )assert "Codex needs a GGUF model" in capsys.readouterr().errdef test_codex_attach_check_passes_on_variants(monkeypatch):urls = _fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M"}]})- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_K_M")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_K_M"+ )assert "repo_id=unsloth%2FQwen3-0.6B-GGUF" in urls[0]@@ -6919,7 +6927,9 @@ def test_codex_attach_check_rejects_unavailable_variant(monkeypatch, capsys):# real GGUF repo evicts and then fails the download._fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M"}, {"quant": "Q8_0"}]})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_KM")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_KM"+ )err = capsys.readouterr().errassert "no GGUF variant Q4_KM" in errassert "Q4_K_M, Q8_0" in err@@ -6939,7 +6949,9 @@ def test_codex_attach_check_rejects_unavailable_variant(monkeypatch, capsys):)def test_codex_attach_check_passes_resolvable_variants(monkeypatch, requested, rows):_fake_variants(monkeypatch, {"variants": rows})- start._attach_gguf_check_for_codex(BASE, "sk-test", f"unsloth/Qwen3-0.6B-GGUF:{requested}")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", f"unsloth/Qwen3-0.6B-GGUF:{requested}"+ )def test_codex_attach_check_takes_the_variant_from_the_caller(monkeypatch):@@ -6947,7 +6959,9 @@ def test_codex_attach_check_takes_the_variant_from_the_caller(monkeypatch):# the gate runs, so the quant arrives as an argument._fake_variants(monkeypatch, {"variants": [{"quant": "Q8_0"}]})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF", "Q4_K_M")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF", "Q4_K_M"+ )def test_codex_attach_check_defers_on_server_error(monkeypatch):@@ -6955,13 +6969,17 @@ def test_codex_attach_check_defers_on_server_error(monkeypatch):monkeypatch,urllib.error.HTTPError(f"{BASE}/api/models/gguf-variants", 404, "nope", None, None),)- start._attach_gguf_check_for_codex(BASE, "sk-test", "mlx-community/Qwen3-0.6B-4bit")- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_K_M")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "mlx-community/Qwen3-0.6B-4bit"+ )+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF:Q4_K_M"+ )def test_codex_attach_check_skips_without_model(monkeypatch):urls = _fake_variants(monkeypatch, {"variants": []})- start._attach_gguf_check_for_codex(BASE, "sk-test", None)+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", None)assert urls == []@@ -6982,7 +7000,7 @@ def test_codex_preflight_defers_bare_names_to_attached_server(monkeypatch):calls = _fake_hub_listing(monkeypatch, {"unsloth/Qwen3-0.6B": []})monkeypatch.setattr(start, "find_studio_server", lambda: "http://127.0.0.1:8888")monkeypatch.setattr(start, "verify_studio_identity", lambda base: True)- start._preflight_codex_gguf("Qwen3-0.6B")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "Qwen3-0.6B")assert calls == []@@ -6993,7 +7011,7 @@ def test_codex_gguf_failure_skips_hint_probe_for_non_hub_ids(monkeypatch, capsyslambda repo: pytest.fail("must not probe the hub for a non-hub id"),)with pytest.raises(typer.Exit):- start._fail_codex_needs_gguf("models/Llama/customer-model")+ start._fail_agent_needs_gguf(start._CODEX_GGUF_AGENT, "models/Llama/customer-model")assert "Try:" not in capsys.readouterr().err@@ -7089,12 +7107,18 @@ def test_codex_attach_check_skips_direct_gguf_files(monkeypatch):"_http_json",lambda *a, **k: pytest.fail("a direct .gguf file needs no variants probe"),)- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/foo-Q4_K_M.gguf")- start._attach_gguf_check_for_codex(BASE, "sk-test", "./local/model.GGUF")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/foo-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./local/model.GGUF")# A quant folder or an unrelated parent name is still the model itself.- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/Q4_K_M/model-be.gguf")- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/mmproj-dumps/foo-Q4_K_M.gguf")- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/dflash/Qwen-DFlash-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/Q4_K_M/model-be.gguf"+ )+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/mmproj-dumps/foo-Q4_K_M.gguf"+ )+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/dflash/Qwen-DFlash-Q4_K_M.gguf"+ )def test_codex_attach_check_direct_variant_always_asks_the_server(monkeypatch):@@ -7119,7 +7143,9 @@ def test_codex_attach_check_direct_variant_always_asks_the_server(monkeypatch):}monkeypatch.setattr(start, "_http_json", http_json)- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/foo-Q4_K_M.gguf", "q4_k_m")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/foo-Q4_K_M.gguf", "q4_k_m"+ )assert probes, "an explicit variant must reach the server"# Without a variant the load takes this very file, so no probe is needed.@@ -7128,21 +7154,27 @@ def test_codex_attach_check_direct_variant_always_asks_the_server(monkeypatch):"_http_json",lambda *a, **k: pytest.fail("a variantless direct file needs no probe"),)- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/foo-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/foo-Q4_K_M.gguf")def test_codex_attach_check_asks_server_for_foreign_direct_variant(monkeypatch, capsys):# A quant that is not the file's own label is the marked parent's business: an answer# carrying it passes, one without it fails before the load can evict._fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M"}, {"quant": "Q8_0"}]})- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/m/model-Q4_K_M.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/m/model-Q4_K_M.gguf", "Q8_0"+ )_fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M"}]})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/foo-Q4_K_M.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/foo-Q4_K_M.gguf", "Q8_0"+ )assert "no GGUF variant Q8_0" in capsys.readouterr().err# The parent folder cannot vouch for a quant the file is not.with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/Q8_0/foo-Q4_K_M.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/Q8_0/foo-Q4_K_M.gguf", "Q8_0"+ )def test_codex_attach_check_fails_live_empty_explicit_paths(tmp_path, monkeypatch, capsys):@@ -7152,7 +7184,7 @@ def test_codex_attach_check_fails_live_empty_explicit_paths(tmp_path, monkeypatctarget = tmp_path / "hf-dir"target.mkdir()with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(target))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(target))assert "Codex needs a GGUF model" in capsys.readouterr().err@@ -7162,7 +7194,7 @@ def test_codex_attach_check_still_defers_existing_raw_names(tmp_path, monkeypatcmonkeypatch.chdir(tmp_path)(tmp_path / "my-model-dir").mkdir()_fake_variants(monkeypatch, {"variants": []})- start._attach_gguf_check_for_codex(BASE, "sk-test", "my-model-dir")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "my-model-dir")def test_codex_attach_check_strictness_follows_the_server_answer(monkeypatch):@@ -7171,9 +7203,9 @@ def test_codex_attach_check_strictness_follows_the_server_answer(monkeypatch):rows = [{"quant": "Q4_K_M", "filename": "model-Q4_K_M.gguf"}]_fake_variants(monkeypatch, {"variants": rows, "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "models/qwen", "Q4")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "models/qwen", "Q4")_fake_variants(monkeypatch, {"variants": rows})- start._attach_gguf_check_for_codex(BASE, "sk-test", "models/qwen", "Q4")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "models/qwen", "Q4")def test_codex_attach_check_strict_accepts_the_full_stem(monkeypatch):@@ -7185,7 +7217,7 @@ def test_codex_attach_check_strict_accepts_the_full_stem(monkeypatch):"resolved_locally": True,},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "model-Q4_K_M")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "model-Q4_K_M")def test_codex_attach_check_strict_rejects_nested_basename_labels(monkeypatch):@@ -7198,7 +7230,7 @@ def test_codex_attach_check_strict_rejects_nested_basename_labels(monkeypatch):},)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "model")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "model")def test_codex_attach_check_rejects_torn_named_file_despite_sibling_variant(tmp_path, monkeypatch):@@ -7212,7 +7244,7 @@ def test_codex_attach_check_rejects_torn_named_file_despite_sibling_variant(tmp_{"variants": [{"quant": "Q8_0", "partial": False}], "resolved_locally": True},)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(shard), "Q8_0")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(shard), "Q8_0")def test_codex_attach_check_rejects_a_requested_torn_local_variant(monkeypatch):@@ -7226,9 +7258,9 @@ def test_codex_attach_check_rejects_a_requested_torn_local_variant(monkeypatch):}_fake_variants(monkeypatch, rows)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "Q4_K_M")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "Q4_K_M")_fake_variants(monkeypatch, rows)- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "Q8_0")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "Q8_0")def test_codex_attach_check_probes_direct_paths_on_remote_servers(monkeypatch, capsys):@@ -7237,16 +7269,18 @@ def test_codex_attach_check_probes_direct_paths_on_remote_servers(monkeypatch, cremote = "http://studio.example:8888"_fake_variants(monkeypatch, {"variants": [], "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(remote, "sk-test", "/models/gone-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, remote, "sk-test", "/models/gone-Q4_K_M.gguf"+ )assert "Codex needs a GGUF model" in capsys.readouterr().err# A server that has it answers with rows, and loopback still short-circuits._fake_variants(monkeypatch,{"variants": [{"quant": "Q4_K_M", "partial": False}], "resolved_locally": True},)- start._attach_gguf_check_for_codex(remote, "sk-test", "/models/foo-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, remote, "sk-test", "/models/foo-Q4_K_M.gguf")monkeypatch.setattr(start, "_http_json", lambda *a, **k: pytest.fail("loopback needs no probe"))- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/foo-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/foo-Q4_K_M.gguf")@pytest.mark.skipif(os.name == "nt", reason = "every spelling is native on Windows")@@ -7256,7 +7290,9 @@ def test_codex_attach_check_probes_non_native_direct_paths(monkeypatch, capsys):# for a file nobody looked at, and the load trusts the .gguf suffix: teardown, then failure.urls = _fake_variants(monkeypatch, {"variants": [], "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", r"C:\models\typo-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", r"C:\models\typo-Q4_K_M.gguf"+ )assert "Codex needs a GGUF model" in capsys.readouterr().errassert urls, "the server was never asked"# The server holding it still passes.@@ -7264,7 +7300,7 @@ def test_codex_attach_check_probes_non_native_direct_paths(monkeypatch, capsys):monkeypatch,{"variants": [{"quant": "Q4_K_M", "partial": False}], "resolved_locally": True},)- start._attach_gguf_check_for_codex(BASE, "sk-test", r"C:\models\foo-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", r"C:\models\foo-Q4_K_M.gguf")def test_codex_attach_check_honors_a_negative_verdict_without_an_allow_list(monkeypatch, capsys):@@ -7278,13 +7314,19 @@ def test_codex_attach_check_honors_a_negative_verdict_without_an_allow_list(monk}_fake_variants(monkeypatch, negative)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/MTP/sub/foo-Q8_0.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/MTP/sub/foo-Q8_0.gguf", "Q8_0"+ )assert "Codex needs a GGUF model" in capsys.readouterr().err# A positive verdict passes, and a server too old to send the flag falls through to rows._fake_variants(monkeypatch, {**negative, "loadable": True})- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/sub/foo-Q8_0.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/sub/foo-Q8_0.gguf", "Q8_0"+ )_fake_variants(monkeypatch, {k: v for k, v in negative.items() if k != "loadable"})- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/sub/foo-Q8_0.gguf", "Q8_0")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/sub/foo-Q8_0.gguf", "Q8_0"+ )def test_codex_attach_check_refuses_companion_paths_with_a_variant(monkeypatch, capsys):@@ -7296,10 +7338,14 @@ def test_codex_attach_check_refuses_companion_paths_with_a_variant(monkeypatch,lambda *a, **k: pytest.fail("a refused direct file needs no variants probe"),)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/m/mmproj-F16.gguf", "Q4_K_M")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/m/mmproj-F16.gguf", "Q4_K_M"+ )assert "Codex needs a GGUF model" in capsys.readouterr().errwith pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/m/mmproj-F16.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/m/mmproj-F16.gguf"+ )def test_codex_attach_check_ignores_cleanable_only_answers(monkeypatch, capsys):@@ -7309,7 +7355,7 @@ def test_codex_attach_check_ignores_cleanable_only_answers(monkeypatch, capsys):{"variants": [{"quant": "Q4_K_M", "partial": True, "cleanable": True}]},)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "owner/no-gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "owner/no-gguf")assert "Codex needs a GGUF model" in capsys.readouterr().err# A real listed row beside it still answers._fake_variants(@@ -7321,7 +7367,7 @@ def test_codex_attach_check_ignores_cleanable_only_answers(monkeypatch, capsys):]},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "owner/has-gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "owner/has-gguf")def test_codex_attach_check_follows_bare_names_the_server_calls_remote(monkeypatch):@@ -7343,7 +7389,7 @@ def test_codex_attach_check_follows_bare_names_the_server_calls_remote(monkeypatreturn {"variants": [], "resolved_locally": False}monkeypatch.setattr(start, "_http_json", http_json)- start._attach_gguf_check_for_codex(BASE, "sk-test", "Qwen3-0.6B-GGUF")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "Qwen3-0.6B-GGUF")assert len(urls) == 2 and "unsloth%2FQwen3-0.6B-GGUF" in urls[1]@@ -7359,7 +7405,7 @@ def test_codex_attach_check_trusts_the_servers_loadable_answer(monkeypatch, caps},)# Naming the quant works even though every row is nested...- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "BF16")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "BF16")_fake_variants(monkeypatch,{@@ -7371,7 +7417,7 @@ def test_codex_attach_check_trusts_the_servers_loadable_answer(monkeypatch, caps)# ...and a variantless load, which cannot pick it, is refused.with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m")assert "Codex needs a GGUF model" in capsys.readouterr().err# A quant the load would not serve is refused even though a row lists it._fake_variants(@@ -7384,7 +7430,7 @@ def test_codex_attach_check_trusts_the_servers_loadable_answer(monkeypatch, caps},)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "Q8_0")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "Q8_0")def test_codex_attach_check_probes_missing_bare_gguf_shorthands(tmp_path, monkeypatch, capsys):@@ -7406,14 +7452,14 @@ def test_codex_attach_check_probes_missing_bare_gguf_shorthands(tmp_path, monkeymonkeypatch.setattr(start, "_http_json", http_json)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "foo.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "foo.gguf")assert any("repo_id=unsloth%2Ffoo.gguf" in url for url in urls)# A file that does exist is still the direct path it names.(tmp_path / "real-Q4_K_M.gguf").write_bytes(b"GGUF")monkeypatch.setattr(start, "_http_json", lambda *a, **k: pytest.fail("an existing file needs no probe"))- start._attach_gguf_check_for_codex(BASE, "sk-test", "real-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "real-Q4_K_M.gguf")def test_codex_attach_check_treats_gguf_suffixed_hub_ids_as_remote(monkeypatch):@@ -7423,12 +7469,14 @@ def test_codex_attach_check_treats_gguf_suffixed_hub_ids_as_remote(monkeypatch):monkeypatch,{"variants": [{"quant": "Q4_K_M", "filename": "BF16/model-Q4_K_M.gguf"}]},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "owner/model.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "owner/model.gguf")_fake_variants(monkeypatch,{"variants": [{"quant": "UD-Q4_K_XL", "filename": "m-UD-Q4_K_XL.gguf"}]},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "owner/model.gguf", "Q4_K_XL")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "owner/model.gguf", "Q4_K_XL"+ )def test_codex_attach_check_accepts_bpw_qualified_local_requests(monkeypatch):@@ -7441,7 +7489,7 @@ def test_codex_attach_check_accepts_bpw_qualified_local_requests(monkeypatch):"resolved_locally": True,},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "IQ4_XS-3.53bpw")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "IQ4_XS-3.53bpw")def test_codex_attach_check_strict_accepts_basename_quant_tokens(monkeypatch):@@ -7454,8 +7502,8 @@ def test_codex_attach_check_strict_accepts_basename_quant_tokens(monkeypatch):"resolved_locally": True,},)- start._attach_gguf_check_for_codex(- BASE, "sk-test", "/models/F16-checkpoint-Q4_K_M.gguf", "Q4_K_M"+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/F16-checkpoint-Q4_K_M.gguf", "Q4_K_M")@@ -7468,11 +7516,11 @@ def test_codex_attach_check_honors_resolved_locally_empty_for_raw_names((tmp_path / "models" / "qwen").mkdir(parents = True)_fake_variants(monkeypatch, {"variants": [], "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "models/qwen")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "models/qwen")assert "Codex needs a GGUF model" in capsys.readouterr().err# A legacy answer without the flag keeps the deferral._fake_variants(monkeypatch, {"variants": []})- start._attach_gguf_check_for_codex(BASE, "sk-test", "models/qwen")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "models/qwen")def test_codex_attach_check_requires_a_pickable_row_without_a_variant(monkeypatch, capsys):@@ -7484,17 +7532,17 @@ def test_codex_attach_check_requires_a_pickable_row_without_a_variant(monkeypatc}_fake_variants(monkeypatch, rows)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m")err = capsys.readouterr().errassert "quant subdirectories" in err and "BF16" in err# Naming the variant resolves it, and a top-level row needs nothing._fake_variants(monkeypatch, rows)- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "BF16")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "BF16")_fake_variants(monkeypatch,{"variants": [{"quant": "Q4_K_M", "filename": "m-Q4_K_M.gguf"}], "resolved_locally": True},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m")def test_codex_attach_check_probes_gguf_named_directories(tmp_path, monkeypatch, capsys):@@ -7503,14 +7551,14 @@ def test_codex_attach_check_probes_gguf_named_directories(tmp_path, monkeypatch,gguf_dir.mkdir()_fake_variants(monkeypatch, {"variants": [], "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(gguf_dir))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(gguf_dir))assert "Codex needs a GGUF model" in capsys.readouterr().err# One holding weights answers with rows and passes._fake_variants(monkeypatch,{"variants": [{"quant": "Q4_K_M", "filename": "m-Q4_K_M.gguf"}], "resolved_locally": True},)- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(gguf_dir))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(gguf_dir))def test_codex_attach_check_allows_short_shard_like_names(tmp_path, monkeypatch):@@ -7522,18 +7570,20 @@ def test_codex_attach_check_allows_short_shard_like_names(tmp_path, monkeypatch))lone = tmp_path / "model-Q4_K_M-001-of-002.gguf"lone.write_bytes(b"GGUF")- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(lone))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(lone))def test_codex_attach_check_honors_loadable_on_an_empty_listing(monkeypatch):# A root-blind lister can miss a file detect_gguf_model resolves, so an empty answer# reporting loadable is loadable._fake_variants(monkeypatch, {"variants": [], "resolved_locally": True, "loadable": True})- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/MTP/foo-Q8_0.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/MTP/foo-Q8_0.gguf")# Empty and not loadable still fails._fake_variants(monkeypatch, {"variants": [], "resolved_locally": True, "loadable": False})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/MTP/foo-Q8_0.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/MTP/foo-Q8_0.gguf"+ )def test_codex_preload_gate_checks_direct_path_identity(fake_studio, monkeypatch, tmp_path):@@ -7692,20 +7742,26 @@ def test_codex_attach_check_asks_about_nested_drafter_folders(monkeypatch, capsy# path loads or is refused depending on a root this process cannot see._fake_variants(monkeypatch, {"variants": [], "resolved_locally": True})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/MTP/copies/foo-Q8_0.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/MTP/copies/foo-Q8_0.gguf"+ )assert "Codex needs a GGUF model" in capsys.readouterr().err# A server that serves it answers with rows and the attach proceeds._fake_variants(monkeypatch,{"variants": [{"quant": "Q8_0"}], "resolved_locally": True, "loadable": True},)- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/MTP/copies/foo-Q8_0.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/MTP/copies/foo-Q8_0.gguf"+ )# A drafter NAME PREFIX means the same under any root, so it is refused with no probe.monkeypatch.setattr(start, "_http_json", lambda *a, **k: pytest.fail("an immediate companion needs no probe"))with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "/models/mtp-foo-Q8_0.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/models/mtp-foo-Q8_0.gguf"+ )def test_codex_attach_check_defers_foreign_path_syntax(monkeypatch, tmp_path):@@ -7713,11 +7769,13 @@ def test_codex_attach_check_defers_foreign_path_syntax(monkeypatch, tmp_path):# absence says nothing about the server's disk.monkeypatch.chdir(tmp_path)monkeypatch.setattr(start, "_http_json", lambda *a, **k: {"variants": [{"quant": "Q4_K_M"}]})- start._attach_gguf_check_for_codex(BASE, "sk-test", "C:\\models\\foo-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "C:\\models\\foo-Q4_K_M.gguf"+ )# A native path that really is absent is still failed.with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(- BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf"))@@ -7741,10 +7799,12 @@ def test_codex_attach_check_defers_when_loopback_is_not_this_machine(monkeypatchmonkeypatch.setattr(start, "_http_json", http_json)# Absent locally, and an incomplete local shard: neither may settle it now.- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf"))+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf")+ )torn = tmp_path / "torn-Q4_K_M-00001-of-00002.gguf"torn.write_bytes(b"GGUF")- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(torn))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(torn))assert probes, "the server must be asked when its filesystem is not ours"@@ -7761,8 +7821,8 @@ def test_codex_attach_check_treats_both_spellings_as_native_on_windows(monkeypatlambda *a, **k: pytest.fail("a visible missing file needs no probe"),)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(- BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(tmp_path / "gone-Q4_K_M.gguf"))@@ -7775,12 +7835,14 @@ def test_codex_attach_check_rejects_missing_direct_paths(tmp_path, monkeypatch,lambda *a, **k: pytest.fail("a visible missing file needs no probe"),)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(- BASE, "sk-test", os.fspath(tmp_path / "typo-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(tmp_path / "typo-Q4_K_M.gguf"))assert "does not exist" in capsys.readouterr().err# A path under a directory this process cannot list stays unknowable.- start._attach_gguf_check_for_codex(BASE, "sk-test", "/nonexistent-root/dir/m-Q4_K_M.gguf")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/nonexistent-root/dir/m-Q4_K_M.gguf"+ )def test_codex_attach_check_rejects_broken_direct_symlinks(tmp_path, monkeypatch, capsys):@@ -7794,7 +7856,7 @@ def test_codex_attach_check_rejects_broken_direct_symlinks(tmp_path, monkeypatchlink = tmp_path / "gone-Q4_K_M.gguf"link.symlink_to(tmp_path / "missing-target.gguf")with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(link))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(link))assert "incomplete" in capsys.readouterr().err@@ -7804,14 +7866,14 @@ def test_codex_attach_check_fails_all_partial_local_answers(monkeypatch, capsys)rows = {"variants": [{"quant": "Q4_K_M", "partial": True}], "resolved_locally": True}_fake_variants(monkeypatch, rows)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m")assert "incomplete GGUF weights" in capsys.readouterr().err_fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M", "partial": True}]})- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF")# A server predating resolved_locally still resolves explicit path syntax locally._fake_variants(monkeypatch, {"variants": [{"quant": "Q4_K_M", "partial": True}]})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m")def test_codex_attach_check_local_answers_take_exact_labels_only(monkeypatch):@@ -7820,9 +7882,11 @@ def test_codex_attach_check_local_answers_take_exact_labels_only(monkeypatch):rows = {"variants": [{"quant": "Q4_K_M", "filename": "model-Q4_K_M.gguf"}]}_fake_variants(monkeypatch, rows)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "./m", "Q4")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "./m", "Q4")_fake_variants(monkeypatch, rows)- start._attach_gguf_check_for_codex(BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF", "Q4")+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "unsloth/Qwen3-0.6B-GGUF", "Q4"+ )def test_codex_attach_check_rejects_incomplete_direct_files(tmp_path, monkeypatch, capsys):@@ -7836,18 +7900,20 @@ def test_codex_attach_check_rejects_incomplete_direct_files(tmp_path, monkeypatcempty = tmp_path / "zero-Q4_K_M.gguf"empty.write_bytes(b"")with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(empty))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(empty))assert "incomplete" in capsys.readouterr().errshard = tmp_path / "m-Q4_K_M-00001-of-00002.gguf"shard.write_bytes(b"GGUF")with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(shard))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(shard))# The complete set beside it passes, and a CLI-invisible path stays open.(tmp_path / "m-Q4_K_M-00002-of-00002.gguf").write_bytes(b"GGUF")- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(shard))- start._attach_gguf_check_for_codex(BASE, "sk-test", "/nonexistent/other-Q4_K_M.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(shard))+ start._attach_gguf_check(+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "/nonexistent/other-Q4_K_M.gguf"+ )def test_codex_attach_check_accepts_symlinked_split_shards(tmp_path, monkeypatch):@@ -7866,12 +7932,12 @@ def test_codex_attach_check_accepts_symlinked_split_shards(tmp_path, monkeypatchlinks.mkdir()link = links / "m-Q4_K_M-00001-of-00002.gguf"link.symlink_to(real / "m-Q4_K_M-00001-of-00002.gguf")- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(link))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(link))# A target set that is itself torn still fails.(real / "m-Q4_K_M-00002-of-00002.gguf").unlink()with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", os.fspath(link))+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", os.fspath(link))@pytest.mark.parametrize(@@ -7894,7 +7960,7 @@ def test_codex_attach_check_refuses_companion_gguf_files(monkeypatch, capsys, palambda *a, **k: pytest.fail("a companion .gguf needs no variants probe"),)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", path)+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", path)assert "Codex needs a GGUF model" in capsys.readouterr().err@@ -7904,14 +7970,14 @@ def test_codex_preflight_canonicalizes_missing_bare_gguf_names(tmp_path, monkeypmonkeypatch.chdir(tmp_path)calls = _fake_hub_listing(monkeypatch, {"unsloth/foo.gguf": []})with pytest.raises(typer.Exit):- start._preflight_codex_gguf("foo.gguf")+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "foo.gguf")assert calls == ["unsloth/foo.gguf"]@pytest.mark.parametrize("kwargs", [{"serve": False}, {"launch": False}])def test_codex_preflight_skips_when_autostart_impossible(monkeypatch, kwargs):calls = _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})- start._preflight_codex_gguf("mlx-community/Qwen3-0.6B-4bit", **kwargs)+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit", **kwargs)assert calls == []@@ -7934,7 +8000,7 @@ def test_codex_attach_check_normalizes_shorthand_after_raw_probe(monkeypatch, camonkeypatch.setattr(start, "_http_json", http_json)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "Qwen3-0.6B")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "Qwen3-0.6B")assert len(urls) == 2assert "repo_id=unsloth%2FQwen3-0.6B" in urls[1]assert "unsloth/Qwen3-0.6B" in capsys.readouterr().err@@ -7955,7 +8021,7 @@ def test_codex_attach_check_trusts_raw_server_dir_answer(monkeypatch):return {"variants": [{"quant": "Q4_K_M"}]}monkeypatch.setattr(start, "_http_json", http_json)- start._attach_gguf_check_for_codex(BASE, "sk-test", "local-gguf-dir")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "local-gguf-dir")assert len(urls) == 1@@ -7981,7 +8047,7 @@ def test_codex_attach_check_rejects_live_empty_raw_shorthand(monkeypatch, tmp_pamonkeypatch.setattr(start, "_http_json", http_json)with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "Qwen3-0.6B-GGUF")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "Qwen3-0.6B-GGUF")assert len(urls) == 1assert "Qwen3-0.6B-GGUF" in capsys.readouterr().err@@ -7998,14 +8064,14 @@ def test_codex_attach_check_defers_shorthand_when_canonical_probe_errors(monkeypraise urllib.error.HTTPError(url, 404, "nope", None, None)monkeypatch.setattr(start, "_http_json", http_json)- start._attach_gguf_check_for_codex(BASE, "sk-test", "Qwen3-0.6B")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "Qwen3-0.6B")def test_codex_attach_check_probes_hub_shaped_gguf_ids(monkeypatch, capsys):monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)urls = _fake_variants(monkeypatch, {"variants": []})with pytest.raises(typer.Exit):- start._attach_gguf_check_for_codex(BASE, "sk-test", "owner/model.gguf")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "owner/model.gguf")assert len(urls) == 1assert "owner%2Fmodel.gguf" in urls[0]@@ -8014,4 +8080,413 @@ def test_codex_attach_check_defers_when_raw_name_exists_locally(monkeypatch, tmp(tmp_path / "models" / "qwen").mkdir(parents = True)monkeypatch.chdir(tmp_path)_fake_variants(monkeypatch, {"variants": []})- start._attach_gguf_check_for_codex(BASE, "sk-test", "models/qwen")+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", "models/qwen")+++# These also pin Codex's wording, now that the helpers are shared.+++def test_gguf_agents_name_themselves_and_their_own_subcommand(monkeypatch, capsys):+ monkeypatch.setattr(start, "_is_hub_model_id", lambda name: True)+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: ["model-Q4_K_M.gguf"])+ for agent, label, command in (+ (start._CODEX_GGUF_AGENT, "Codex", "codex"),+ (start._CLAUDE_GGUF_AGENT, "Claude Code", "claude"),+ ):+ with pytest.raises(typer.Exit) as excinfo:+ start._fail_agent_needs_gguf(agent, "unsloth/gemma-3-4b-it")+ assert excinfo.value.exit_code == 1+ assert capsys.readouterr().err.strip() == (+ f"{label} needs a GGUF model served by llama-server, but unsloth/gemma-3-4b-it "+ f"is not one. Try: unsloth start {command} --model unsloth/gemma-3-4b-it-GGUF"+ )+++def test_require_gguf_for_agent_reads_the_servers_status(monkeypatch, capsys):+ monkeypatch.setattr(+ start,+ "_http_json",+ lambda *a, **k: {"is_gguf": False, "active_model": "unsloth/gemma-3-4b-it"},+ )+ with pytest.raises(typer.Exit):+ start._require_gguf_for_agent(+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "unsloth/gemma-3-4b-it"+ )+ assert "Claude Code needs a GGUF model" in capsys.readouterr().err+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: {"is_gguf": True})+ start._require_gguf_for_agent(+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "unsloth/gemma-3-4b-it-GGUF"+ )+++def test_claude_preflight_rejects_non_gguf_repo(monkeypatch, capsys):+ _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})+ with pytest.raises(typer.Exit):+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit")+ assert "Claude Code needs a GGUF model" in capsys.readouterr().err+++def test_claude_command_preflights_before_starting_a_server(fake_studio, monkeypatch, tmp_path):+ _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})+ monkeypatch.setattr(start, "_agents_config_root", lambda: tmp_path / "agents")+ started = {"called": False}+ monkeypatch.setattr(+ start, "_start_studio_server", lambda *a, **k: started.__setitem__("called", True)+ )+ result = CliRunner().invoke(+ start.start_app, ["claude", "--model", "mlx-community/Qwen3-0.6B-4bit"]+ )+ assert result.exit_code == 1+ assert "Claude Code needs a GGUF model" in result.output+ assert started["called"] is False+++ ("subcommand", "label"),+ [("claude", "Claude Code"), ("codex", "Codex")],+)+def test_a_rejected_model_never_offers_to_install_the_agent(+ monkeypatch, tmp_path, subcommand, label+):+ # No fake_studio: it stubs _require_agent_for_launch to a no-op, which is the call+ # under test here. _install_agent runs a remote installer, so the refusal must come+ # first. Neither test reaches a server.+ _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})+ monkeypatch.setattr(start, "_agents_config_root", lambda: tmp_path / "agents")+ monkeypatch.setattr(start, "_which_with_install_dirs", lambda name: None)+ monkeypatch.setattr(start, "_start_studio_server", lambda *a, **k: None)+ offered = []+ monkeypatch.setattr(+ start,+ "_install_agent",+ lambda name, hint: offered.append(name),+ )+ result = CliRunner().invoke(+ start.start_app,+ [subcommand, "--model", "mlx-community/Qwen3-0.6B-4bit", "--launch"],+ )+ assert result.exit_code == 1+ assert f"{label} needs a GGUF model" in result.output+ assert offered == []+++def test_a_missing_agent_is_still_reported_for_a_model_that_passes(monkeypatch, tmp_path):+ # The reorder must not turn the install prompt into dead code for a runnable model.+ _fake_hub_listing(monkeypatch, {"unsloth/Qwen3-0.6B-GGUF": ["Q4_K_M.gguf"]})+ monkeypatch.setattr(start, "_agents_config_root", lambda: tmp_path / "agents")+ monkeypatch.setattr(start, "_which_with_install_dirs", lambda name: None)+ monkeypatch.setattr(start, "_start_studio_server", lambda *a, **k: None)+ offered = []+ monkeypatch.setattr(+ start,+ "_install_agent",+ lambda name, hint: offered.append(name),+ )+ result = CliRunner().invoke(+ start.start_app,+ ["claude", "--model", "unsloth/Qwen3-0.6B-GGUF", "--launch"],+ )+ assert offered == ["claude"]+ assert result.exit_code == 1+ assert "not found on PATH" in result.output+++def test_claude_preload_gate_rejects_before_an_evicting_load(fake_studio, monkeypatch):+ inner = start._http_json+ probed = []++ def http_json(+ method,+ url,+ token,+ payload = None,+ timeout = 30,+ error = None,+ ):+ if "/api/models/gguf-variants" in url:+ probed.append(url)+ return {"variants": []}+ return inner(method, url, token, payload, timeout, error)++ monkeypatch.setattr(start, "_http_json", http_json)+ result = CliRunner().invoke(+ start.start_app, ["claude", "--model", "unsloth/Qwen3-1.7B", "--no-launch"]+ )+ assert result.exit_code == 1+ assert "Claude Code needs a GGUF model" in result.output+ assert probed, "the gate must probe the server before the load"+ assert not [call for call in fake_studio if call[1].endswith("/api/inference/load")]+++def test_claude_post_connect_failure_tears_down_auto_served(fake_studio, monkeypatch):+ # Listing unavailable: the check falls back to post-connect and must still tear down an+ # auto-started server instead of leaving it to atexit.+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)+ monkeypatch.setattr(start, "find_studio_server", lambda: None)+ started = {}+ fake = SimpleNamespace(pid = 999, poll = lambda: None)++ def fake_start(+ base,+ model,+ load,+ server_options = None,+ ):+ started.update(base = base, model = model)+ start._auto_served_server = fake+ return fake++ monkeypatch.setattr(start, "_start_studio_server", fake_start)+ monkeypatch.setattr(+ start, "_shutdown_server", lambda server: started.__setitem__("down", server)+ )+ inner = start._http_json++ def http_json(+ method,+ url,+ token,+ payload = None,+ timeout = 30,+ error = None,+ ):+ if url.endswith("/api/inference/status"):+ return {"is_gguf": False, "model_identifier": "transformers-model"}+ return inner(method, url, token, payload, timeout, error)++ monkeypatch.setattr(start, "_http_json", http_json)+ result = CliRunner().invoke(+ start.start_app, ["claude", "--model", "unsloth/Qwen3-1.7B", "--launch"]+ )+ assert result.exit_code != 0, result.output+ assert "Claude Code needs a GGUF model" in result.output+ assert started.get("down") is fake+++def test_claude_post_connect_failure_spares_an_attached_server(fake_studio, monkeypatch):+ down = []+ monkeypatch.setattr(start, "_shutdown_server", lambda server: down.append(server))+ inner = start._http_json++ def http_json(+ method,+ url,+ token,+ payload = None,+ timeout = 30,+ error = None,+ ):+ if url.endswith("/api/inference/status"):+ return {"is_gguf": False, "model_identifier": "transformers-model"}+ return inner(method, url, token, payload, timeout, error)++ monkeypatch.setattr(start, "_http_json", http_json)+ result = CliRunner().invoke(start.start_app, ["claude", "--no-launch"])+ assert result.exit_code == 1+ assert "Claude Code needs a GGUF model" in result.output+ assert down == []+++# Tolerance: callers tear the server down on any exception, so only "is_gguf": false rejects.+++def _status_raises(monkeypatch, exc):+ def http_json(*args, **kwargs):+ raise exc++ monkeypatch.setattr(start, "_http_json", http_json)+++def _require_claude_gguf():+ start._require_gguf_for_agent(+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "unsloth/gemma-3-4b-it"+ )+++ "code,reason",+ [+ (404, "not found"), # older server without the endpoint+ (401, "Unauthorized"), # key scoped to /v1, not /api+ (403, "Forbidden"),+ (500, "Failed to get status"), # get_status's own catch-all, GGUF still resident+ (503, "Service Unavailable"),+ (302, "refusing redirect"), # urlopen_no_redirect raises this shape+ ],+)+def test_require_gguf_never_rejects_on_an_http_error(monkeypatch, capsys, code, reason):+ url = f"{BASE}/api/inference/status"+ _status_raises(monkeypatch, urllib.error.HTTPError(url, code, reason, None, None))+ assert _require_claude_gguf() is None+ assert capsys.readouterr().err == ""+++ "exc",+ [+ urllib.error.URLError(ConnectionRefusedError(111, "Connection refused")),+ TimeoutError("timed out"),+ OSError(101, "Network is unreachable"),+ json.JSONDecodeError("Expecting value", "<html>not json</html>", 0),+ http.client.BadStatusLine("garbage"),+ http.client.RemoteDisconnected("closed"),+ ],+)+def test_require_gguf_never_rejects_on_a_transport_failure(monkeypatch, capsys, exc):+ # Nor as a traceback: only HTTPError was caught before.+ _status_raises(monkeypatch, exc)+ assert _require_claude_gguf() is None+ assert capsys.readouterr().err == ""+++ "body",+ [+ {}, # blank 200 body; _http_json turns "" into {}+ {"model_identifier": "unsloth/Qwen3-1.7B-GGUF"}, # 200 without the key+ {"error": "API endpoint not found"}, # Studio older than the /api/* 404+ {"is_gguf": None}, # explicit null from a proxy or hand-rolled server+ ["not", "a", "dict"],+ None,+ ],+)+def test_require_gguf_treats_an_unreadable_answer_as_unknown(monkeypatch, capsys, body):+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: body)+ assert _require_claude_gguf() is None+ # The old code claimed "needs a GGUF model", which the server never said.+ assert "needs a GGUF model" not in capsys.readouterr().err+++ "agent,label",+ [("_CODEX_GGUF_AGENT", "Codex"), ("_CLAUDE_GGUF_AGENT", "Claude Code")],+)+def test_require_gguf_still_rejects_a_definite_no(monkeypatch, capsys, agent, label):+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None) # no Try: suffix+ monkeypatch.setattr(+ start,+ "_http_json",+ lambda *a, **k: {"is_gguf": False, "model_identifier": "transformers-model"},+ )+ with pytest.raises(typer.Exit) as excinfo:+ start._require_gguf_for_agent(+ getattr(start, agent), BASE, "sk-test", "unsloth/gemma-3-4b-it"+ )+ assert excinfo.value.exit_code == 1+ assert capsys.readouterr().err.strip() == (+ f"{label} needs a GGUF model served by llama-server, "+ "but unsloth/gemma-3-4b-it is not one."+ )+++ "body",+ [+ {"is_gguf": False},+ {"is_gguf": False, "active_model": None},+ {"is_gguf": False, "active_model": None, "model_identifier": None},+ ],+)+def test_require_gguf_treats_an_idle_server_as_unknown(monkeypatch, body):+ # is_gguf's False default means an idle server answers False and names no model;+ # reading that as "not GGUF" refuses a good GGUF that is merely not loaded yet.+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: body)+ start._require_gguf_for_agent(+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "unsloth/gemma-3-4b-it-GGUF"+ )+++def test_require_gguf_still_rejects_a_named_non_gguf_model(monkeypatch, capsys):+ # The tolerance above must not reach a server that does name what it is holding.+ monkeypatch.setattr(+ start,+ "_http_json",+ lambda *a, **k: {"is_gguf": False, "model_identifier": "unsloth/gemma-3-4b-it"},+ )+ with pytest.raises(typer.Exit):+ start._require_gguf_for_agent(+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "unsloth/gemma-3-4b-it"+ )+ assert "Claude Code needs a GGUF model" in capsys.readouterr().err+++def test_require_gguf_does_not_swallow_a_real_exit(monkeypatch):+ # Guards the exception tuple against being loosened to `except Exception`.+ _status_raises(monkeypatch, typer.Exit(code = 1))+ with pytest.raises(typer.Exit):+ _require_claude_gguf()+++def test_require_gguf_does_not_swallow_a_bug(monkeypatch):+ _status_raises(monkeypatch, AttributeError("typo in the stub"))+ with pytest.raises(AttributeError):+ _require_claude_gguf()++[email protected]("agent", ["claude", "codex"])+def test_an_unreadable_status_leaves_the_auto_served_server_alone(fake_studio, monkeypatch, agent):+ # The regression: a 500 from get_status used to reject, then shut down a loaded GGUF.+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)+ monkeypatch.setattr(start, "find_studio_server", lambda: None)+ started = {}+ fake = SimpleNamespace(pid = 999, poll = lambda: None)++ def fake_start(+ base,+ model,+ load,+ server_options = None,+ ):+ started.update(base = base, model = model)+ start._auto_served_server = fake+ return fake++ monkeypatch.setattr(start, "_start_studio_server", fake_start)+ monkeypatch.setattr(+ start, "_shutdown_server", lambda server: started.__setitem__("down", server)+ )+ monkeypatch.setattr(start.shutil, "which", lambda _: f"/usr/local/bin/{agent}")+ monkeypatch.setattr(start.subprocess, "run", lambda command, env: SimpleNamespace(returncode = 0))+ inner = start._http_json++ def http_json(+ method,+ url,+ token,+ payload = None,+ timeout = 30,+ error = None,+ ):+ if url.endswith("/api/inference/status"):+ raise urllib.error.HTTPError(url, 500, "Failed to get status", None, None)+ return inner(method, url, token, payload, timeout, error)++ monkeypatch.setattr(start, "_http_json", http_json)+ result = CliRunner().invoke(+ start.start_app, [agent, "--model", "unsloth/Qwen3-1.7B-GGUF", "--launch"]+ )+ assert result.exit_code == 0, result.output+ assert "needs a GGUF model" not in result.output+ assert started.get("down") is None++[email protected]("agent", ["claude", "codex"])+def test_a_status_body_without_is_gguf_still_launches(fake_studio, monkeypatch, agent):+ inner = start._http_json++ def http_json(+ method,+ url,+ token,+ payload = None,+ timeout = 30,+ error = None,+ ):+ if url.endswith("/api/inference/status"):+ return {"model_identifier": MODEL["id"]}+ return inner(method, url, token, payload, timeout, error)++ monkeypatch.setattr(start, "_http_json", http_json)+ result = CliRunner().invoke(start.start_app, [agent, "--no-launch"])+ assert result.exit_code == 0, result.output+ assert "needs a GGUF model" not in result.output