fix: LiteLLM provider model desync after Sync Models or settings navigation

- Invalidate React Query router-models cache on successful sync in LiteLLM.tsx
  so useSelectedModel picks up the refreshed list (mirrors Poe.tsx fix)
- Preserve configured litellm model ID when model list is empty/loading in
  useSelectedModel.ts instead of silently falling back to hardcoded default
- Pass litellm credentials in the debounced requestRouterModels message in
  ApiOptions.tsx to prevent fetches with stale config from clearing the model list

Author: awschmeder

.changeset/fix-litellm-model-desync.md

@@ -0,0 +1,26 @@
+---
+"zoo-code": patch
+---
+
+Fix LiteLLM provider cache key collision, credential priority, and model-selection fallback to non-existent default.
+
+Two bugs are addressed:
+
+1. **Cache key collision**: All URL-scoped providers (LiteLLM, Ollama, LM Studio, Poe, DeepSeek,
+   Requesty) previously shared one cache entry keyed only on the provider name. Switching between
+   profiles backed by different servers silently served the wrong model list and the stale list
+   persisted across VS Code restarts via the disk cache. Fixed with a compound cache key:
+   URL-scoped providers use `provider:baseUrl`; key-scoped providers (LiteLLM, Poe, Requesty)
+   additionally include a short sha256 hash of the API key (`provider:baseUrl:sha256(apiKey)`) so that
+   two different API keys on the same server never share a cache entry (relevant when the server
+   enforces per-key model allowlists). The `RouterProvider.getModel()` cold-start fallback is also
+   corrected to pass the full options so it resolves the same compound key.
+
+2. **Silent fallback to hardcoded default**: When the LiteLLM model list was empty (due to the
+   collision above, a failed sync, or a transient error), `useSelectedModel` reset the configured
+   model ID to `claude-3-7-sonnet-20250219` -- a model that typically does not exist on user
+   LiteLLM servers. Four sub-fixes: preserve the configured model ID when the list is empty;
+   invalidate the React Query router-models cache after a successful "Sync Models" click; pass the
+   current LiteLLM credentials in the debounced `requestRouterModels` message; and correct the
+   credential priority in `webviewMessageHandler.ts` so that message values (current unsaved field
+   state) take precedence over stale saved config, matching the pattern already used for DeepSeek.

src/api/providers/fetchers/modelCache.ts

@@ -1,6 +1,7 @@
 import * as path from "path"
 import fs from "fs/promises"
 import * as fsSync from "fs"
+import { createHash } from "crypto"
 
 import NodeCache from "node-cache"
 import { z } from "zod"
@@ -34,28 +35,86 @@ const memoryCache = new NodeCache({ stdTTL: 5 * 60, checkperiod: 5 * 60 })
 // Zod schema for validating ModelRecord structure from disk cache
 const modelRecordSchema = z.record(z.string(), modelInfoSchema)
 
-// Track in-flight refresh requests to prevent concurrent API calls for the same provider
-// This prevents race conditions where multiple calls might overwrite each other's results
-const inFlightRefresh = new Map<RouterName, Promise<ModelRecord>>()
+// Track in-flight refresh requests to prevent concurrent API calls for the same provider+url.
+// Keyed on the compound cache key (see getCacheKey) so that two different LiteLLM servers never
+// deduplicate each other's in-flight refreshes.
+const inFlightRefresh = new Map<string, Promise<ModelRecord>>()
 
 // Providers whose model lists are scoped to the signed-in user (e.g. per-account
 // allowlists or org policies). For these we MUST NOT cache results on disk or
 // in memory: a sign-in/out cycle could otherwise serve a previous user's model
 // list to the next user, and stale data could mask backend allowlist updates.
 const AUTH_SCOPED_PROVIDERS: ReadonlySet<RouterName> = new Set(["zoo-gateway"])
 
