feat: distinguish authoritative model lists from cache

Author: unknownzjc

packages/types/src/vscode-extension-host.ts

@@ -172,6 +172,8 @@ export interface ExtensionMessage {
 	ollamaModels?: ModelRecord
 	lmStudioModels?: ModelRecord
 	fullResponseData?: ICostrictModelResponseData[]
+	/** Whether a costrictModels payload came directly from a successful provider request. */
+	modelListAuthoritative?: boolean
 	vsCodeLmModels?: { vendor?: string; family?: string; version?: string; id?: string }[]
 	mcpServers?: McpServer[]
 	commits?: GitCommit[]

src/api/providers/fetchers/__tests__/modelCache.spec.ts

@@ -58,7 +58,7 @@ vi.mock("../../../core/config/ContextProxy", () => ({
 import type { Mock } from "vitest"
 import * as fsSync from "fs"
 import NodeCache from "node-cache"
-import { getModels, getModelsFromCache } from "../modelCache"
+import { getModels, getModelsFromCache, getModelsWithMetadata, refreshModelsWithMetadata } from "../modelCache"
 import { getLiteLLMModels } from "../litellm"
 import { getOpenRouterModels } from "../openrouter"
 import { getRequestyModels } from "../requesty"
@@ -71,6 +71,78 @@ const mockGetCostrictModels = getCostrictModels as Mock<typeof getCostrictModels
 
 const DUMMY_REQUESTY_KEY = "requesty-key-for-testing"
 
+describe("model list authority metadata", () => {
+	beforeEach(() => {
+		vi.clearAllMocks()
+		const mockCache: any = new NodeCache()
+		mockCache.get.mockReturnValue(undefined)
+		vi.mocked(fsSync.existsSync).mockReturnValue(false)
+	})
+
+	afterEach(() => {
+		const mockCache: any = new NodeCache()
+		mockCache.get.mockReturnValue(undefined)
+	})
+
+	it("marks a direct provider response as authoritative", async () => {
+		const models = {
+			"openrouter/fresh-model": {
+				maxTokens: 8192,
+				contextWindow: 128000,
+				supportsPromptCache: false,
+			},
+		}
+		mockGetOpenRouterModels.mockResolvedValue(models)
+
+		await expect(getModelsWithMetadata({ provider: "openrouter" })).resolves.toEqual({
+			models,
+			authoritative: true,
+		})
+	})
+
+	it("marks a cache hit as non-authoritative", async () => {
+		const models = {
+			"openrouter/cached-model": {
+				maxTokens: 8192,
+				contextWindow: 128000,
+				supportsPromptCache: false,
+			},
+		}
+		const mockCache: any = new NodeCache()
+		mockCache.get.mockReturnValue(models)
+
+		await expect(getModelsWithMetadata({ provider: "openrouter" })).resolves.toEqual({
+			models,
+			authoritative: false,
+		})
+	})
+
+	it("marks refresh fallback data as non-authoritative", async () => {
+		const models = {
+			"costrict/cached-model": {
+				id: "costrict/cached-model",
+				maxTokens: 8192,
+				contextWindow: 128000,
+				supportsPromptCache: false,
+			},
+		}
+		const mockCache: any = new NodeCache()
+		mockCache.get.mockReturnValue(models)
+		mockGetCostrictModels.mockRejectedValue(new Error("API error"))
+
+		await expect(
+			refreshModelsWithMetadata({
+				provider: "costrict",
+				baseUrl: "https://api.example.com",
+				apiKey: "test-api-key",
+			}),
+		).resolves.toEqual({
+			models,
+			authoritative: false,
+		})
+	})
+})
+
 describe("getModels with new GetModelsOptions", () => {
 	beforeEach(() => {
 		vi.clearAllMocks()

src/api/providers/fetchers/costrict.ts

@@ -2,7 +2,6 @@ import axios from "axios"
 import { v7 as uuidv7 } from "uuid"
 import { COSTRICT_DEFAULT_HEADERS } from "../../../shared/headers"
 import type { InviteCodeInfo, ICostrictModelResponseData, QuotaInfo } from "@roo-code/types"
-import { readModels } from "./modelCache"
 import { CostrictAuthService } from "../../../core/costrict/auth"
 
 export async function getCostrictModels(
@@ -52,9 +51,7 @@ export async function getCostrictModels(
 			`Error fetching costrictModels from [${requestId}|${baseUrl}/ai-gateway/api/v1/models]:`,
 			error.message,
 		)
-		const modelCache = (await readModels("costrict")) || {}
-
-		return Object.keys(modelCache).map((key) => modelCache[key])
+		throw error
 	}
 }
 

src/api/providers/fetchers/modelCache.ts

@@ -36,9 +36,18 @@ 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)
 
+export interface ModelFetchResult {
+	models: ModelRecord
+	/**
+	 * True only when `models` came directly from a successful provider request.
+	 * Memory/disk cache hits and graceful-degradation fallbacks are never authoritative.
+	 */
+	authoritative: boolean
+}
+
 // 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>>()
+const inFlightRefresh = new Map<RouterName, Promise<ModelFetchResult>>()
 
 async function writeModels(router: RouterName, data: ModelRecord) {
 	const filename = `${router}_models.json`
@@ -137,7 +146,7 @@ async function fetchModelsFromProvider(options: GetModelsOptions): Promise<Model
  * @param baseUrl - Optional base URL for the provider (currently used only for LiteLLM).
  * @returns The models from the cache or the fetched models.
  */
-export const getModels = async (options: GetModelsOptions): Promise<ModelRecord> => {
+export const getModelsWithMetadata = async (options: GetModelsOptions): Promise<ModelFetchResult> => {
 	const { provider } = options
 	const refreshOnDiskCacheHit = "refreshOnDiskCacheHit" in options && options.refreshOnDiskCacheHit
 	const hadMemoryModels = memoryCache.get<ModelRecord>(provider) != null
@@ -156,7 +165,7 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
 						console.error(`[getModels] Background refresh failed for ${provider}:`, error)
 					})
 				}
-				return models
+				return { models, authoritative: false }
 			}
 		}
 		models = await fetchModelsFromProvider(options)
@@ -178,7 +187,7 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
 			})
 		}
 
-		return models
+		return { models, authoritative: true }
 	} catch (error) {
 		// Log the error and re-throw it so the caller can handle it (e.g., show a UI message).
 		console.error(`[getModels] Failed to fetch models in modelCache for ${provider}:`, error)
@@ -187,6 +196,9 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
 	}
 }
 
