feat: load models through provider adapters

Provider model selection had outgrown a single hardcoded service. The old service mixed shared caching with provider catalogs and CLI lookup details. That made stale model lists more likely as providers changed on separate schedules. Move model discovery behind each provider so lookup lives next to the integration. The shared service now focuses on provider resolution, caching, persistence, and dedupe. Return cache metadata and add bypassCache because model availability changes outside the app. The UI and /models command can show freshness and let users force a provider refresh. Surface model descriptions while keeping fallback catalogs for unavailable CLIs or SDKs.
2026-05-28 23:15:33 +08:00 · 2026-05-18 12:40:24 +03:00
parent ffaef395e4
commit 556cbd1a03
28 changed files with 1125 additions and 483 deletions
--- a/src/components/chat/hooks/useChatComposerState.ts
+++ b/src/components/chat/hooks/useChatComposerState.ts
@@ -20,7 +20,7 @@ import type {
  PendingPermissionRequest,
  PermissionMode,
 } from '../types/types';
-import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider, ProviderModelsCacheInfo } from '../../../types/app';
 import { escapeRegExp } from '../utils/chatFormatting';

 import { useFileMentions } from './useFileMentions';
@@ -87,8 +87,10 @@ export type ModelCommandData = {
  availableOptions?: Array<{
    value: string;
    label?: string;
+    description?: string;
  }>;
  defaultModel?: string;
+  cache?: ProviderModelsCacheInfo;
 };

 export type CostCommandData = {
--- a/src/components/chat/hooks/useChatProviderState.ts
+++ b/src/components/chat/hooks/useChatProviderState.ts
@@ -1,7 +1,13 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { authenticatedFetch } from '../../../utils/api';
 import type { PendingPermissionRequest, PermissionMode } from '../types/types';
-import type { ProjectSession, LLMProvider, Project, ProviderModelsDefinition } from '../../../types/app';
+import type {
+  ProjectSession,
+  LLMProvider,
+  Project,
+  ProviderModelsCacheInfo,
+  ProviderModelsDefinition,
+} from '../../../types/app';

 const FALLBACK_DEFAULT_MODEL: Record<LLMProvider, string> = {
  claude: 'opus',
@@ -29,6 +35,14 @@ interface UseChatProviderStateArgs {
  selectedProject: Project | null;
 }

+type ProviderModelsApiResponse = {
+  success?: boolean;
+  data?: {
+    models?: ProviderModelsDefinition;
+    cache?: ProviderModelsCacheInfo;
+  };
+};
+
 export function useChatProviderState({ selectedSession, selectedProject }: UseChatProviderStateArgs) {
  const [permissionMode, setPermissionMode] = useState<PermissionMode>('default');
  const [pendingPermissionRequests, setPendingPermissionRequests] = useState<PendingPermissionRequest[]>([]);
@@ -54,63 +68,78 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
  const [providerModelCatalog, setProviderModelCatalog] = useState<
    Partial<Record<LLMProvider, ProviderModelsDefinition>>
  >({});
+  const [providerModelCacheCatalog, setProviderModelCacheCatalog] = useState<
+    Partial<Record<LLMProvider, ProviderModelsCacheInfo>>
+  >({});
  const [providerModelsLoading, setProviderModelsLoading] = useState(true);
+  const [providerModelsRefreshing, setProviderModelsRefreshing] = useState(false);

  const lastProviderRef = useRef(provider);
+  const providerModelsRequestIdRef = useRef(0);

-  const workspacePath = selectedProject?.fullPath || selectedProject?.path || '';
-
-  useEffect(() => {
-    let cancelled = false;
+  const loadProviderModels = useCallback(async (options: { bypassCache?: boolean } = {}) => {
    const providers: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+    const requestId = providerModelsRequestIdRef.current + 1;
+    providerModelsRequestIdRef.current = requestId;
+    const isHardRefresh = options.bypassCache === true;

-    const load = async () => {
+    if (isHardRefresh) {
+      setProviderModelsRefreshing(true);
+    } else {
      setProviderModelsLoading(true);
-      try {
-        const results = await Promise.all(
-          providers.map(async (p) => {
-            const qs =
-              p === 'opencode' && workspacePath
-                ? `?workspacePath=${encodeURIComponent(workspacePath)}`
-                : '';
-            const response = await authenticatedFetch(`/api/providers/${p}/models${qs}`);
-            const body = (await response.json()) as {
-              success?: boolean;
-              data?: { models?: ProviderModelsDefinition };
-            };
-            if (!body.success || !body.data?.models) {
-              return null;
-            }
-            return body.data.models;
-          }),
-        );
+    }

-        if (cancelled) {
+    try {
+      const results = await Promise.all(
+        providers.map(async (p) => {
+          const params = new URLSearchParams();
+          if (options.bypassCache) {
+            params.set('bypassCache', 'true');
+          }
+
+          const queryString = params.toString();
+          const response = await authenticatedFetch(`/api/providers/${p}/models${queryString ? `?${queryString}` : ''}`);
+          const body = (await response.json()) as ProviderModelsApiResponse;
+          if (!body.success || !body.data?.models || !body.data?.cache) {
+            return null;
+          }
+
+          return body.data;
+        }),
+      );
+
+      if (providerModelsRequestIdRef.current !== requestId) {
+        return;
+      }
+
+      const nextCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>> = {};
+      const nextCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>> = {};
+
+      providers.forEach((p, i) => {
+        const entry = results[i];
+        if (!entry) {
          return;
        }

-        const next: Partial<Record<LLMProvider, ProviderModelsDefinition>> = {};
-        providers.forEach((p, i) => {
-          const entry = results[i];
-          if (entry) {
-            next[p] = entry;
-          }
-        });
-        setProviderModelCatalog(next);
-      } catch (error) {
-        console.error('Error loading provider models:', error);
-      } finally {
-        if (!cancelled) {
-          setProviderModelsLoading(false);
-        }
-      }
-    };
+        nextCatalog[p] = entry.models;
+        nextCacheCatalog[p] = entry.cache;
+      });

-    void load();
-    return () => {
-      cancelled = true;
-    };
-  }, [workspacePath]);
+      setProviderModelCatalog(nextCatalog);
+      setProviderModelCacheCatalog(nextCacheCatalog);
+    } catch (error) {
+      console.error('Error loading provider models:', error);
+    } finally {
+      if (providerModelsRequestIdRef.current === requestId) {
+        setProviderModelsLoading(false);
+        setProviderModelsRefreshing(false);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadProviderModels();
+  }, [loadProviderModels]);

  const pickStoredOrCurrent = (
    storageKey: string,
@@ -279,6 +308,9 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
    setPendingPermissionRequests,
    cyclePermissionMode,
    providerModelCatalog,
+    providerModelCacheCatalog,
    providerModelsLoading,
+    providerModelsRefreshing,
+    hardRefreshProviderModels: () => loadProviderModels({ bypassCache: true }),
  };
 }
--- a/src/components/chat/view/ChatInterface.tsx
+++ b/src/components/chat/view/ChatInterface.tsx
@@ -79,7 +79,10 @@ function ChatInterface({
    setPendingPermissionRequests,
    cyclePermissionMode,
    providerModelCatalog,
+    providerModelCacheCatalog,
    providerModelsLoading,
+    providerModelsRefreshing,
+    hardRefreshProviderModels,
  } = useChatProviderState({
    selectedSession,
    selectedProject,
@@ -328,7 +331,10 @@ function ChatInterface({
          opencodeModel={opencodeModel}
          setOpenCodeModel={setOpenCodeModel}
          providerModelCatalog={providerModelCatalog}
+          providerModelCacheCatalog={providerModelCacheCatalog}
          providerModelsLoading={providerModelsLoading}
+          providerModelsRefreshing={providerModelsRefreshing}
+          onHardRefreshProviderModels={hardRefreshProviderModels}
          tasksEnabled={tasksEnabled}
          isTaskMasterInstalled={isTaskMasterInstalled}
          onShowAllTasks={onShowAllTasks}
@@ -431,6 +437,10 @@ function ChatInterface({
      <CommandResultModal
        payload={commandModalPayload}
        onClose={closeCommandModal}
+        providerModelCatalog={providerModelCatalog}
+        providerModelCacheCatalog={providerModelCacheCatalog}
+        providerModelsRefreshing={providerModelsRefreshing}
+        onHardRefreshProviderModels={hardRefreshProviderModels}
      />
    </PermissionContext.Provider>
  );
--- a/src/components/chat/view/subcomponents/ChatMessagesPane.tsx
+++ b/src/components/chat/view/subcomponents/ChatMessagesPane.tsx
@@ -2,7 +2,13 @@ import { useTranslation } from 'react-i18next';
 import { useCallback, useRef } from 'react';
 import type { Dispatch, RefObject, SetStateAction } from 'react';
 import type { ChatMessage } from '../../types/types';
-import type { Project, ProjectSession, LLMProvider, ProviderModelsDefinition } from '../../../../types/app';
+import type {
+  Project,
+  ProjectSession,
+  LLMProvider,
+  ProviderModelsCacheInfo,
+  ProviderModelsDefinition,
+} from '../../../../types/app';
 import { getIntrinsicMessageKey } from '../../utils/messageKeys';
 import MessageComponent from './MessageComponent';
 import ProviderSelectionEmptyState from './ProviderSelectionEmptyState';
@@ -29,7 +35,10 @@ interface ChatMessagesPaneProps {
  opencodeModel: string;
  setOpenCodeModel: (model: string) => void;
  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
  providerModelsLoading: boolean;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
  tasksEnabled: boolean;
  isTaskMasterInstalled: boolean | null;
  onShowAllTasks?: (() => void) | null;
@@ -78,7 +87,10 @@ export default function ChatMessagesPane({
  opencodeModel,
  setOpenCodeModel,
  providerModelCatalog,
+  providerModelCacheCatalog,
  providerModelsLoading,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
  tasksEnabled,
  isTaskMasterInstalled,
  onShowAllTasks,
@@ -165,7 +177,10 @@ export default function ChatMessagesPane({
          opencodeModel={opencodeModel}
          setOpenCodeModel={setOpenCodeModel}
          providerModelCatalog={providerModelCatalog}
+          providerModelCacheCatalog={providerModelCacheCatalog}
          providerModelsLoading={providerModelsLoading}
+          providerModelsRefreshing={providerModelsRefreshing}
+          onHardRefreshProviderModels={onHardRefreshProviderModels}
          tasksEnabled={tasksEnabled}
          isTaskMasterInstalled={isTaskMasterInstalled}
          onShowAllTasks={onShowAllTasks}
--- a/src/components/chat/view/subcomponents/CommandResultModal.tsx
+++ b/src/components/chat/view/subcomponents/CommandResultModal.tsx
@@ -16,11 +16,13 @@ import {
  Sparkles,
  TerminalSquare,
  Timer,
+  RefreshCw,
  X,
  Zap,
 } from 'lucide-react';

 import { Badge, Button, Dialog, DialogContent, DialogTitle, Input } from '../../../../shared/view/ui';
+import type { LLMProvider, ProviderModelsCacheInfo, ProviderModelsDefinition } from '../../../../types/app';
 import type {
  CommandModalPayload,
  CostCommandData,
@@ -32,6 +34,10 @@ import type {
 type CommandResultModalProps = {
  payload: CommandModalPayload | null;
  onClose: () => void;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
 };

 type CommandEntry = {
@@ -43,6 +49,20 @@ type CommandEntry = {
 type ModelOption = {
  value: string;
  label?: string;
+  description?: string;
+};
+
+const formatUpdatedAt = (value?: string) => {
+  if (!value) {
+    return 'Not cached yet';
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return 'Not cached yet';
+  }
+
+  return parsed.toLocaleString();
 };

 const PROVIDER_LABELS: Record<string, string> = {
@@ -94,11 +114,13 @@ function MetricCard({
  value,
  icon: Icon,
  tone = 'neutral',
+  compact = false,
 }: {
  label: string;
  value: string;
  icon: typeof Activity;
  tone?: 'neutral' | 'primary' | 'success';
+  compact?: boolean;
 }) {
  const toneClass =
    tone === 'primary'
@@ -108,12 +130,16 @@ function MetricCard({
        : 'border-border/70 bg-background/75 text-muted-foreground';

  return (
-    <div className="group rounded-2xl border border-border/70 bg-background/75 p-4 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:border-primary/25 hover:shadow-md">
-      <div className={`mb-3 inline-flex rounded-xl border p-2 ${toneClass}`}>
-        <Icon className="h-4 w-4" />
+    <div
+      className={`group rounded-2xl border border-border/70 bg-background/75 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:border-primary/25 hover:shadow-md ${
+        compact ? 'p-3' : 'p-4'
+      }`}
+    >
+      <div className={`inline-flex rounded-xl border ${compact ? 'mb-2 p-1.5' : 'mb-3 p-2'} ${toneClass}`}>
+        <Icon className={compact ? 'h-3.5 w-3.5' : 'h-4 w-4'} />
      </div>
      <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">{label}</p>
-      <p className="mt-1 break-all text-sm font-semibold text-foreground">{value}</p>
+      <p className={`${compact ? 'mt-0.5 text-[13px]' : 'mt-1 text-sm'} break-all font-semibold text-foreground`}>{value}</p>
    </div>
  );
 }
@@ -222,21 +248,39 @@ function HelpContent({ data }: { data: HelpCommandData }) {
  );
 }

-function ModelsContent({ data }: { data: ModelCommandData }) {
+function ModelsContent({
+  data,
+  providerModelCatalog,
+  providerModelCacheCatalog,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
+}: {
+  data: ModelCommandData;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
+}) {
  const [query, setQuery] = useState('');
  const [copiedModel, setCopiedModel] = useState<string | null>(null);
-  const currentProvider = data?.current?.provider || 'claude';
+  const currentProvider = (data?.current?.provider || 'claude') as LLMProvider;
  const currentModel = data?.current?.model || 'Unknown';
-  const defaultModel = data?.defaultModel || currentModel;
  const providerLabel = data?.current?.providerLabel || getProviderLabel(currentProvider);
+  const liveDefinition = providerModelCatalog[currentProvider];
+  const currentCache = providerModelCacheCatalog[currentProvider] ?? data?.cache;
  const availableOptions = useMemo<ModelOption[]>(() => {
+    if (liveDefinition?.OPTIONS && liveDefinition.OPTIONS.length > 0) {
+      return liveDefinition.OPTIONS;
+    }
+
    if (Array.isArray(data?.availableOptions) && data.availableOptions.length > 0) {
      return data.availableOptions;
    }

    const availableModels = Array.isArray(data?.availableModels) ? data.availableModels : [];
    return availableModels.map((model) => ({ value: model, label: model }));
-  }, [data]);
+  }, [data, liveDefinition]);
+  const defaultModel = liveDefinition?.DEFAULT || data?.defaultModel || currentModel;

  const filteredOptions = useMemo(() => {
    const normalized = query.trim().toLowerCase();
@@ -245,7 +289,7 @@ function ModelsContent({ data }: { data: ModelCommandData }) {
    }

    return availableOptions.filter((option) => {
-      const haystack = `${option.value} ${option.label || ''}`.toLowerCase();
+      const haystack = `${option.value} ${option.label || ''} ${option.description || ''}`.toLowerCase();
      return haystack.includes(normalized);
    });
  }, [availableOptions, query]);
@@ -264,25 +308,49 @@ function ModelsContent({ data }: { data: ModelCommandData }) {

  return (
    <div className="flex h-full min-h-0 flex-col gap-4">
-      <div className="grid gap-3 md:grid-cols-[1.15fr_0.85fr]">
-        <div className="relative overflow-hidden rounded-3xl border border-primary/25 bg-primary/10 p-5">
+      <div className="flex flex-col gap-2 rounded-2xl border border-border/70 bg-muted/20 px-3 py-2.5 lg:flex-row lg:items-center lg:justify-between">
+        <div className="min-w-0">
+          <p className="text-sm font-semibold text-foreground">Hard refresh provider catalogs</p>
+          <p className="mt-0.5 text-xs leading-5 text-muted-foreground">
+            Bypasses the 3-day backend cache and re-fetches models for every provider.
+          </p>
+          <p className="mt-1 text-[11px] text-muted-foreground">
+            Last updated for {providerLabel}: {formatUpdatedAt(currentCache?.updatedAt)}
+          </p>
+        </div>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={onHardRefreshProviderModels}
+          disabled={providerModelsRefreshing}
+          className="h-8 shrink-0 rounded-xl px-3"
+        >
+          <RefreshCw className={providerModelsRefreshing ? 'animate-spin' : ''} />
+          {providerModelsRefreshing ? 'Refreshing...' : 'Hard Refresh'}
+        </Button>
+      </div>
+
+      <div className="grid gap-3 md:grid-cols-[minmax(0,1.35fr)_minmax(0,0.48fr)_minmax(0,0.48fr)]">
+        <div className="relative overflow-hidden rounded-3xl border border-primary/25 bg-primary/10 p-4">
          <div className="pointer-events-none absolute -right-10 -top-12 h-36 w-36 rounded-full bg-primary/20 blur-3xl" />
          <div className="relative flex items-start justify-between gap-4">
            <div className="min-w-0">
              <p className="text-xs font-semibold uppercase tracking-[0.2em] text-primary/80">Active model</p>
-              <h3 className="mt-2 break-all font-mono text-lg font-semibold text-foreground">{currentModel}</h3>
+              <h3 className="mt-1.5 break-all font-mono text-base font-semibold text-foreground">{currentModel}</h3>
              {activeOption?.label && activeOption.label !== currentModel && (
-                <p className="mt-1 text-sm text-muted-foreground">{activeOption.label}</p>
+                <p className="mt-1 text-xs text-muted-foreground">{activeOption.label}</p>
+              )}
+              {activeOption?.description && (
+                <p className="mt-1.5 line-clamp-2 text-xs leading-5 text-muted-foreground">{activeOption.description}</p>
              )}
            </div>
            <Badge className="shrink-0 rounded-full bg-primary text-primary-foreground">Live</Badge>
          </div>
        </div>

-        <div className="grid grid-cols-2 gap-3">
-          <MetricCard label="Provider" value={providerLabel} icon={Server} tone="primary" />
-          <MetricCard label="Models" value={String(availableOptions.length)} icon={Layers3} />
-        </div>
+        <MetricCard label="Provider" value={providerLabel} icon={Server} tone="primary" compact />
+        <MetricCard label="Models" value={String(availableOptions.length)} icon={Layers3} compact />
      </div>

      <div className="flex min-h-0 flex-1 flex-col rounded-3xl border border-border/70 bg-muted/15 p-3 sm:p-4">
@@ -320,6 +388,9 @@ function ModelsContent({ data }: { data: ModelCommandData }) {
                      {option.label && option.label !== option.value && (
                        <span className="mt-1 block text-xs text-muted-foreground">{option.label}</span>
                      )}
+                      {option.description && (
+                        <span className="mt-1 block text-xs leading-5 text-muted-foreground">{option.description}</span>
+                      )}
                      {isCurrent && <span className="mt-2 block text-[11px] font-semibold uppercase tracking-[0.16em] text-primary">Current selection</span>}
                    </span>
                    <span className="rounded-lg border border-border/70 bg-muted/30 p-2 text-muted-foreground transition-colors group-hover:text-primary">
@@ -443,9 +514,17 @@ function StatusContent({ data }: { data: StatusCommandData }) {
  );
 }

-export default function CommandResultModal({ payload, onClose }: CommandResultModalProps) {
+export default function CommandResultModal({
+  payload,
+  onClose,
+  providerModelCatalog,
+  providerModelCacheCatalog,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
+}: CommandResultModalProps) {
  const isOpen = Boolean(payload);
  const kind = payload?.kind;
+  const isModelsModal = kind === 'models';

  const modalMeta = {
    help: {
@@ -482,23 +561,31 @@ export default function CommandResultModal({ payload, onClose }: CommandResultMo
      <DialogContent className="flex h-[min(92dvh,48rem)] w-[calc(100vw-1rem)] max-w-5xl flex-col overflow-hidden rounded-3xl border-border/80 bg-popover/95 p-0 shadow-2xl backdrop-blur-xl sm:w-[min(94vw,64rem)]">
        <DialogTitle>{activeMeta?.title || 'Command Result'}</DialogTitle>

-        <div className="relative shrink-0 overflow-hidden border-b border-border/70 bg-gradient-to-br from-primary/15 via-background to-muted/40 px-4 pb-4 pt-4 sm:px-6 sm:pb-5 sm:pt-5">
+        <div
+          className={`relative shrink-0 overflow-hidden border-b border-border/70 bg-gradient-to-br from-primary/15 via-background to-muted/40 ${
+            isModelsModal ? 'px-4 pb-3 pt-3 sm:px-5 sm:pb-4 sm:pt-4' : 'px-4 pb-4 pt-4 sm:px-6 sm:pb-5 sm:pt-5'
+          }`}
+        >
          <div className="pointer-events-none absolute -left-20 -top-24 h-56 w-56 rounded-full bg-primary/20 blur-3xl" />
          <div className="pointer-events-none absolute right-0 top-0 h-full w-1/2 bg-[radial-gradient(circle_at_top_right,hsl(var(--primary)/0.16),transparent_58%)]" />

          <div className="relative flex items-start justify-between gap-3">
            <div className="flex min-w-0 items-start gap-3 sm:items-center">
-              <div className="rounded-2xl border border-primary/30 bg-primary/10 p-3 text-primary shadow-sm">
-                <HeaderIcon className="h-5 w-5" />
+              <div
+                className={`rounded-2xl border border-primary/30 bg-primary/10 text-primary shadow-sm ${
+                  isModelsModal ? 'p-2.5' : 'p-3'
+                }`}
+              >
+                <HeaderIcon className={isModelsModal ? 'h-4 w-4' : 'h-5 w-5'} />
              </div>
              <div className="min-w-0">
                <p className="text-[11px] font-semibold uppercase tracking-[0.22em] text-primary/80">
                  {activeMeta?.eyebrow}
                </p>
-                <p className="mt-1 text-xl font-semibold tracking-tight text-foreground sm:text-2xl">
+                <p className={`mt-1 font-semibold tracking-tight text-foreground ${isModelsModal ? 'text-lg sm:text-xl' : 'text-xl sm:text-2xl'}`}>
                  {activeMeta?.title}
                </p>
-                <p className="mt-1 max-w-2xl text-sm leading-5 text-muted-foreground">
+                <p className={`mt-1 max-w-2xl text-muted-foreground ${isModelsModal ? 'text-xs leading-5 sm:text-sm' : 'text-sm leading-5'}`}>
                  {activeMeta?.subtitle}
                </p>
              </div>
@@ -519,7 +606,15 @@ export default function CommandResultModal({ payload, onClose }: CommandResultMo

        <div className="settings-content-enter min-h-0 flex-1 overflow-hidden px-4 py-4 sm:px-6 sm:py-5">
          {payload?.kind === 'help' && <HelpContent data={payload.data as HelpCommandData} />}
-          {payload?.kind === 'models' && <ModelsContent data={payload.data as ModelCommandData} />}
+          {payload?.kind === 'models' && (
+            <ModelsContent
+              data={payload.data as ModelCommandData}
+              providerModelCatalog={providerModelCatalog}
+              providerModelCacheCatalog={providerModelCacheCatalog}
+              providerModelsRefreshing={providerModelsRefreshing}
+              onHardRefreshProviderModels={onHardRefreshProviderModels}
+            />
+          )}
          {payload?.kind === 'cost' && <CostContent data={payload.data as CostCommandData} />}
          {payload?.kind === 'status' && <StatusContent data={payload.data as StatusCommandData} />}
        </div>
--- a/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx
+++ b/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx
@@ -1,12 +1,18 @@
 import React, { useCallback, useEffect, useMemo, useState } from "react";
-import { Check, ChevronDown } from "lucide-react";
+import { Check, ChevronDown, RefreshCw } from "lucide-react";
 import { Trans, useTranslation } from "react-i18next";

 import { useServerPlatform } from "../../../../hooks/useServerPlatform";
-import type { ProjectSession, LLMProvider, ProviderModelsDefinition } from "../../../../types/app";
+import type {
+  ProjectSession,
+  LLMProvider,
+  ProviderModelsCacheInfo,
+  ProviderModelsDefinition,
+} from "../../../../types/app";
 import SessionProviderLogo from "../../../llm-logo-provider/SessionProviderLogo";
 import { NextTaskBanner } from "../../../task-master";
 import {
+  Button,
  Dialog,
  DialogTrigger,
  DialogContent,
@@ -48,7 +54,10 @@ type ProviderSelectionEmptyStateProps = {
  opencodeModel: string;
  setOpenCodeModel: (model: string) => void;
  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
  providerModelsLoading: boolean;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
  tasksEnabled: boolean;
  isTaskMasterInstalled: boolean | null;
  onShowAllTasks?: (() => void) | null;
@@ -58,7 +67,7 @@ type ProviderSelectionEmptyStateProps = {
 type ProviderGroup = {
  id: LLMProvider;
  name: string;
-  models: { value: string; label: string }[];
+  models: { value: string; label: string; description?: string }[];
 };

 function getModelConfig(
@@ -92,6 +101,19 @@ function getProviderDisplayName(p: LLMProvider) {
  return "Gemini";
 }

+function formatUpdatedAt(value?: string) {
+  if (!value) {
+    return "Not cached yet";
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return "Not cached yet";
+  }
+
+  return parsed.toLocaleString();
+}
+
 export default function ProviderSelectionEmptyState({
  selectedSession,
  currentSessionId,
@@ -109,7 +131,10 @@ export default function ProviderSelectionEmptyState({
  opencodeModel,
  setOpenCodeModel,
  providerModelCatalog,
+  providerModelCacheCatalog,
  providerModelsLoading,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
  tasksEnabled,
  isTaskMasterInstalled,
  onShowAllTasks,
@@ -156,6 +181,8 @@ export default function ProviderSelectionEmptyState({
    return found?.label || currentModel;
  }, [provider, currentModel, providerModelCatalog]);

+  const currentProviderCache = providerModelCacheCatalog[provider];
+
  const setModelForProvider = useCallback(
    (providerId: LLMProvider, modelValue: string) => {
      if (providerId === "claude") {
@@ -237,6 +264,32 @@ export default function ProviderSelectionEmptyState({

            <DialogContent className="max-w-md overflow-hidden p-0">
              <DialogTitle>Model Selector</DialogTitle>
+              <div className="border-b border-border/60 bg-muted/20 px-4 py-3">
+                <div className="flex items-start justify-between gap-3">
+                  <div className="min-w-0">
+                    <p className="text-sm font-semibold text-foreground">
+                      Hard refresh model catalogs
+                    </p>
+                    <p className="mt-1 text-xs leading-5 text-muted-foreground">
+                      Bypasses the 3-day backend cache and re-fetches models for every provider.
+                    </p>
+                    <p className="mt-1 text-[11px] text-muted-foreground">
+                      Last updated for {getProviderDisplayName(provider)}: {formatUpdatedAt(currentProviderCache?.updatedAt)}
+                    </p>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={onHardRefreshProviderModels}
+                    disabled={providerModelsRefreshing}
+                    className="shrink-0 rounded-xl"
+                  >
+                    <RefreshCw className={providerModelsRefreshing ? "animate-spin" : ""} />
+                    {providerModelsRefreshing ? "Refreshing..." : "Hard Refresh"}
+                  </Button>
+                </div>
+              </div>
              <Command>
                <CommandInput
                  placeholder={t("providerSelection.searchModels", {
@@ -274,11 +327,18 @@ export default function ProviderSelectionEmptyState({
                        return (
                          <CommandItem
                            key={`${group.id}-${model.value}`}
-                            value={`${group.name} ${model.label}`}
+                            value={`${group.name} ${model.label} ${model.description || ''}`}
                            onSelect={() => handleModelSelect(group.id, model.value)}
                            className="ml-4 border-l border-border/40 pl-4"
                          >
-                            <span className="flex-1 truncate">{model.label}</span>
+                            <div className="min-w-0 flex-1">
+                              <div className="truncate">{model.label}</div>
+                              {model.description && (
+                                <div className="truncate text-xs text-muted-foreground">
+                                  {model.description}
+                                </div>
+                              )}
+                            </div>
                            {isSelected && (
                              <Check className="ml-auto h-4 w-4 shrink-0 text-primary" />
                            )}
--- a/src/types/app.ts
+++ b/src/types/app.ts
@@ -3,6 +3,7 @@ export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode';
 export type ProviderModelOption = {
  value: string;
  label: string;
+  description?: string;
 };

 export type ProviderModelsDefinition = {
@@ -10,6 +11,12 @@ export type ProviderModelsDefinition = {
  DEFAULT: string;
 };

+export type ProviderModelsCacheInfo = {
+  updatedAt: string;
+  expiresAt: string;
+  source: 'memory' | 'disk' | 'fresh';
+};
+
 export type AppTab = 'chat' | 'files' | 'shell' | 'git' | 'tasks' | 'preview' | `plugin:${string}`;

 export interface ProjectSession {