Skip to content

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

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.ts
index 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.tsx
index 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 help
agentPickedByUserRef.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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.py
index 013ce3f7a8a..98308519318 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -7,7 +7,9 @@ import atexit
import base64
import contextlib
import errno
+import functools
import hashlib
+import http.client
import json
import os
import 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(
return
files = _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 = False
if 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)
return
if 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)
return
if not variant and isinstance(info.get("loadable"), bool):
if not info["loadable"]:
- _fail_codex_needs_gguf(candidate)
+ _fail_agent_needs_gguf(agent, candidate)
return
if 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)
return
if 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(
return
except 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()
+ raise
model_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()
raise
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index 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.client
import io
import json
import 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_json
def 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.output
result = 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, capsys
def 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 == 1
err = capsys.readouterr().err
assert "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_pat
calls = _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().err
def 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().err
assert "no GGUF variant Q4_KM" in err
assert "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, capsys
lambda 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, monkeypatc
target = 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, monkeypatc
monkeypatch.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, c
remote = "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().err
assert 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().err
with 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(monkeypat
return {"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, monkey
monkeypatch.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().err
assert "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(monkeypatch
monkeypatch.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(monkeypat
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 / "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, monkeypatch
link = 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, monkeypatc
empty = 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().err
shard = 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, monkeypatch
links.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, pa
lambda *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, monkeyp
monkeypatch.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, ca
monkeypatch.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) == 2
assert "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_pa
monkeypatch.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) == 1
assert "Qwen3-0.6B-GGUF" in capsys.readouterr().err
@@ -7998,14 +8064,14 @@ def test_codex_attach_check_defers_shorthand_when_canonical_probe_errors(monkeyp
raise 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) == 1
assert "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