+export const getModels = async (options: GetModelsOptions): Promise<ModelRecord> =>
+	(await getModelsWithMetadata(options)).models
+
 /**
  * Force-refresh models from API, bypassing cache.
  * Uses atomic writes so cache remains available during refresh.
@@ -196,7 +208,7 @@ export const getModels = async (options: GetModelsOptions): Promise<ModelRecord>
  * @param options - Provider options for fetching models
  * @returns Fresh models from API, or existing cache if refresh yields worse data
  */
-export const refreshModels = async (options: GetModelsOptions): Promise<ModelRecord> => {
+export const refreshModelsWithMetadata = async (options: GetModelsOptions): Promise<ModelFetchResult> => {
 	const { provider } = options
 
 	// Check if there's already an in-flight refresh for this provider
@@ -208,7 +220,7 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 	}
 
 	// Create the refresh promise and track it
-	const refreshPromise = (async (): Promise<ModelRecord> => {
+	const refreshPromise = (async (): Promise<ModelFetchResult> => {
 		try {
 			// Force fresh API fetch - skip getModelsFromCache() check
 			const models = await fetchModelsFromProvider(options)
@@ -226,9 +238,9 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 					existingCacheSize: existingCount,
 				})
 				if (existingCount > 0) {
-					return existingCache!
+					return { models: existingCache!, authoritative: false }
 				} else {
-					return {}
+					return { models: {}, authoritative: false }
 				}
 			}
 
@@ -240,11 +252,11 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 				console.error(`[refreshModels] Error writing ${provider} models to disk:`, err),
 			)
 
-			return models
+			return { models, authoritative: true }
 		} catch (error) {
 			// Log the error for debugging, then return existing cache if available (graceful degradation)
 			console.error(`[refreshModels] Failed to refresh ${provider} models:`, error)
-			return getModelsFromCache(provider) || {}
+			return { models: getModelsFromCache(provider) || {}, authoritative: false }
 		} finally {
 			// Always clean up the in-flight tracking
 			inFlightRefresh.delete(provider)
@@ -257,6 +269,9 @@ export const refreshModels = async (options: GetModelsOptions): Promise<ModelRec
 	return refreshPromise
 }
 
+export const refreshModels = async (options: GetModelsOptions): Promise<ModelRecord> =>
+	(await refreshModelsWithMetadata(options)).models
+
 /**
  * Initialize background model cache refresh.
  * Refreshes public provider caches without blocking or requiring auth.
@@ -292,16 +307,16 @@ export async function initializeModelCacheRefresh(): Promise<void> {
 export const flushModels = async (
 	options: GetModelsOptions,
 	refresh: boolean = false,
-	cb?: (v: any) => void,
+	cb?: (models: ModelRecord, metadata: ModelFetchResult) => void,
 ): 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)
-			.then(cb)
+		await refreshModelsWithMetadata(options)
+			.then((result) => cb?.(result.models, result))
 			.catch((error) => {
 				console.log(`[flushModels] Refresh failed for ${provider}:`, error.message)
 			})

src/core/webview/__tests__/ClineProvider.spec.ts

@@ -294,6 +294,7 @@ vi.mock("../../../integrations/misc/extract-text", () => ({
 
 vi.mock("../../../api/providers/fetchers/modelCache", () => ({
 	getModels: vi.fn().mockResolvedValue({}),
+	getModelsWithMetadata: vi.fn().mockResolvedValue({ models: {}, authoritative: false }),
 	flushModels: vi.fn(),
 	getModelsFromCache: vi.fn().mockReturnValue(undefined),
 }))
@@ -368,6 +369,7 @@ vi.mock("../../../integrations/misc/extract-text", () => ({
 
 vi.mock("../../../api/providers/fetchers/modelCache", () => ({
 	getModels: vi.fn().mockResolvedValue({}),
+	getModelsWithMetadata: vi.fn().mockResolvedValue({ models: {}, authoritative: false }),
 	flushModels: vi.fn(),
 	getModelsFromCache: vi.fn().mockReturnValue(undefined),
 }))
@@ -3068,8 +3070,9 @@ describe("ClineProvider - Router Models", () => {
 			},
 		}
 
-		const { getModels } = await import("../../../api/providers/fetchers/modelCache")
+		const { getModels, getModelsWithMetadata } = await import("../../../api/providers/fetchers/modelCache")
 		vi.mocked(getModels).mockResolvedValue(mockModels)
+		vi.mocked(getModelsWithMetadata).mockResolvedValue({ models: mockModels, authoritative: false })
 
 		await messageHandler({ type: "requestRouterModels" })
 
@@ -3090,6 +3093,7 @@ describe("ClineProvider - Router Models", () => {
 			type: "costrictModels",
 			openAiModels: ["model-1", "model-2"],
 			fullResponseData: [mockModels["model-1"], mockModels["model-2"]],
+			modelListAuthoritative: false,
 		})
 
 		// Verify response was sent
@@ -3127,12 +3131,12 @@ describe("ClineProvider - Router Models", () => {
 		const mockModels = {
 			"model-1": { maxTokens: 4096, contextWindow: 8192, description: "Test model", supportsPromptCache: false },
 		}
-		const { getModels } = await import("../../../api/providers/fetchers/modelCache")
+		const { getModels, getModelsWithMetadata } = await import("../../../api/providers/fetchers/modelCache")
+		vi.mocked(getModelsWithMetadata).mockResolvedValue({ models: mockModels, authoritative: false })
 
 		// Mock some providers to succeed and others to fail
-		// Provider order in source: costrict, openrouter, requesty, vercel-ai-gateway, litellm (conditional)
+		// Costrict uses getModelsWithMetadata; remaining providers use getModels.
 		vi.mocked(getModels)
-			.mockResolvedValueOnce(mockModels) // costrict success (first call)
 			.mockResolvedValueOnce(mockModels) // openrouter success
 			.mockRejectedValueOnce(new Error("Requesty API error")) // requesty fail
 			.mockResolvedValueOnce(mockModels) // unbound success
@@ -3146,6 +3150,7 @@ describe("ClineProvider - Router Models", () => {
 			type: "costrictModels",
 			openAiModels: ["model-1"],
 			fullResponseData: [mockModels["model-1"]],
+			modelListAuthoritative: false,
 		})
 
 		// Verify main response includes successful providers and empty objects for failed ones
@@ -3198,8 +3203,9 @@ describe("ClineProvider - Router Models", () => {
 		const mockModels = {
 			"model-1": { maxTokens: 4096, contextWindow: 8192, description: "Test model", supportsPromptCache: false },
 		}
-		const { getModels } = await import("../../../api/providers/fetchers/modelCache")
+		const { getModels, getModelsWithMetadata } = await import("../../../api/providers/fetchers/modelCache")
 		vi.mocked(getModels).mockResolvedValue(mockModels)
+		vi.mocked(getModelsWithMetadata).mockResolvedValue({ models: mockModels, authoritative: false })
 
 		await messageHandler({
 			type: "requestRouterModels",
@@ -3232,10 +3238,9 @@ describe("ClineProvider - Router Models", () => {
 		const mockModels = {
 			"model-1": { maxTokens: 4096, contextWindow: 8192, description: "Test model", supportsPromptCache: false },
 		}
-		const { getModels } = await import("../../../api/providers/fetchers/modelCache")
-		vi.mocked(getModels)
-			.mockResolvedValueOnce(mockModels) // costrict success (first call)
-			.mockResolvedValue(mockModels) // other providers success
+		const { getModels, getModelsWithMetadata } = await import("../../../api/providers/fetchers/modelCache")
+		vi.mocked(getModels).mockResolvedValue(mockModels)
+		vi.mocked(getModelsWithMetadata).mockResolvedValue({ models: mockModels, authoritative: false })
 
 		await messageHandler({ type: "requestRouterModels" })
 
@@ -3251,6 +3256,7 @@ describe("ClineProvider - Router Models", () => {
 			type: "costrictModels",
 			openAiModels: ["model-1"],
 			fullResponseData: [mockModels["model-1"]],
+			modelListAuthoritative: false,
 		})
 
 		// Verify response includes empty object for LiteLLM