+// Providers whose model list is determined by the server URL, not just by the provider name.
+// Each unique baseUrl must be cached independently so that switching endpoints never serves
+// stale results from a previously-cached server.
+const URL_SCOPED_PROVIDERS: ReadonlySet<RouterName> = new Set([
+	"litellm",
+	"poe",
+	"deepseek",
+	"ollama",
+	"lmstudio",
+	"requesty",
+])
+
+// Providers where the API key itself determines which models are visible (e.g. per-key
+// allowlists on a shared proxy). For these the cache key also includes a short hash of
+// the API key so that two different keys on the same server never share a cache entry.
+const KEY_SCOPED_PROVIDERS: ReadonlySet<RouterName> = new Set([
+	"litellm", // Per-key model allowlists are a first-class LiteLLM proxy feature
+	"poe", // Per-account model availability
+	"requesty", // Per-account custom model policies
+])
+
 function isAuthScopedProvider(provider: RouterName): boolean {
 	return AUTH_SCOPED_PROVIDERS.has(provider)
 }
 
-async function writeModels(router: RouterName, data: ModelRecord) {
-	const filename = `${router}_models.json`
+/**
+ * Build a cache key that is unique per provider+server+key combination.
+ *
+ * - URL-scoped providers include the normalized baseUrl so that two different servers
+ *   of the same provider type never share a cache entry.
+ * - Key-scoped providers additionally fold in a short sha256 hash of the API key so that
+ *   two different API keys on the same server never share a cache entry (relevant when
+ *   the server enforces per-key model allowlists, e.g. LiteLLM, Poe, Requesty).
+ */
+function getCacheKey(options: GetModelsOptions): string {
+	const { provider } = options
+	const isUrlScoped = URL_SCOPED_PROVIDERS.has(provider as RouterName)
+	const isKeyScoped = KEY_SCOPED_PROVIDERS.has(provider as RouterName)
+
+	if (isUrlScoped && options.baseUrl) {
+		// Strip trailing slashes so "http://host:4000/" and "http://host:4000" map to the same key.
+		const normalizedUrl = options.baseUrl.replace(/\/+$/, "")
+		if (isKeyScoped && options.apiKey) {
+			// Short (16-char) sha256 prefix -- enough to make collisions effectively impossible
+			// while keeping filenames readable. We do not need the full digest here.
+			const keyHash = createHash("sha256").update(options.apiKey).digest("hex").slice(0, 16)
+			return `${provider}:${normalizedUrl}:${keyHash}`
+		}
+		return `${provider}:${normalizedUrl}`
+	}
+	return provider
+}
+
+/**
+ * Convert a cache key to a filesystem-safe filename component.
+ * Replaces characters that are illegal or awkward in filenames with underscores.
+ */
+function cacheKeyToFilename(cacheKey: string): string {
+	return cacheKey.replace(/[:/\\?#*<>|"\s]+/g, "_")
+}
+
+async function writeModels(cacheKey: string, data: ModelRecord) {
+	const filename = `${cacheKeyToFilename(cacheKey)}_models.json`
 	const cacheDir = await getCacheDirectoryPath(ContextProxy.instance.globalStorageUri.fsPath)
 	await safeWriteJson(path.join(cacheDir, filename), data)
 }
 
-async function readModels(router: RouterName): Promise<ModelRecord | undefined> {
-	const filename = `${router}_models.json`
+async function readModels(cacheKey: string): Promise<ModelRecord | undefined> {
+	const filename = `${cacheKeyToFilename(cacheKey)}_models.json`
 	const cacheDir = await getCacheDirectoryPath(ContextProxy.instance.globalStorageUri.fsPath)
 	const filePath = path.join(cacheDir, filename)
 	const exists = await fileExistsAtPath(filePath)
@@ -133,10 +192,11 @@ async function fetchModelsFromProvider(options: GetModelsOptions): Promise<Model
  */
 export const getModels = async (options: GetModelsOptions): Promise<ModelRecord> => {
 	const { provider } = options
+	const cacheKey = getCacheKey(options)
 
 	const shouldSkipCache = isAuthScopedProvider(provider)
 
-	let models = shouldSkipCache ? undefined : getModelsFromCache(provider)
+	let models = shouldSkipCache ? undefined : getModelsFromCache(options)
 
 	if (models) {
 		return models
@@ -149,10 +209,10 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
 		// Only cache non-empty results so a failed API response doesn't get persisted
 		// as if the provider had no models. Auth-scoped providers skip caching entirely.
 		if (modelCount > 0 && !shouldSkipCache) {
-			memoryCache.set(provider, models)
+			memoryCache.set(cacheKey, models)
 
-			await writeModels(provider, models).catch((err) =>
-				console.error(`[MODEL_CACHE] Error writing ${provider} models to file cache:`, err),
+			await writeModels(cacheKey, models).catch((err) =>
+				console.error(`[MODEL_CACHE] Error writing ${cacheKey} models to file cache:`, err),
 			)
 		} else if (modelCount === 0) {
 			TelemetryService.instance.captureEvent(TelemetryEventName.MODEL_CACHE_EMPTY_RESPONSE, {
@@ -182,17 +242,18 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
  */
 export const refreshModels = async (options: GetModelsOptions): Promise<ModelRecord> => {
 	const { provider } = options
+	const cacheKey = getCacheKey(options)
 
 	const shouldSkipCache = isAuthScopedProvider(provider)
 
-	// Check if there's already an in-flight refresh for this provider.
+	// Check if there's already an in-flight refresh for this provider+url combination.
 	// This prevents race conditions where multiple concurrent refreshes might
 	// overwrite each other's results. Skip de-duplication for auth-scoped
 	// providers because two concurrent calls may carry different tokens
 	// (e.g., after a sign-out/sign-in within the same session) and we must
 	// not return the first caller's results to the second caller.
 	if (!shouldSkipCache) {
-		const existingRequest = inFlightRefresh.get(provider)
+		const existingRequest = inFlightRefresh.get(cacheKey)
 		if (existingRequest) {
 			return existingRequest
 		}
@@ -206,7 +267,7 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 			const modelCount = Object.keys(models).length
 
 			// Get existing cached data for comparison
-			const existingCache = shouldSkipCache ? undefined : getModelsFromCache(provider)
+			const existingCache = shouldSkipCache ? undefined : getModelsFromCache(options)
 			const existingCount = existingCache ? Object.keys(existingCache).length : 0
 
 			if (modelCount === 0) {
@@ -224,34 +285,34 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 			}
 
 			if (!shouldSkipCache) {
-				memoryCache.set(provider, models)
+				memoryCache.set(cacheKey, models)
 
-				await writeModels(provider, models).catch((err) =>
-					console.error(`[refreshModels] Error writing ${provider} models to disk:`, err),
+				await writeModels(cacheKey, models).catch((err) =>
+					console.error(`[refreshModels] Error writing ${cacheKey} models to disk:`, err),
 				)
 			}
 
 			return models
 		} catch (error) {
 			// Log the error for debugging, then return existing cache if available (graceful degradation).
 			// For auth-scoped providers (zoo-gateway) we MUST NOT return cached models from a prior
-			// session, since they could belong to a different user — return empty instead.
-			console.error(`[refreshModels] Failed to refresh ${provider} models:`, error)
+			// session, since they could belong to a different user -- return empty instead.
+			console.error(`[refreshModels] Failed to refresh ${cacheKey} models:`, error)
 			if (shouldSkipCache) {
 				return {}
 			}
-			return getModelsFromCache(provider) || {}
+			return getModelsFromCache(options) || {}
 		} finally {
 			// Always clean up the in-flight tracking
 			if (!shouldSkipCache) {
-				inFlightRefresh.delete(provider)
+				inFlightRefresh.delete(cacheKey)
 			}
 		}
 	})()
 
 	// Track the in-flight request (auth-scoped providers are excluded; see above).
 	if (!shouldSkipCache) {
-		inFlightRefresh.set(provider, refreshPromise)
+		inFlightRefresh.set(cacheKey, refreshPromise)
 	}
 
 	return refreshPromise
@@ -290,16 +351,17 @@ export async function initializeModelCacheRefresh(): Promise<void> {
  * @param refresh - If true, immediately fetch fresh data from API
  */
 export const flushModels = async (options: GetModelsOptions, refresh: boolean = false): Promise<void> => {
-	const { provider } = options
 	if (refresh) {
 		// Don't delete memory cache - let refreshModels atomically replace it
 		// This prevents a race condition where getModels() might be called
 		// before refresh completes, avoiding a gap in cache availability
 		// Await the refresh to ensure the cache is updated before returning
 		await refreshModels(options)
 	} else {
-		// Only delete memory cache when not refreshing
-		memoryCache.del(provider)
+		// Only delete memory cache when not refreshing. Use the compound cache key so that
+		// URL-scoped providers (litellm, poe, etc.) actually evict the per-server entry rather
+		// than a bare provider-name entry that was never written.
+		memoryCache.del(getCacheKey(options))
 	}
 }
 
@@ -311,17 +373,20 @@ export const flushModels = async (options: GetModelsOptions, refresh: boolean =
  * @param provider - The provider to get models for.
  * @returns Models from memory cache, disk cache, or undefined if not cached.
  */
-export function getModelsFromCache(provider: ProviderName): ModelRecord | undefined {
+export function getModelsFromCache(
+	options: GetModelsOptions | ProviderName,
+): ModelRecord | undefined {
+	const cacheKey = typeof options === "string" ? options : getCacheKey(options)
 	// Check memory cache first (fast)
-	const memoryModels = memoryCache.get<ModelRecord>(provider)
+	const memoryModels = memoryCache.get<ModelRecord>(cacheKey)
 	if (memoryModels) {
 		return memoryModels
 	}
 
 	// Memory cache miss - try to load from disk synchronously
 	// This is acceptable because it only happens on cold start or after cache expiry
 	try {
-		const filename = `${provider}_models.json`
+		const filename = `${cacheKeyToFilename(cacheKey)}_models.json`
 		const cacheDir = getCacheDirectoryPathSync()
 		if (!cacheDir) {
 			return undefined
@@ -339,19 +404,19 @@ export function getModelsFromCache(provider: ProviderName): ModelRecord | undefi
 			const validation = modelRecordSchema.safeParse(models)
 			if (!validation.success) {
 				console.error(
-					`[MODEL_CACHE] Invalid disk cache data structure for ${provider}:`,
+					`[MODEL_CACHE] Invalid disk cache data structure for ${cacheKey}:`,
 					validation.error.format(),
 				)
 				return undefined
 			}
 
 			// Populate memory cache for future fast access
-			memoryCache.set(provider, validation.data)
+			memoryCache.set(cacheKey, validation.data)
 
 			return validation.data
 		}
 	} catch (error) {
-		console.error(`[MODEL_CACHE] Error loading ${provider} models from disk:`, error)
+		console.error(`[MODEL_CACHE] Error loading ${cacheKey} models from disk:`, error)
 	}
 
 	return undefined

src/api/providers/router-provider.ts

@@ -69,9 +69,14 @@ export abstract class RouterProvider extends BaseProvider {
 			return { id, info: this.models[id] }
 		}
 
-		// Fall back to global cache (synchronous disk/memory cache)
-		// This ensures models are available before fetchModel() is called
-		const cachedModels = getModelsFromCache(this.name)
+		// Fall back to global cache (synchronous disk/memory cache).
+		// Pass the full options so URL-scoped providers (litellm, ollama, etc.)
+		// resolve the same compound cache key that fetchModel() wrote under.
+		const cachedModels = getModelsFromCache({
+			provider: this.name,
+			baseUrl: this.client.baseURL,
+			apiKey: this.client.apiKey,
+		})
 		if (cachedModels?.[id]) {
 			// Also populate instance models for future calls
 			this.models = cachedModels

src/core/webview/webviewMessageHandler.ts

@@ -1074,9 +1074,11 @@ export const webviewMessageHandler = async (
 				},
 			]
 
-			// LiteLLM is conditional on baseUrl+apiKey
-			const litellmApiKey = apiConfiguration.litellmApiKey || message?.values?.litellmApiKey
-			const litellmBaseUrl = apiConfiguration.litellmBaseUrl || message?.values?.litellmBaseUrl
+			// LiteLLM is conditional on baseUrl+apiKey.
+			// Prefer explicit values from message (current unsaved field state) over saved config,
+			// matching the pattern used for DeepSeek and other credential-carrying providers.
+			const litellmApiKey = message?.values?.litellmApiKey ?? apiConfiguration.litellmApiKey
+			const litellmBaseUrl = message?.values?.litellmBaseUrl ?? apiConfiguration.litellmBaseUrl
 
 			if (litellmApiKey && litellmBaseUrl) {
 				// If explicit credentials are provided in message.values (from Refresh Models button),

webview-ui/src/components/settings/ApiOptions.tsx

@@ -222,7 +222,15 @@ const ApiOptions = ({
 				requestLmStudioModels(apiConfiguration?.lmStudioBaseUrl)
 			} else if (selectedProvider === "vscode-lm") {
 				vscode.postMessage({ type: "requestVsCodeLmModels" })
-			} else if (selectedProvider === "litellm" || selectedProvider === "poe") {
+			} else if (selectedProvider === "litellm") {
+				vscode.postMessage({
+					type: "requestRouterModels",
+					values: {
+						litellmApiKey: apiConfiguration?.litellmApiKey,
+						litellmBaseUrl: apiConfiguration?.litellmBaseUrl,
+					},
+				})
+			} else if (selectedProvider === "poe") {
 				vscode.postMessage({ type: "requestRouterModels" })
 			}
 		},

webview-ui/src/components/settings/providers/LiteLLM.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useState, useEffect, useRef } from "react"
 import { VSCodeTextField, VSCodeCheckbox } from "@vscode/webview-ui-toolkit/react"
+import { useQueryClient } from "@tanstack/react-query"
 
 import {
 	type ProviderSettings,
@@ -34,6 +35,7 @@ export const LiteLLM = ({
 	simplifySettings,
 }: LiteLLMProps) => {
 	const { t } = useAppTranslation()
+	const queryClient = useQueryClient()
 	const { routerModels } = useExtensionState()
 	const [refreshStatus, setRefreshStatus] = useState<"idle" | "loading" | "success" | "error">("idle")
 	const [refreshError, setRefreshError] = useState<string | undefined>()
@@ -55,6 +57,9 @@ export const LiteLLM = ({
 				if (refreshStatus === "loading") {
 					if (!litellmErrorJustReceived.current) {
 						setRefreshStatus("success")
+						// Invalidate the react-query router models cache so
+						// useSelectedModel picks up the refreshed list.
+						queryClient.invalidateQueries({ queryKey: ["routerModels"] })
 					}
 					// If litellmErrorJustReceived.current is true, status is already (or will be) "error".
 				}
@@ -65,7 +70,7 @@ export const LiteLLM = ({
 		return () => {
 			window.removeEventListener("message", handleMessage)
 		}
-	}, [refreshStatus, refreshError, setRefreshStatus, setRefreshError])
+	}, [refreshStatus, queryClient])
 
 	const handleInputChange = useCallback(
 		<K extends keyof ProviderSettings, E>(