🙌 OpenHands: AI-Driven Development
feat(frontend): warn when the LLM is not configured after skipping onboarding (#1011)
Hiep Le6c376bdd5757
diff --git a/__tests__/components/home/llm-not-configured-banner.test.tsx b/__tests__/components/home/llm-not-configured-banner.test.tsxnew file mode 100644index 0000000000..7c9aaf710c--- /dev/null+++ b/__tests__/components/home/llm-not-configured-banner.test.tsx@@ -0,0 +1,188 @@+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { render, screen } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { beforeEach, describe, expect, it, vi } from "vitest";++import { LlmNotConfiguredBanner } from "#/components/features/home/llm-not-configured-banner";+import { NavigationProvider } from "#/context/navigation-context";+import { useSettings } from "#/hooks/query/use-settings";+import { useConfig } from "#/hooks/query/use-config";+import SettingsService from "#/api/settings-service/settings-service.api";+import OptionService from "#/api/option-service/option-service.api";+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";+import { Settings } from "#/types/settings";+import { WebClientConfig } from "#/api/option-service/option.types";++function buildSettings(overrides: Partial<Settings> = {}): Settings {+ return {+ ...MOCK_DEFAULT_USER_SETTINGS,+ ...overrides,+ agent_settings:+ overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,+ };+}++function buildConfig(hideLlmSettings = false): WebClientConfig {+ return {+ posthog_client_key: null,+ feature_flags: {+ hide_llm_settings: hideLlmSettings,+ hide_users_page: true,+ },+ providers_configured: [],+ maintenance_start_time: null,+ recaptcha_site_key: null,+ faulty_models: [],+ error_message: null,+ updated_at: "2026-01-01T00:00:00.000Z",+ };+}++// Renders the banner next to a probe that flips on once both underlying+// queries have resolved. The "hidden" assertions wait on this marker so they+// observe the settled state rather than the (always-empty) loading frame.+function ProbedBanner() {+ const settings = useSettings();+ const config = useConfig();+ return (+ <>+ <LlmNotConfiguredBanner />+ {settings.isFetched && config.isFetched ? (+ <div data-testid="queries-settled" />+ ) : null}+ </>+ );+}++function renderBanner() {+ const navigate = vi.fn();+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ render(+ <QueryClientProvider client={queryClient}>+ <NavigationProvider+ value={{+ currentPath: "/",+ conversationId: null,+ isNavigating: false,+ navigate,+ }}+ >+ <ProbedBanner />+ </NavigationProvider>+ </QueryClientProvider>,+ );+ return { navigate };+}++describe("LlmNotConfiguredBanner", () => {+ beforeEach(() => {+ vi.restoreAllMocks();+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig());+ });++ it("warns the user when no LLM API key is set (the skip-onboarding case)", async () => {+ // Arrange: an OpenHands agent with no key — what "Skip for now" leaves.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({ llm_api_key_set: false }),+ );++ // Act+ renderBanner();++ // Assert+ expect(+ await screen.findByTestId("home-llm-not-configured-banner"),+ ).toBeInTheDocument();+ });++ it("stays hidden once an LLM API key is configured", async () => {+ // Arrange+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({ llm_api_key_set: true }),+ );++ // Act+ renderBanner();+ await screen.findByTestId("queries-settled");++ // Assert+ expect(+ screen.queryByTestId("home-llm-not-configured-banner"),+ ).not.toBeInTheDocument();+ });++ it("stays hidden for ACP agents, which own their LLM and need no key", async () => {+ // Arrange: ACP agent, no key — must not be nagged.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({+ llm_api_key_set: false,+ agent_settings: {+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,+ agent_kind: "acp",+ },+ }),+ );++ // Act+ renderBanner();+ await screen.findByTestId("queries-settled");++ // Assert+ expect(+ screen.queryByTestId("home-llm-not-configured-banner"),+ ).not.toBeInTheDocument();+ });++ it("stays hidden when the LLM settings page is hidden by feature flag", async () => {+ // Arrange: no key, but the settings page is hidden — routing the user to+ // /settings/llm would dead-end, so the hook treats the LLM as configured.+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig(true));+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({ llm_api_key_set: false }),+ );++ // Act+ renderBanner();+ await screen.findByTestId("queries-settled");++ // Assert+ expect(+ screen.queryByTestId("home-llm-not-configured-banner"),+ ).not.toBeInTheDocument();+ });++ it("warns when settings 404 — the genuine new-user state — despite the error flag", async () => {+ // Arrange: a 404 means no settings exist yet. useSettings maps it to+ // DEFAULT_SETTINGS (no key) while keeping isError set, so the banner must+ // still appear — this is the real "Skip for now" state. Guards against+ // conflating this with a transient fetch error that should suppress it.+ vi.spyOn(SettingsService, "getSettings").mockRejectedValue({ status: 404 });++ // Act+ renderBanner();++ // Assert+ expect(+ await screen.findByTestId("home-llm-not-configured-banner"),+ ).toBeInTheDocument();+ });++ it("routes the user to LLM settings when the action is clicked", async () => {+ // Arrange+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({ llm_api_key_set: false }),+ );+ const user = userEvent.setup();+ const { navigate } = renderBanner();++ // Act+ await user.click(+ await screen.findByTestId("home-llm-not-configured-action"),+ );++ // Assert+ expect(navigate).toHaveBeenCalledWith("/settings/llm");+ });+});diff --git a/src/components/features/home/llm-not-configured-banner.tsx b/src/components/features/home/llm-not-configured-banner.tsxnew file mode 100644index 0000000000..75634ab3ab--- /dev/null+++ b/src/components/features/home/llm-not-configured-banner.tsx@@ -0,0 +1,53 @@+import { useTranslation } from "react-i18next";+import { FaTriangleExclamation } from "react-icons/fa6";+import { I18nKey } from "#/i18n/declaration";+import { useNavigation } from "#/context/navigation-context";+import { useLlmConfigured } from "#/hooks/use-llm-configured";+import { BrandButton } from "#/components/features/settings/brand-button";+import { Typography } from "#/ui/typography";++/**+ * Warns the user on the home screen when the active agent has no usable LLM —+ * most notably after they skip onboarding, which persists no settings. Offers+ * a single action that routes to LLM settings so the failure is communicated+ * up front instead of surfacing only when a conversation attempt errors out.+ *+ * Renders nothing while settings load (avoids a flash) or once the LLM is+ * configured; the settings query refetches after a key is saved, so the banner+ * unmounts on its own.+ */+export function LlmNotConfiguredBanner() {+ const { t } = useTranslation("openhands");+ const { navigate } = useNavigation();+ const { isConfigured, isLoading } = useLlmConfigured();++ if (isLoading || isConfigured) {+ return null;+ }++ return (+ <div+ data-testid="home-llm-not-configured-banner"+ role="alert"+ className="bg-base border border-primary text-white p-4 rounded flex flex-row items-center justify-between gap-3 mt-3"+ >+ <div className="flex items-center">+ <div className="flex-shrink-0">+ <FaTriangleExclamation className="text-primary align-middle" />+ </div>+ <Typography.Text className="ml-3 text-sm font-medium">+ {t(I18nKey.HOME$LLM_NOT_CONFIGURED_MESSAGE)}+ </Typography.Text>+ </div>++ <BrandButton+ testId="home-llm-not-configured-action"+ type="button"+ variant="primary"+ onClick={() => navigate("/settings/llm")}+ >+ {t(I18nKey.HOME$LLM_NOT_CONFIGURED_ACTION)}+ </BrandButton>+ </div>+ );+}diff --git a/src/hooks/use-llm-configured.ts b/src/hooks/use-llm-configured.tsnew file mode 100644index 0000000000..943cd8a68b--- /dev/null+++ b/src/hooks/use-llm-configured.ts@@ -0,0 +1,62 @@+import { useSettings } from "#/hooks/query/use-settings";+import { useConfig } from "#/hooks/query/use-config";+import { isSettingsPageHidden } from "#/utils/settings-utils";++interface LlmConfiguredResult {+ /**+ * True when the active backend's agent has a usable LLM:+ * - ACP agents own their LLM via a subprocess, so they never need a key.+ * - OpenHands agents are ready only once an LLM API key has been saved.+ * - When the LLM settings page is hidden by a feature flag there is no+ * place to finish setup, so we treat the LLM as configured to avoid+ * surfacing an actionless warning.+ */+ isConfigured: boolean;+ /**+ * True while the configured/unconfigured state is indeterminate — either+ * settings/config are still resolving, or a fetch failed and left us with no+ * data to decide from. Consumers should render nothing in this state so a+ * warning doesn't flash before data loads or on a transient network error.+ */+ isLoading: boolean;+}++/**+ * Reports whether the active backend's agent has an LLM ready to run+ * conversations. Surfaces the gap left by the onboarding "Skip for now" path,+ * which persists no settings — leaving an OpenHands agent without an API key.+ */+export function useLlmConfigured(): LlmConfiguredResult {+ const {+ data: settings,+ isLoading: settingsLoading,+ isError: settingsError,+ } = useSettings();+ const {+ data: config,+ isLoading: configLoading,+ isError: configError,+ } = useConfig();++ const isAcpAgent = settings?.agent_settings?.agent_kind === "acp";+ const hasApiKey = settings?.llm_api_key_set === true;+ const llmSettingsHidden = isSettingsPageHidden(+ "/settings/llm",+ config?.feature_flags,+ );++ // Treat a fetch failure as indeterminate (same as loading) only when it+ // leaves us with no data to decide from — otherwise a transient network+ // error would surface the banner with the same urgency as a genuinely+ // missing API key. A settings 404 is deliberately not covered here:+ // `useSettings` maps it to DEFAULT_SETTINGS (no key, OpenHands agent) while+ // keeping `isError` set, and that is exactly the new-user / "Skip for now"+ // state the banner exists to catch — so we keep deciding from that data.+ const settingsIndeterminate = settingsLoading || (settingsError && !settings);+ const configIndeterminate = configLoading || (configError && !config);++ return {+ isConfigured: isAcpAgent || hasApiKey || llmSettingsHidden,+ isLoading: settingsIndeterminate || configIndeterminate,+ };+}diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex 81f7e37ee5..a914dee718 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -611,6 +611,40 @@"uk": "Почати з нуля","ca": "Comença des de zero"},+ "HOME$LLM_NOT_CONFIGURED_MESSAGE": {+ "en": "Your LLM isn't set up yet, so conversations won't run. Finish setup to get started.",+ "ja": "LLMがまだ設定されていないため、会話を実行できません。セットアップを完了して始めましょう。",+ "zh-CN": "您的 LLM 尚未设置,因此无法进行对话。请完成设置以开始使用。",+ "zh-TW": "您的 LLM 尚未設定,因此無法進行對話。請完成設定以開始使用。",+ "ko-KR": "LLM이 아직 설정되지 않아 대화를 실행할 수 없습니다. 설정을 완료하여 시작하세요.",+ "no": "LLM-en din er ikke satt opp ennå, så samtaler vil ikke kjøre. Fullfør oppsettet for å komme i gang.",+ "it": "Il tuo LLM non è ancora configurato, quindi le conversazioni non funzioneranno. Completa la configurazione per iniziare.",+ "pt": "Seu LLM ainda não está configurado, então as conversas não funcionarão. Conclua a configuração para começar.",+ "es": "Tu LLM aún no está configurado, por lo que las conversaciones no funcionarán. Completa la configuración para empezar.",+ "ar": "لم يتم إعداد نموذج اللغة الخاص بك بعد، لذا لن تعمل المحادثات. أكمل الإعداد للبدء.",+ "fr": "Votre LLM n'est pas encore configuré, les conversations ne fonctionneront donc pas. Terminez la configuration pour commencer.",+ "tr": "LLM'niz henüz ayarlanmadı, bu yüzden konuşmalar çalışmaz. Başlamak için kurulumu tamamlayın.",+ "de": "Dein LLM ist noch nicht eingerichtet, daher können keine Konversationen ausgeführt werden. Schließe die Einrichtung ab, um loszulegen.",+ "uk": "Ваш LLM ще не налаштований, тому розмови не працюватимуть. Завершіть налаштування, щоб почати.",+ "ca": "El teu LLM encara no està configurat, així que les converses no funcionaran. Completa la configuració per començar."+ },+ "HOME$LLM_NOT_CONFIGURED_ACTION": {+ "en": "Set up LLM",+ "ja": "LLMを設定",+ "zh-CN": "设置 LLM",+ "zh-TW": "設定 LLM",+ "ko-KR": "LLM 설정",+ "no": "Sett opp LLM",+ "it": "Configura LLM",+ "pt": "Configurar LLM",+ "es": "Configurar LLM",+ "ar": "إعداد نموذج اللغة",+ "fr": "Configurer le LLM",+ "tr": "LLM'yi ayarla",+ "de": "LLM einrichten",+ "uk": "Налаштувати LLM",+ "ca": "Configura el LLM"+ },"HOME$READ_THIS": {"en": "Read this","ja": "詳細はこちら",diff --git a/src/routes/home.tsx b/src/routes/home.tsxindex 46a5db6478..84578dde6b 100644--- a/src/routes/home.tsx+++ b/src/routes/home.tsx@@ -1,5 +1,6 @@import { PrefetchPageLinks } from "react-router";import { HomeChatLauncher } from "#/components/features/home/home-chat-launcher";+import { LlmNotConfiguredBanner } from "#/components/features/home/llm-not-configured-banner";import { OnboardingHost } from "#/components/features/onboarding";<PrefetchPageLinks page="/conversations/:conversationId" />;@@ -10,6 +11,8 @@ function HomeScreen() {data-testid="home-screen"className="custom-scrollbar-always flex h-full flex-col overflow-y-auto rounded-xl bg-transparent px-4 md:px-0 lg:px-[42px]">+ <LlmNotConfiguredBanner />+<div className="flex flex-1 min-h-0 flex-col items-center justify-center"><HomeChatLauncher /></div>