🙌 OpenHands: AI-Driven Development
feat: use DB-driven free/default model flags in Canvas (#16685)
Juan Pedro Michelini Jorgeb6e27d596666
diff --git a/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx b/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsxindex 6544dc9070..689bbd3cc2 100644--- a/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx+++ b/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx@@ -8,7 +8,7 @@ vi.mock("#/hooks/use-chat-input-llm-profile-state", () => ({useChatInputLlmProfileState: () => useChatInputLlmProfileStateMock(),}));-// eslint-disable-next-line import/first+import { useFreeModelsStore } from "#/stores/free-models-store";import { ChatInputLlmProfilePicker } from "#/components/features/chat/components/chat-input-llm-profile-picker";const PROFILES = [@@ -46,6 +46,11 @@ describe("ChatInputLlmProfilePicker", () => {selectProfile.mockReset();useChatInputLlmProfileStateMock.mockReset();useChatInputLlmProfileStateMock.mockReturnValue(state());+ useFreeModelsStore.setState({+ freeModels: new Set(),+ defaultModel: null,+ defaultModelReady: false,+ });});it("renders nothing while loading or when there are no profiles", () => {@@ -95,7 +100,11 @@ describe("ChatInputLlmProfilePicker", () => {).not.toBeInTheDocument();});- it("labels a free OpenHands route in the profile menu", () => {+ it("labels a backend-flagged free OpenHands route in the profile menu", () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/deepseek-v4-flash"]),+ defaultModel: null,+ });useChatInputLlmProfileStateMock.mockReturnValue(state({profiles: [@@ -119,7 +128,11 @@ describe("ChatInputLlmProfilePicker", () => {).toBeInTheDocument();});- it("labels a free OpenHands route in the read-only profile menu", () => {+ it("labels a backend-flagged free OpenHands route in the read-only profile menu", () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/deepseek-v4-flash"]),+ defaultModel: null,+ });useChatInputLlmProfileStateMock.mockReturnValue(state({canSwitchProfile: false,diff --git a/__tests__/components/features/chat/model-messages.test.tsx b/__tests__/components/features/chat/model-messages.test.tsxindex 699e346072..ac83ec5f21 100644--- a/__tests__/components/features/chat/model-messages.test.tsx+++ b/__tests__/components/features/chat/model-messages.test.tsx@@ -5,6 +5,7 @@ import userEvent from "@testing-library/user-event";import { renderWithProviders } from "test-utils";import { ModelMessages } from "#/components/features/chat/model-messages";import { useModelStore } from "#/stores/model-store";+import { useFreeModelsStore } from "#/stores/free-models-store";import type { ProfileInfo } from "#/api/profiles-service/profiles-service.api";const CONVERSATION_ID = "conv-1";@@ -36,6 +37,10 @@ describe("ModelMessages", () => {i18n.addResourceBundle("en", "translation", resources, true, true);i18n.addResourceBundle("en", "openhands", resources, true, true);useModelStore.setState({ entriesByConversation: {} });+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });});it("renders only entries anchored to the requested event", async () => {@@ -105,12 +110,16 @@ describe("ModelMessages", () => {);});- it("labels a free OpenHands route in expanded profile diagnostics", async () => {+ it("labels a DB-flagged free OpenHands route in expanded profile diagnostics", async () => {const user = userEvent.setup();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/glm-5.2"]),+ defaultModel: "openhands/glm-5.2",+ });useModelStore.getState().show(CONVERSATION_ID, "event-1", [{name: "free",- model: "openhands/deepseek-v4-flash",+ model: "openhands/glm-5.2",base_url: null,api_key_set: true,},@@ -129,7 +138,7 @@ describe("ModelMessages", () => {);expect(- screen.getByText(/model:\s+OpenHands DeepSeek V4 Flash \(free\)/),+ screen.getByText(/model:\s+openhands\/glm-5\.2 \(free\)/),).toBeInTheDocument();});});diff --git a/__tests__/components/features/conversation-panel/conversation-card.test.tsx b/__tests__/components/features/conversation-panel/conversation-card.test.tsxindex 00a084aeb7..03e646bf91 100644--- a/__tests__/components/features/conversation-panel/conversation-card.test.tsx+++ b/__tests__/components/features/conversation-panel/conversation-card.test.tsx@@ -23,6 +23,7 @@ import {} from "#/api/backend-registry/active-store";import type { Backend } from "#/api/backend-registry/types";import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import { useFreeModelsStore } from "#/stores/free-models-store";// We'll use the actual i18next implementation but override the translation function@@ -1122,7 +1123,11 @@ describe("ConversationCard", () => {).not.toBeInTheDocument();});- it("labels a free OpenHands route on native conversation chips", () => {+ it("labels a DB-flagged free OpenHands route on native conversation chips", () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/glm-5.2"]),+ defaultModel: "openhands/glm-5.2",+ });renderWithProviders(<ConversationCardtitle="Conversation 1"@@ -1135,8 +1140,13 @@ describe("ConversationCard", () => {);const chip = screen.getByTestId("conversation-card-agent-chip");- expect(chip).toHaveTextContent("glm-5.2");+ expect(chip).toHaveTextContent("glm-5.2 (free)");expect(chip).toHaveAttribute("title", "openhands/glm-5.2");++ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });});it("hides the chip for OpenHands conversations with no model", () => {diff --git a/__tests__/components/modals/settings/model-selector-openhands.test.tsx b/__tests__/components/modals/settings/model-selector-openhands.test.tsxindex 523f6d05c7..1c7e7927ea 100644--- a/__tests__/components/modals/settings/model-selector-openhands.test.tsx+++ b/__tests__/components/modals/settings/model-selector-openhands.test.tsx@@ -1,33 +1,76 @@-import { describe, expect, it, beforeEach } from "vitest";+import { describe, expect, it, beforeEach, vi } from "vitest";import React from "react";import { render, screen, waitFor } from "@testing-library/react";import userEvent from "@testing-library/user-event";import { http, HttpResponse } from "msw";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { ModelSelector } from "#/components/shared/modals/settings/model-selector";+import type { LLMModel } from "#/api/config-service/config-service.types";import { server } from "#/mocks/node";-describe("ModelSelector — OpenHands provider display", () => {- let providersCount = 0;- let verifiedCount = 0;- let modelsCount = 0;+vi.mock("react-i18next", () => ({+ useTranslation: () => ({+ t: (key: string, values?: { ids?: string }) =>+ key === "SETTINGS$OPENHANDS_FREE_MODELS_NOTE"+ ? `Free OpenHands models: ${values?.ids}. Other provider endpoints with similar model names may require separate billing.`+ : key,+ }),+}));++// The "Free" badge is DB-driven: the backend model list carries a `free` flag+// per item (the same channel as `verified`). These tests drive the selector+// through the model list rather than the (free-less) local /api/llm channel.+const OPENHANDS_MODELS: LLMModel[] = [+ {+ provider: "openhands",+ name: "claude-opus-4-7",+ verified: true,+ free: false,+ default: false,+ },+ {+ provider: "openhands",+ name: "glm-5.2",+ verified: true,+ free: true,+ default: true,+ },+ {+ provider: "openhands",+ name: "deepseek-v4-flash",+ verified: true,+ free: true,+ default: false,+ },+ {+ provider: "openhands",+ name: "minimax-m2.7",+ verified: true,+ free: true,+ default: false,+ },+];+vi.mock("#/hooks/query/use-provider-models", () => ({+ useProviderModels: (provider: string | null) => ({+ data: provider === "openhands" ? OPENHANDS_MODELS : [],+ isLoading: false,+ error: null,+ }),+}));++describe("ModelSelector — OpenHands provider display", () => {beforeEach(() => {- providersCount = 0;- verifiedCount = 0;- modelsCount = 0;// Use "*" prefix to match both relative paths and absolute URLs (e.g.,// http://127.0.0.1:8000/api/...) when VITE_BACKEND_BASE_URL is configured.server.use(- http.get("*/api/llm/providers", () => {- providersCount += 1;- return HttpResponse.json({+ http.get("*/api/llm/providers", () =>+ HttpResponse.json({providers: ["openhands", "anthropic", "openai"],- });- }),- http.get("*/api/llm/models/verified", () => {- verifiedCount += 1;- return HttpResponse.json({+ }),+ ),+ http.get("*/api/llm/models/verified", () =>+ HttpResponse.json({models: {openhands: ["claude-opus-4-7",@@ -37,12 +80,9 @@ describe("ModelSelector — OpenHands provider display", () => {],anthropic: ["claude-opus-4-5-20251101"],},- });- }),- http.get("*/api/llm/models", () => {- modelsCount += 1;- return HttpResponse.json({ models: [] });- }),+ }),+ ),+ http.get("*/api/llm/models", () => HttpResponse.json({ models: [] })),);});@@ -61,18 +101,15 @@ describe("ModelSelector — OpenHands provider display", () => {await waitFor(() => {expect(screen.getByLabelText("LLM$PROVIDER")).toHaveValue("OpenHands");});-- expect(providersCount).toBe(1);- expect(verifiedCount).toBe(1);- expect(modelsCount).toBe(1);});it("makes clear which OpenHands models are free", async () => {const user = userEvent.setup();- renderWithQuery(<ModelSelector currentModel="openhands/deepseek-v4-flash" />);+ renderWithQuery(+ <ModelSelector currentModel="openhands/deepseek-v4-flash" />,+ );- await waitFor(() => {- });+ await waitFor(() => {});expect(screen.getByTestId("openhands-free-models-note")).toHaveTextContent("openhands/deepseek-v4-flash",);@@ -82,7 +119,9 @@ describe("ModelSelector — OpenHands provider display", () => {await user.click(screen.getByLabelText("LLM$MODEL"));- expect(screen.getAllByText("Free")).toHaveLength(2);+ // Three DB-flagged free models render a "Free" badge in the dropdown; the+ // selected-model badge adds a fourth occurrence.+ expect(screen.getAllByText("Free")).toHaveLength(4);expect(screen.getByLabelText("LLM$MODEL")).toHaveValue("deepseek-v4-flash");await user.click(screen.getByRole("option", { name: /deepseek-v4-flash/ }));diff --git a/__tests__/components/modals/settings/model-selector.test.tsx b/__tests__/components/modals/settings/model-selector.test.tsxindex fcc7767501..c1115de22c 100644--- a/__tests__/components/modals/settings/model-selector.test.tsx+++ b/__tests__/components/modals/settings/model-selector.test.tsx@@ -14,18 +14,26 @@ const mockProviders: LLMProvider[] = [{ name: "vertex_ai", verified: false },];+const model = (partial: Partial<LLMModel> & Pick<LLMModel, "name">): LLMModel => ({+ provider: null,+ verified: false,+ free: false,+ default: false,+ ...partial,+});+const mockModelsByProvider: Record<string, LLMModel[]> = {openai: [- { provider: "openai", name: "gpt-4o", verified: true },- { provider: "openai", name: "gpt-4o-mini", verified: true },+ model({ provider: "openai", name: "gpt-4o", verified: true }),+ model({ provider: "openai", name: "gpt-4o-mini", verified: true }),],azure: [- { provider: "azure", name: "ada", verified: false },- { provider: "azure", name: "gpt-35-turbo", verified: false },+ model({ provider: "azure", name: "ada" }),+ model({ provider: "azure", name: "gpt-35-turbo" }),],vertex_ai: [- { provider: "vertex_ai", name: "chat-bison", verified: false },- { provider: "vertex_ai", name: "chat-bison-32k", verified: false },+ model({ provider: "vertex_ai", name: "chat-bison" }),+ model({ provider: "vertex_ai", name: "chat-bison-32k" }),],};diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsxindex a08bb10559..a0fcdd513c 100644--- a/__tests__/components/onboarding/onboarding-modal.test.tsx+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx@@ -19,6 +19,7 @@ import { NavigationProvider } from "#/context/navigation-context";import SettingsService from "#/api/settings-service/settings-service.api";import { SecretsService } from "#/api/secrets-service";import { DEFAULT_SETTINGS } from "#/services/settings";+import { useFreeModelsStore } from "#/stores/free-models-store";import * as telemetry from "#/services/telemetry";const llmSettingsScreenMock = vi.hoisted(() => vi.fn());@@ -188,10 +189,7 @@ function seedCloudBackend() {return backend;}-function renderModal(- onClose = vi.fn(),- options?: { initialStep?: number },-) {+function renderModal(onClose = vi.fn(), options?: { initialStep?: number }) {const queryClient = new QueryClient({defaultOptions: { queries: { retry: false } },});@@ -222,6 +220,10 @@ beforeEach(() => {vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");vi.stubEnv("VITE_SESSION_API_KEY", "session-key");__resetActiveStoreForTests();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });// Clear accumulated spy/mock call history so per-test assertions (the// ACP secret-write checks and the LLM-defaults mock) don't see calls// leaked from a prior test. Covers `llmSettingsScreenMock` too.@@ -716,6 +718,24 @@ describe("OnboardingModal", () => {);});+ it("pre-fills the LLM step with the DB-selected OpenHands default", () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/gpt-5.2"]),+ defaultModel: "openhands/gpt-5.2",+ });++ renderModal();++ expect(llmSettingsScreenMock).toHaveBeenCalledTimes(1);+ expect(llmSettingsScreenMock).toHaveBeenCalledWith(+ expect.objectContaining({+ initialValueOverrides: {+ "llm.model": "openhands/gpt-5.2",+ },+ }),+ );+ });+it("does not show backend configuration when the configured backend is healthy", async () => {renderModal();diff --git a/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx b/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsxindex add36ddf8f..580107d6be 100644--- a/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx+++ b/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx@@ -13,6 +13,7 @@ import * as useActivateLlmProfileHook from "#/hooks/mutation/use-activate-llm-primport * as useSaveLlmProfileHook from "#/hooks/mutation/use-save-llm-profile";import ProfilesService from "#/api/profiles-service/profiles-service.api";import * as activeBackendContext from "#/contexts/active-backend-context";+import { useFreeModelsStore } from "#/stores/free-models-store";import type { Backend } from "#/api/backend-registry/types";const mockCloudBackend: Backend = {@@ -212,6 +213,10 @@ describe("LlmSettingsLocalView", () => {beforeEach(() => {vi.clearAllMocks();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(createMockLlmProfilesReturn(),@@ -364,6 +369,23 @@ describe("LlmSettingsLocalView", () => {);});+ it("prefills the DB-selected OpenHands default when creating a new profile", async () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/gpt-5.2"]),+ defaultModel: "openhands/gpt-5.2",+ });++ const user = userEvent.setup();+ renderWithProviders(<LlmSettingsLocalView />);++ await user.click(screen.getByTestId("add-llm-profile"));++ expect(screen.getByTestId("profile-name-input")).toHaveValue("gpt-5.2");+ expect(screen.getByTestId("mock-basic-model-input")).toHaveValue(+ "openhands/gpt-5.2",+ );+ });+it("uses unique key for create mode to ensure form remounts", async () => {const user = userEvent.setup();renderWithProviders(<LlmSettingsLocalView />);@@ -406,6 +428,41 @@ describe("LlmSettingsLocalView", () => {// The key "new-profile" should be used, ensuring a fresh form mount// that doesn't inherit any existing profile data});++ it("shows a skeleton until the DB default query settles, then mounts the form with the resolved default", async () => {+ // Start with the flags unset (hydrator has not resolved yet), so the+ // create form must wait instead of mounting with the static fallback.+ useFreeModelsStore.getState().resetFlags();++ const user = userEvent.setup();+ renderWithProviders(<LlmSettingsLocalView />);++ await user.click(screen.getByTestId("add-llm-profile"));++ // While the DB default is unresolved, the form is replaced by a skeleton+ // (no model input / save control to accept yet).+ expect(screen.getByTestId("app-settings-skeleton")).toBeInTheDocument();+ expect(+ screen.queryByTestId("mock-basic-model-input"),+ ).not.toBeInTheDocument();++ // The DB default resolves to a concrete model.+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/gpt-5.2"]),+ defaultModel: "openhands/gpt-5.2",+ });++ // The keyed form now mounts with the resolved default, not the static+ // fallback.+ await waitFor(() => {+ expect(screen.getByTestId("mock-basic-model-input")).toHaveValue(+ "openhands/gpt-5.2",+ );+ });+ expect(+ screen.queryByTestId("app-settings-skeleton"),+ ).not.toBeInTheDocument();+ });});describe("edit mode form initialization", () => {@@ -980,6 +1037,13 @@ describe("LlmSettingsLocalView - OpenHands provider on cloud", () => {beforeEach(() => {vi.clearAllMocks();+ // Mark the DB default query as settled so the create-mode form mounts+ // (the gate renders a skeleton until `defaultModelReady` is true).+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });+vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(createMockLlmProfilesReturn({data: { profiles: [], active_profile: null },diff --git a/__tests__/components/settings/llm-profiles/profile-row.test.tsx b/__tests__/components/settings/llm-profiles/profile-row.test.tsxindex 6be24c66d6..cf43cdab27 100644--- a/__tests__/components/settings/llm-profiles/profile-row.test.tsx+++ b/__tests__/components/settings/llm-profiles/profile-row.test.tsx@@ -1,8 +1,9 @@import { render, screen } from "@testing-library/react";-import { describe, expect, it, vi } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import userEvent from "@testing-library/user-event";import { ProfileRow } from "#/components/features/settings/llm-profiles/profile-row";import { ProfileInfo } from "#/api/profiles-service/profiles-service.api";+import { useFreeModelsStore } from "#/stores/free-models-store";vi.mock("react-i18next", () => ({useTranslation: () => ({@@ -40,6 +41,13 @@ const defaultProps = {};describe("ProfileRow", () => {+ afterEach(() => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });+ });+it("displays the profile name", () => {render(<ProfileRow {...defaultProps} />);@@ -52,17 +60,22 @@ describe("ProfileRow", () => {expect(screen.getByText("openai/gpt-4")).toBeInTheDocument();});- it("labels a free OpenHands route without changing the raw title", () => {+ it("labels a DB-flagged free OpenHands route without changing the raw title", () => {+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/glm-5.2"]),+ defaultModel: "openhands/glm-5.2",+ });render(<ProfileRow{...defaultProps}- profile={{ ...mockProfile, model: "openhands/deepseek-v4-flash" }}+ profile={{ ...mockProfile, model: "openhands/glm-5.2" }}/>,);- expect(- screen.getByText("OpenHands DeepSeek V4 Flash (free)"),- ).toHaveAttribute("title", "openhands/deepseek-v4-flash");+ expect(screen.getByText("openhands/glm-5.2 (free)")).toHaveAttribute(+ "title",+ "openhands/glm-5.2",+ );});it("does not display model when null", () => {diff --git a/__tests__/hooks/chat/use-slash-command.test.ts b/__tests__/hooks/chat/use-slash-command.test.tsindex 116fafec48..1062ea08b0 100644--- a/__tests__/hooks/chat/use-slash-command.test.ts+++ b/__tests__/hooks/chat/use-slash-command.test.ts@@ -9,6 +9,7 @@ import {setRegisteredBackends,} from "#/api/backend-registry/active-store";import type { Backend } from "#/api/backend-registry/types";+import { useFreeModelsStore } from "#/stores/free-models-store";const mockSkills = vi.hoisted(() => ({data: undefined as unknown[] | undefined,@@ -94,6 +95,10 @@ describe("useSlashCommand", () => {mockLlmProfiles.data = undefined;mockLlmProfiles.isLoading = false;mockConversation.data = undefined;+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });});afterEach(() => {@@ -140,6 +145,10 @@ describe("useSlashCommand", () => {// The active backend store is reset before each test, which restores the default local backend.mockSkills.data = [];+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/glm-5.2"]),+ defaultModel: "openhands/glm-5.2",+ });mockLlmProfiles.data = {profiles: [{@@ -156,7 +165,7 @@ describe("useSlashCommand", () => {},{name: "free",- model: "openhands/deepseek-v4-flash",+ model: "openhands/glm-5.2",base_url: null,api_key_set: true,},@@ -180,7 +189,7 @@ describe("useSlashCommand", () => {expect(result.current.filteredItems.find((i) => i.command === "/model free")?.skill.content,- ).toBe("Switch to OpenHands DeepSeek V4 Flash (free)");+ ).toBe("Switch to openhands/glm-5.2 (free)");});it("filters saved LLM profile suggestions by profile name or model", () => {diff --git a/__tests__/hooks/query/use-free-models.test.tsx b/__tests__/hooks/query/use-free-models.test.tsxnew file mode 100644index 0000000000..48b4c33ff3--- /dev/null+++ b/__tests__/hooks/query/use-free-models.test.tsx@@ -0,0 +1,102 @@+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { renderHook, waitFor } from "@testing-library/react";+import React from "react";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import {+ __resetActiveStoreForTests,+ setActiveSelection,+ setRegisteredBackends,+} from "#/api/backend-registry/active-store";+import type { Backend } from "#/api/backend-registry/types";+import { callCloudProxy } from "#/api/cloud/proxy";+import {+ useDefaultModel,+ useFreeModels,+ useHydrateFreeModels,+} from "#/hooks/query/use-free-models";+import { useFreeModelsStore } from "#/stores/free-models-store";++vi.mock("#/api/cloud/proxy", () => ({+ callCloudProxy: vi.fn(),+}));++const cloudBackend: Backend = {+ id: "cloud-ohe",+ name: "OpenHands Cloud",+ host: "https://app.all-hands.dev",+ apiKey: "cloud-key",+ kind: "cloud",+};++const wrapper = ({ children }: { children: React.ReactNode }) => {+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ return <QueryClientProvider client={client}>{children}</QueryClientProvider>;+};++function useHydratedFreeModelState() {+ useHydrateFreeModels();+ return {+ freeModels: useFreeModels(),+ defaultModel: useDefaultModel(),+ };+}++describe("useHydrateFreeModels", () => {+ beforeEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+ setRegisteredBackends([cloudBackend]);+ setActiveSelection({ backendId: cloudBackend.id, orgId: null });+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });+ vi.mocked(callCloudProxy).mockReset();+ });++ afterEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(),+ defaultModel: null,+ });+ vi.mocked(callCloudProxy).mockReset();+ });++ it("fetches OpenHands model flags with the backend-compatible page limit", async () => {+ vi.mocked(callCloudProxy).mockImplementation((async (req: {+ path: string;+ method: string;+ }) => {+ expect(req.method).toBe("GET");+ expect(req.path).toMatch(/^\/api\/v1\/config\/models\/search/);+ const url = new URL(`http://x.example.com${req.path}`);+ expect(url.searchParams.get("provider__eq")).toBe("openhands");+ expect(url.searchParams.get("limit")).toBe("100");+ return {+ items: [+ {+ provider: "openhands",+ name: "glm-5.2",+ verified: true,+ free: true,+ default: true,+ },+ ],+ next_page_id: null,+ };+ }) as never);++ const { result } = renderHook(() => useHydratedFreeModelState(), {+ wrapper,+ });++ await waitFor(() =>+ expect(result.current.freeModels.has("openhands/glm-5.2")).toBe(true),+ );+ expect(result.current.defaultModel).toBe("openhands/glm-5.2");+ });+});diff --git a/__tests__/hooks/query/use-search-providers.test.tsx b/__tests__/hooks/query/use-search-providers.test.tsxindex de2a3fd6cd..543fad13b6 100644--- a/__tests__/hooks/query/use-search-providers.test.tsx+++ b/__tests__/hooks/query/use-search-providers.test.tsx@@ -5,11 +5,13 @@ import React from "react";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import {__resetActiveStoreForTests,+ getActiveBackend,setActiveSelection,setRegisteredBackends,} from "#/api/backend-registry/active-store";import type { Backend } from "#/api/backend-registry/types";import { callCloudProxy } from "#/api/cloud/proxy";+import { ActiveBackendProvider } from "#/contexts/active-backend-context";import { useSearchProviders } from "#/hooks/query/use-search-providers";import { server } from "#/mocks/node";@@ -161,3 +163,78 @@ describe("useSearchProviders — cloud backend pagination", () => {);});});++describe("useSearchProviders — backend switch re-keying", () => {+ const cloudBackendA: Backend = {+ ...cloudBackend,+ id: "cloud-a",+ };+ const cloudBackendB: Backend = {+ ...cloudBackend,+ id: "cloud-b",+ };++ // Wraps with ActiveBackendProvider so `useActiveBackend()` (used in the+ // query key) follows `setActiveSelection` instead of falling back to the+ // default local backend. Without the provider, the hook tests cannot+ // exercise backend-switch re-keying at all.+ const scopedWrapper = ({ children }: { children: React.ReactNode }) => {+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ return (+ <QueryClientProvider client={client}>+ <ActiveBackendProvider>{children}</ActiveBackendProvider>+ </QueryClientProvider>+ );+ };++ beforeEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+ setRegisteredBackends([cloudBackendA, cloudBackendB]);+ setActiveSelection({ backendId: cloudBackendA.id, orgId: null });+ vi.mocked(callCloudProxy).mockReset();+ });++ afterEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+ vi.mocked(callCloudProxy).mockReset();+ });++ it("refetches instead of serving the previous backend's cached provider list after a switch", async () => {+ // Backend A surfaces an "a-only" provider; backend B surfaces a+ // "b-only" provider. If the query key were unscoped, React Query would+ // serve A's cached page (within staleTime) after switching to B.+ vi.mocked(callCloudProxy).mockImplementation((async () => {+ const active = getActiveBackend();+ const items =+ active.backend.id === "cloud-a"+ ? [{ name: "a-only-provider", verified: false }]+ : [{ name: "b-only-provider", verified: false }];+ return { items, next_page_id: null };+ }) as never);++ const { result, rerender } = renderHook(() => useSearchProviders(), {+ wrapper: scopedWrapper,+ });+ await waitFor(() => expect(result.current.isSuccess).toBe(true));+ expect(result.current.data?.map((p) => p.name) ?? []).toContain(+ "a-only-provider",+ );++ // Switch to backend B inside the same session (no full reload).+ setActiveSelection({ backendId: cloudBackendB.id, orgId: null });+ rerender();++ await waitFor(() =>+ expect(result.current.data?.map((p) => p.name) ?? []).toContain(+ "b-only-provider",+ ),+ );+ expect(result.current.data?.map((p) => p.name) ?? []).not.toContain(+ "a-only-provider",+ );+ });+});diff --git a/__tests__/routes/llm-settings.test.tsx b/__tests__/routes/llm-settings.test.tsxindex 4c84200d05..d1f906b518 100644--- a/__tests__/routes/llm-settings.test.tsx+++ b/__tests__/routes/llm-settings.test.tsx@@ -12,8 +12,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest";// Import the named export LlmSettingsScreen directly for testing the form component.// The default export now renders LlmSettingsLocalView (the profiles manager view).import LlmSettingsRoute, { LlmSettingsScreen } from "#/routes/llm-settings";+import ConfigService from "#/api/config-service/config-service.api";import SettingsService from "#/api/settings-service/settings-service.api";import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";+import { useFreeModelsStore } from "#/stores/free-models-store";import { Settings } from "#/types/settings";import * as activeBackendContext from "#/contexts/active-backend-context";import type { Backend } from "#/api/backend-registry/types";@@ -117,6 +119,10 @@ function createMockLlmProfilesReturn(describe("LlmSettingsScreen", () => {beforeEach(() => {vi.restoreAllMocks();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/kimi-k3"]),+ defaultModel: "openhands/kimi-k3",+ });});it("renders the OSS LLM settings form from the SDK schema fallback", async () => {@@ -480,12 +486,32 @@ describe("LlmSettingsScreen - provider connection selector", () => {describe("LlmSettingsScreen - OpenHands provider on cloud", () => {beforeEach(() => {vi.restoreAllMocks();+ useFreeModelsStore.getState().setFlags({+ freeModels: new Set(["openhands/kimi-k3"]),+ defaultModel: "openhands/kimi-k3",+ });vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({backend: mockCloudBackend,} as ReturnType<typeof activeBackendContext.useActiveBackend>);vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings({ llm_model: "openhands/kimi-k3", llm_api_key_set: true }),);+ vi.spyOn(ConfigService, "searchProviders").mockResolvedValue({+ items: [{ name: "openhands", verified: true }],+ next_page_id: null,+ });+ vi.spyOn(ConfigService, "searchModels").mockResolvedValue({+ items: [+ {+ provider: "openhands",+ name: "kimi-k3",+ verified: true,+ free: true,+ default: true,+ },+ ],+ next_page_id: null,+ });});it("hides the inline API key and base URL inputs for an OpenHands provider model", async () => {@@ -505,7 +531,7 @@ describe("LlmSettingsScreen - OpenHands provider on cloud", () => {expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();// The free-models note is still surfaced so the user understands the model.expect(- screen.getByTestId("openhands-free-models-note"),+ await screen.findByTestId("openhands-free-models-note"),).toBeInTheDocument();});diff --git a/__tests__/utils/format-model-name.test.ts b/__tests__/utils/format-model-name.test.tsindex 66b4f15ec8..255118f85e 100644--- a/__tests__/utils/format-model-name.test.ts+++ b/__tests__/utils/format-model-name.test.ts@@ -1,12 +1,20 @@import { describe, expect, it } from "vitest";import {- FREE_OPENHANDS_MODELS,+ FREE_MODEL_SUFFIX,formatModelNameForDisplay,formatNativeModelName,formatProviderModelNameForDisplay,isFreeOpenHandsModel,} from "#/utils/format-model-name";+// DB-driven free set (sourced from the backend model list), replacing the+// previously-hardcoded free-model map.+const FREE_MODELS = new Set([+ "openhands/glm-5.2",+ "openhands/deepseek-v4-flash",+ "openhands/minimax-m2.7",+]);+describe("formatNativeModelName", () => {it("strips the provider route prefix", () => {expect(formatNativeModelName("anthropic/claude-sonnet-4-5-20250929")).toBe(@@ -15,31 +23,41 @@ describe("formatNativeModelName", () => {expect(formatNativeModelName("openai/gpt-4o")).toBe("gpt-4o");});- it("labels only configured OpenHands free-model routes as free", () => {- expect(Object.keys(FREE_OPENHANDS_MODELS)).toEqual([- "openhands/deepseek-v4-flash",- ]);+ it("treats no model as free without a free-models set", () => {+ expect(formatModelNameForDisplay("openhands/glm-5.2")).toBe(+ "openhands/glm-5.2",+ );+ expect(isFreeOpenHandsModel("openhands/glm-5.2")).toBe(false);+ });- for (const [model, label] of Object.entries(FREE_OPENHANDS_MODELS)) {- expect(formatModelNameForDisplay(model)).toBe(label);+ it("labels only DB-flagged OpenHands free-model routes as free", () => {+ for (const fullModel of FREE_MODELS) {+ const name = fullModel.slice("openhands/".length);+ expect(formatModelNameForDisplay(fullModel, FREE_MODELS)).toBe(+ `${fullModel}${FREE_MODEL_SUFFIX}`,+ );expect(- formatProviderModelNameForDisplay("openhands", model.slice(10)),- ).toBe(label);- expect(isFreeOpenHandsModel(model)).toBe(true);+ formatProviderModelNameForDisplay("openhands", name, FREE_MODELS),+ ).toBe(`${name}${FREE_MODEL_SUFFIX}`);+ expect(isFreeOpenHandsModel(fullModel, FREE_MODELS)).toBe(true);}- expect(formatModelNameForDisplay("openai/glm-5.2")).toBe("openai/glm-5.2");- expect(formatProviderModelNameForDisplay("openai", "glm-5.2")).toBe(- "glm-5.2",+ expect(formatModelNameForDisplay("openai/glm-5.2", FREE_MODELS)).toBe(+ "openai/glm-5.2",);- expect(isFreeOpenHandsModel("openai/glm-5.2")).toBe(false);+ expect(+ formatProviderModelNameForDisplay("openai", "glm-5.2", FREE_MODELS),+ ).toBe("glm-5.2");+ expect(isFreeOpenHandsModel("openai/glm-5.2", FREE_MODELS)).toBe(false);});- it("keeps free OpenHands labels on native conversation chips", () => {- expect(formatNativeModelName("openhands/glm-5.2")).toBe("glm-5.2");- expect(formatNativeModelName("openhands/deepseek-v4-flash")).toBe(- FREE_OPENHANDS_MODELS["openhands/deepseek-v4-flash"],+ it("keeps the free suffix on native conversation chips", () => {+ expect(formatNativeModelName("openhands/glm-5.2", FREE_MODELS)).toBe(+ `glm-5.2${FREE_MODEL_SUFFIX}`,);+ expect(+ formatNativeModelName("openhands/deepseek-v4-flash", FREE_MODELS),+ ).toBe(`deepseek-v4-flash${FREE_MODEL_SUFFIX}`);});it("strips nested routing prefixes to the last segment", () => {diff --git a/src/api/config-service/config-service.api.ts b/src/api/config-service/config-service.api.tsindex 3953a6d56e..6f2320d2eb 100644--- a/src/api/config-service/config-service.api.ts+++ b/src/api/config-service/config-service.api.ts@@ -99,10 +99,15 @@ class ConfigService {const verifiedNames = new Set(provider ? (verifiedMap?.[provider] ?? []) : [],);+ // The local agent-server has no model database, so it exposes no free /+ // default metadata; both are always false here. Cloud backends embed the+ // DB-driven flags natively on each item (handled above).const verifiedItems: LLMModel[] = [...verifiedNames].map((name) => ({provider,name,verified: true,+ free: false,+ default: false,}));const prefixedItems: LLMModel[] = provider@@ -114,6 +119,8 @@ class ConfigService {provider,name,verified: false,+ free: false,+ default: false,})): [];diff --git a/src/api/config-service/config-service.types.ts b/src/api/config-service/config-service.types.tsindex dc8e7235bb..3a9344f649 100644--- a/src/api/config-service/config-service.types.ts+++ b/src/api/config-service/config-service.types.ts@@ -4,6 +4,19 @@ export interface LLMModel {provider: string | null;name: string;verified: boolean;+ /**+ * Whether the model is free to use on the OpenHands provider. Mirrors+ * `verified`: it is populated by the backend model list (DB-driven on+ * cloud) and defaults to `false` where no free metadata exists (e.g. the+ * local agent-server reconstruction path, which has no model database).+ */+ free: boolean;+ /**+ * Whether this is the provider's default model. Mirrors `free`: DB-driven on+ * cloud, `false` where no default metadata exists. Used to preselect the+ * model on onboarding and when creating a new model for the provider.+ */+ default: boolean;}export interface LLMModelPage {diff --git a/src/components/features/chat/components/chat-input-llm-profile-picker.tsx b/src/components/features/chat/components/chat-input-llm-profile-picker.tsxindex 0cf740f7e6..60dfada5c3 100644--- a/src/components/features/chat/components/chat-input-llm-profile-picker.tsx+++ b/src/components/features/chat/components/chat-input-llm-profile-picker.tsx@@ -13,7 +13,8 @@ import { Typography } from "#/ui/typography";import { I18nKey } from "#/i18n/declaration";import { cn } from "#/utils/utils";import { chatInputPillButtonClassName } from "#/utils/form-control-classes";-import { formatModelNameForDisplay } from "#/utils/format-model-name";+import { useFreeModels } from "#/hooks/query/use-free-models";+import { formatModelPillLabel } from "#/utils/format-model-name";const PROFILE_LABEL_MAX_CHARS = 18;@@ -43,6 +44,7 @@ export function ChatInputLlmProfileMenuContent({settingsIconClassName,}: ChatInputLlmProfileMenuContentProps) {const { t } = useTranslation("openhands");+ const freeModels = useFreeModels();const {profiles,currentProfileName,@@ -74,7 +76,10 @@ export function ChatInputLlmProfileMenuContent({</li>{profiles.map((profile) => {const isCurrent = profile.name === currentProfileName;- const displayModel = formatModelNameForDisplay(profile.model);+ const displayModel = formatModelPillLabel(+ profile.model,+ freeModels,+ );return (<ContextMenuListItemkey={profile.name}@@ -127,7 +132,7 @@ export function ChatInputLlmProfileMenuContent({</span>{currentProfileModel && (<span className="truncate text-xs leading-4 text-[var(--oh-muted)]">- {formatModelNameForDisplay(currentProfileModel)}+ {formatModelPillLabel(currentProfileModel, freeModels)}</span>)}</div>diff --git a/src/components/features/chat/model-messages.tsx b/src/components/features/chat/model-messages.tsxindex 901ae6ddca..eddb6483d9 100644--- a/src/components/features/chat/model-messages.tsx+++ b/src/components/features/chat/model-messages.tsx@@ -5,6 +5,7 @@ import { useModelStore } from "#/stores/model-store";import { I18nKey } from "#/i18n/declaration";import InfoCircleIcon from "#/icons/info-circle.svg?react";import type { ProfileInfo } from "#/api/profiles-service/profiles-service.api";+import { useFreeModels } from "#/hooks/query/use-free-models";import { formatModelNameForDisplay } from "#/utils/format-model-name";import { GenericEventMessage } from "./generic-event-message";@@ -14,7 +15,8 @@ interface ProfileRowProps {function ProfileRow({ profile }: ProfileRowProps) {const [expanded, setExpanded] = React.useState(false);- const displayModel = formatModelNameForDisplay(profile.model);+ const freeModels = useFreeModels();+ const displayModel = formatModelNameForDisplay(profile.model, freeModels);return (<div className="border border-neutral-700 rounded-md overflow-hidden">diff --git a/src/components/features/conversation-panel/conversation-card/conversation-card-footer.tsx b/src/components/features/conversation-panel/conversation-card/conversation-card-footer.tsxindex 49ddbbbb36..f1bb2d5689 100644--- a/src/components/features/conversation-panel/conversation-card/conversation-card-footer.tsx+++ b/src/components/features/conversation-panel/conversation-card/conversation-card-footer.tsx@@ -10,6 +10,7 @@ import {labelForAcpModel,resolveAcpProviderIcon,} from "#/constants/acp-providers";+import { useFreeModels } from "#/hooks/query/use-free-models";import { formatNativeModelName } from "#/utils/format-model-name";import {AgentBrandIcon,@@ -87,6 +88,7 @@ export function ConversationCardFooter({isArchived = false,}: ConversationCardFooterProps) {const { t } = useTranslation("openhands");+ const freeModels = useFreeModels();const isPaused = isExecutionPaused(executionStatus);@@ -121,7 +123,7 @@ export function ConversationCardFooter({// the chip text; keep the full routing string in the tooltip.chip = {kind: "openhands",- text: formatNativeModelName(llmModel) ?? llmModel,+ text: formatNativeModelName(llmModel, freeModels) ?? llmModel,tooltip: llmModel,};}diff --git a/src/components/features/onboarding/steps/setup-llm-step.tsx b/src/components/features/onboarding/steps/setup-llm-step.tsxindex b7be1d5644..97a83c3439 100644--- a/src/components/features/onboarding/steps/setup-llm-step.tsx+++ b/src/components/features/onboarding/steps/setup-llm-step.tsx@@ -8,6 +8,11 @@ import { useActiveBackend } from "#/contexts/active-backend-context";import { useSaveLlmProfile } from "#/hooks/mutation/use-save-llm-profile";import { useActivateLlmProfile } from "#/hooks/mutation/use-activate-llm-profile";import { useApplyOnboardingAgentProfile } from "#/hooks/mutation/use-apply-onboarding-agent-profile";+import {+ useDefaultModel,+ useDefaultModelReady,+} from "#/hooks/query/use-free-models";+import { LlmSettingsInputsSkeleton } from "#/components/features/settings/llm-settings/llm-settings-inputs-skeleton";import { deriveProfileNameFromModel } from "#/utils/derive-profile-name";interface SetupLlmStepProps {@@ -16,10 +21,9 @@ interface SetupLlmStepProps {}/**- * Pre-fills the LLM form with the OpenAI GPT-5.6 Sol default- * (`openai/gpt-5.6-sol`), matching `DEFAULT_SETTINGS.llm_model`. The explicit- * override marks the model dirty so the Next button persists the suggested- * default immediately.+ * Fallback when the backend has not exposed a DB-selected OpenHands default.+ * The onboarding override still marks the model dirty so Next persists the+ * suggested model immediately.*/export const ONBOARDING_DEFAULT_LLM_MODEL = "openai/gpt-5.6-sol";@@ -47,6 +51,9 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {const saveProfile = useSaveLlmProfile();const activateProfile = useActivateLlmProfile();const applyAgentProfile = useApplyOnboardingAgentProfile();+ const dbDefaultLlmModel = useDefaultModel();+ const isDefaultModelReady = useDefaultModelReady();+ const defaultLlmModel = dbDefaultLlmModel ?? ONBOARDING_DEFAULT_LLM_MODEL;const [saveControl, setSaveControl] =React.useState<SdkSectionSaveControl | null>(null);const [isFinalizing, setIsFinalizing] = React.useState(false);@@ -148,16 +155,20 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {data-testid="onboarding-llm-settings"className="flex min-h-0 flex-1 flex-col overflow-y-auto custom-scrollbar-always">- <LlmSettingsScreen- embedded- hideSaveButton- suppressSuccessToast- initialValueOverrides={{- "llm.model": ONBOARDING_DEFAULT_LLM_MODEL,- }}- onSaveSuccess={handleSaveSuccess}- onSaveControlChange={setSaveControl}- />+ {isDefaultModelReady ? (+ <LlmSettingsScreen+ embedded+ hideSaveButton+ suppressSuccessToast+ initialValueOverrides={{+ "llm.model": defaultLlmModel,+ }}+ onSaveSuccess={handleSaveSuccess}+ onSaveControlChange={setSaveControl}+ />+ ) : (+ <LlmSettingsInputsSkeleton />+ )}</div><div className="sticky bottom-0 flex items-center justify-between gap-2 bg-base-secondary pt-4 pb-7">@@ -173,7 +184,11 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {testId="onboarding-llm-next"type="button"variant="primary"- isDisabled={(saveControl?.isSaving ?? false) || isFinalizing}+ isDisabled={+ !isDefaultModelReady ||+ (saveControl?.isSaving ?? false) ||+ isFinalizing+ }onClick={handleNext}>{t(I18nKey.ONBOARDING$NEXT)}diff --git a/src/components/features/settings/llm-profiles/llm-settings-local-view.tsx b/src/components/features/settings/llm-profiles/llm-settings-local-view.tsxindex 293f6e3edb..06520f9840 100644--- a/src/components/features/settings/llm-profiles/llm-settings-local-view.tsx+++ b/src/components/features/settings/llm-profiles/llm-settings-local-view.tsx@@ -19,6 +19,11 @@ import { useActivateLlmProfile } from "#/hooks/mutation/use-activate-llm-profileimport { useLlmProfiles } from "#/hooks/query/use-llm-profiles";import { useSettings } from "#/hooks/query/use-settings";import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema";+import {+ useDefaultModel,+ useDefaultModelReady,+} from "#/hooks/query/use-free-models";+import { LlmSettingsInputsSkeleton } from "#/components/features/settings/llm-settings/llm-settings-inputs-skeleton";import { DEFAULT_SETTINGS } from "#/services/settings";import ProfilesService, {ProfileInfo,@@ -99,6 +104,15 @@ export function LlmSettingsLocalView() {const { data: agentSchema } = useAgentSettingsSchema(settings?.agent_settings_schema,);+ const createProfileDefaultModel =+ useDefaultModel() ?? DEFAULT_SETTINGS.llm_model;+ // Gate new-profile creation on the DB default query settling, mirroring+ // onboarding's `useDefaultModelReady`. Without this, clicking Add before+ // the hydrator finishes mounts the keyed form with the static fallback+ // model; SdkSectionPage ignores later initial-value changes once an+ // embedded form hydrates, so the eventual DB default never replaces it and+ // the user can save the wrong model.+ const isDefaultModelReady = useDefaultModelReady();// Always hold the freshest schema. `handleEditProfile` awaits a network// round-trip before seeding the form, so reading the schema from a ref@@ -487,34 +501,42 @@ export function LlmSettingsLocalView() {isRequired/>- {/* Profile form - key ensures form remounts when switching profiles */}- <LlmSettingsScreen- key={- viewMode === "edit"- ? `edit-${editingProfile?.profile.name}`- : "new-profile"- }- embedded- hideSaveButton- markInitialOverridesDirty={false}- initialValueOverrides={- viewMode === "edit" && editingProfile?.initialValues- ? // Edit mode: use the existing profile values- editingProfile.initialValues- : // Create mode: prefill the model with Canvas' free default,- // while keeping secret/base URL fields blank for a fresh profile.- {- "llm.model": DEFAULT_SETTINGS.llm_model,- "llm.api_key": "",- "llm.base_url": "",- [LLM_PROVIDER_CONNECTION_KEY]: "",- [LLM_AUTH_TYPE_KEY]: LLM_AUTH_TYPE_API_KEY,- [LLM_SUBSCRIPTION_VENDOR_KEY]: OPENAI_SUBSCRIPTION_VENDOR,- }- }- showProviderConnection={supportsConnections}- onSaveControlChange={handleSaveControlChange}- />+ {/* Profile form - key ensures form remounts when switching profiles.+ In create mode, wait for the DB default query to settle before+ mounting the keyed form; otherwise SdkSectionPage would hydrate with+ the static fallback and ignore the eventual DB default. Edit mode is+ seeded from the existing profile, so it does not need the gate. */}+ {viewMode === "create" && !isDefaultModelReady ? (+ <LlmSettingsInputsSkeleton />+ ) : (+ <LlmSettingsScreen+ key={+ viewMode === "edit"+ ? `edit-${editingProfile?.profile.name}`+ : "new-profile"+ }+ embedded+ hideSaveButton+ markInitialOverridesDirty={false}+ initialValueOverrides={+ viewMode === "edit" && editingProfile?.initialValues+ ? // Edit mode: use the existing profile values+ editingProfile.initialValues+ : // Create mode: prefill with the backend-selected default model,+ // while keeping secret/base URL fields blank for a fresh profile.+ {+ "llm.model": createProfileDefaultModel,+ "llm.api_key": "",+ "llm.base_url": "",+ [LLM_PROVIDER_CONNECTION_KEY]: "",+ [LLM_AUTH_TYPE_KEY]: LLM_AUTH_TYPE_API_KEY,+ [LLM_SUBSCRIPTION_VENDOR_KEY]: OPENAI_SUBSCRIPTION_VENDOR,+ }+ }+ showProviderConnection={supportsConnections}+ onSaveControlChange={handleSaveControlChange}+ />+ )}{/* Action buttons */}<div className="flex justify-start gap-3 pt-4">diff --git a/src/components/features/settings/llm-profiles/profile-row.tsx b/src/components/features/settings/llm-profiles/profile-row.tsxindex cf1415355b..0d072b21ad 100644--- a/src/components/features/settings/llm-profiles/profile-row.tsx+++ b/src/components/features/settings/llm-profiles/profile-row.tsx@@ -7,6 +7,7 @@ import { I18nKey } from "#/i18n/declaration";import { EllipsisButton } from "#/components/features/conversation-panel/ellipsis-button";import { BrandBadge } from "#/components/shared/badge";import { cn } from "#/utils/utils";+import { useFreeModels } from "#/hooks/query/use-free-models";import { formatModelNameForDisplay } from "#/utils/format-model-name";import {settingsListIconActionButtonClassName,@@ -40,7 +41,8 @@ export function ProfileRow({const { t } = useTranslation("openhands");const [menuOpen, setMenuOpen] = useState(false);const triggerRef = useRef<HTMLButtonElement>(null);- const displayModel = formatModelNameForDisplay(profile.model);+ const freeModels = useFreeModels();+ const displayModel = formatModelNameForDisplay(profile.model, freeModels);return (<divdiff --git a/src/components/providers/agent-server-ui-providers.tsx b/src/components/providers/agent-server-ui-providers.tsxindex 5a71a58f6f..b9f884355f 100644--- a/src/components/providers/agent-server-ui-providers.tsx+++ b/src/components/providers/agent-server-ui-providers.tsx@@ -14,6 +14,7 @@ import {setI18n,} from "#/i18n";import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import { useHydrateFreeModels } from "#/hooks/query/use-free-models";import type { TelemetryConfig } from "#/services/telemetry";import { TelemetryProvider } from "./telemetry-provider";import {@@ -45,6 +46,16 @@ export interface AgentServerUIProvidersProps extends Pick<withStyleRoot?: boolean;}+/**+ * Fetches the DB-driven free / default model flags once and mirrors them into+ * the free-models store. Rendered inside the query provider so leaf components+ * can read the flags synchronously without a QueryClientProvider in scope.+ */+function FreeModelsHydrator() {+ useHydrateFreeModels();+ return null;+}+export function AgentServerUIProviders({children,queryClient,@@ -96,7 +107,10 @@ export function AgentServerUIProviders({}: false;const content = (- <TelemetryProvider config={posthogConfig}>{children}</TelemetryProvider>+ <TelemetryProvider config={posthogConfig}>+ <FreeModelsHydrator />+ {children}+ </TelemetryProvider>);const wrappedContent = withStyleRoot ? (diff --git a/src/components/shared/free-models-note.tsx b/src/components/shared/free-models-note.tsxnew file mode 100644index 0000000000..bd1da7df78--- /dev/null+++ b/src/components/shared/free-models-note.tsx@@ -0,0 +1,25 @@+import { Info } from "lucide-react";+import { useTranslation } from "react-i18next";+import { I18nKey } from "#/i18n/declaration";++export function FreeOpenHandsModelsNote({+ modelIds,+}: {+ modelIds: Iterable<string>;+}) {+ const { t } = useTranslation("openhands");++ return (+ <p+ data-testid="openhands-free-models-note"+ className="flex items-start gap-2 text-xs text-warning"+ >+ <Info className="mt-0.5 size-4 shrink-0 text-warning" aria-hidden />+ <span>+ {t(I18nKey.SETTINGS$OPENHANDS_FREE_MODELS_NOTE, {+ ids: [...modelIds].join(", "),+ })}+ </span>+ </p>+ );+}diff --git a/src/components/shared/modals/settings/model-selector.tsx b/src/components/shared/modals/settings/model-selector.tsxindex 754f24743f..2f1379ea22 100644--- a/src/components/shared/modals/settings/model-selector.tsx+++ b/src/components/shared/modals/settings/model-selector.tsx@@ -3,7 +3,6 @@ import {AutocompleteItem,AutocompleteSection,} from "@heroui/react";-import { Info } from "lucide-react";import React from "react";import { useTranslation } from "react-i18next";import { I18nKey } from "#/i18n/declaration";@@ -16,27 +15,12 @@ import { HelpLink } from "#/ui/help-link";import { PRODUCT_URL } from "#/utils/constants";import { useSearchProviders } from "#/hooks/query/use-search-providers";import { useProviderModels } from "#/hooks/query/use-provider-models";-import {- FREE_MODEL_BADGE_LABEL,- FREE_OPENHANDS_MODEL_NOTE,- isFreeOpenHandsModel,-} from "#/utils/format-model-name";+import { FREE_MODEL_BADGE_LABEL } from "#/utils/format-model-name";+import { FreeOpenHandsModelsNote } from "#/components/shared/free-models-note";const freeModelBadgeClassName ="shrink-0 rounded-full border border-warning/40 bg-warning/10 px-1.5 py-0.5 text-[10px] leading-none text-warning";-function FreeOpenHandsModelsNote() {- return (- <p- data-testid="openhands-free-models-note"- className="flex items-start gap-2 text-xs text-warning"- >- <Info className="mt-0.5 size-4 shrink-0 text-warning" aria-hidden />- <span>{FREE_OPENHANDS_MODEL_NOTE}</span>- </p>- );-}-interface ModelSelectorProps {isDisabled?: boolean;currentModel?: string;@@ -88,6 +72,17 @@ export function ModelSelector({[providerModels],);+ // DB-driven set of free model names for the selected provider. Mirrors the+ // `verified` flag: the frontend no longer hardcodes which models are free.+ const freeModelNames = React.useMemo(+ () => providerModels.filter((m) => m.free).map((m) => m.name),+ [providerModels],+ );+ const freeModelNameSet = React.useMemo(+ () => new Set(freeModelNames),+ [freeModelNames],+ );+React.useEffect(() => {if (currentModel) {const { provider, model } = extractModelAndProvider(currentModel);@@ -121,11 +116,9 @@ export function ModelSelector({setLitellmId(null);};- const selectedFullModel =- selectedProvider && selectedModel- ? `${selectedProvider}/${selectedModel}`- : null;- const isSelectedModelFree = isFreeOpenHandsModel(selectedFullModel);+ const isSelectedModelFree = Boolean(+ selectedModel && freeModelNameSet.has(selectedModel),+ );const selectedModelMeasureRef = React.useRef<HTMLSpanElement>(null);const [selectedModelTextWidth, setSelectedModelTextWidth] = React.useState(0);@@ -272,9 +265,7 @@ export function ModelSelector({<AutocompleteItem key={model.name} textValue={model.name}><span className="flex min-w-0 items-center gap-2"><span className="truncate">{model.name}</span>- {isFreeOpenHandsModel(- `${selectedProvider}/${model.name}`,- ) ? (+ {model.free ? (<span className={freeModelBadgeClassName}>{FREE_MODEL_BADGE_LABEL}</span>@@ -329,7 +320,13 @@ export function ModelSelector({{t(I18nKey.CONFIGURATION$ERROR_FETCH_MODELS)}</p>)}- {selectedProvider === "openhands" ? <FreeOpenHandsModelsNote /> : null}+ {selectedProvider === "openhands" && freeModelNames.length > 0 ? (+ <FreeOpenHandsModelsNote+ modelIds={freeModelNames.map(+ (name) => `${selectedProvider}/${name}`,+ )}+ />+ ) : null}</fieldset></div>);diff --git a/src/hooks/chat/use-slash-command.ts b/src/hooks/chat/use-slash-command.tsindex 4ee41199bf..2035288601 100644--- a/src/hooks/chat/use-slash-command.ts+++ b/src/hooks/chat/use-slash-command.ts@@ -4,6 +4,7 @@ import { SkillInfo } from "#/types/settings";import { BUILT_IN_COMMANDS, MODEL_COMMAND } from "#/utils/constants";import { useActiveBackend } from "#/contexts/active-backend-context";import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";+import { useFreeModels } from "#/hooks/query/use-free-models";import { formatModelNameForDisplay } from "#/utils/format-model-name";export type SlashCommandSkill = SkillInfo;@@ -40,6 +41,7 @@ export const useSlashCommand = (const { data: skills, isLoading: isSkillsLoading } = useConversationSkills();const isCloud = useActiveBackend().backend.kind === "cloud";const { data: profilesData, isLoading: isProfilesLoading } = useLlmProfiles();+ const freeModels = useFreeModels();const [isMenuOpen, setIsMenuOpen] = useState(false);const [filterText, setFilterText] = useState("");const [completionKind, setCompletionKind] =@@ -89,13 +91,13 @@ export const useSlashCommand = (type: "agentskills",source: null,content: profile.model- ? `Switch to ${formatModelNameForDisplay(profile.model)}`+ ? `Switch to ${formatModelNameForDisplay(profile.model, freeModels)}`: "Switch to this LLM profile",triggers: [command],},};});- }, [profilesData?.profiles]);+ }, [profilesData?.profiles, freeModels]);// Filter items based on user input after "/"const filteredItems = useMemo(() => {diff --git a/src/hooks/query/use-free-models.ts b/src/hooks/query/use-free-models.tsnew file mode 100644index 0000000000..9ff713ab76--- /dev/null+++ b/src/hooks/query/use-free-models.ts@@ -0,0 +1,156 @@+import React from "react";+import { useQuery } from "@tanstack/react-query";+import ConfigService from "#/api/config-service/config-service.api";+import type { LLMModel } from "#/api/config-service/config-service.types";+import type { FreeModelSet } from "#/utils/format-model-name";+import { useFreeModelsStore } from "#/stores/free-models-store";+import { useActiveBackend } from "#/contexts/active-backend-context";+import {+ VERIFIED_MODELS_GC_TIME,+ VERIFIED_MODELS_QUERY_KEY,+ VERIFIED_MODELS_STALE_TIME,+ fetchVerifiedModelsByProvider,+} from "./use-verified-models";++/**+ * Provider whose models carry free / default metadata. Both are+ * OpenHands-managed concepts, so they are scoped to the `openhands` provider.+ */+const OPENHANDS_PROVIDER = "openhands";+const CLOUD_MODEL_SEARCH_PAGE_LIMIT = 100;+const MAX_PAGINATION_DEPTH = 10;++async function fetchAllOpenHandsModels(+ verifiedByProvider: Record<string, string[]>,+ pageId: string | null | undefined,+ seenPageIds: Set<string>,+ depth: number,+): Promise<LLMModel[]> {+ if (depth >= MAX_PAGINATION_DEPTH) {+ throw new Error(+ `Too many pagination requests while fetching OpenHands models (depth=${depth})`,+ );+ }++ const page = await ConfigService.searchModels(+ {+ provider__eq: OPENHANDS_PROVIDER,+ limit: CLOUD_MODEL_SEARCH_PAGE_LIMIT,+ ...(pageId ? { page_id: pageId } : {}),+ },+ verifiedByProvider,+ );++ if (!page.next_page_id) {+ return page.items;+ }++ if (seenPageIds.has(page.next_page_id)) {+ throw new Error(+ `Repeated page id while fetching OpenHands models: ${page.next_page_id}`,+ );+ }+ seenPageIds.add(page.next_page_id);++ const rest = await fetchAllOpenHandsModels(+ verifiedByProvider,+ page.next_page_id,+ seenPageIds,+ depth + 1,+ );+ return [...page.items, ...rest];+}++/**+ * Fetches the `openhands` provider's models with their DB-driven `free` /+ * `default` flags (the same channel that carries `verified`).+ */+const useOpenHandsModels = () => {+ const { backend, orgId } = useActiveBackend();+ const backendScope = [+ backend.id,+ backend.connectionRevision ?? 0,+ orgId,+ ] as const;++ return useQuery({+ queryKey: [+ "config",+ "models",+ OPENHANDS_PROVIDER,+ "flags",+ ...backendScope,+ ],+ queryFn: async ({ client }): Promise<LLMModel[]> => {+ const verifiedByProvider = await client.fetchQuery({+ queryKey: [...VERIFIED_MODELS_QUERY_KEY, ...backendScope],+ queryFn: fetchVerifiedModelsByProvider,+ staleTime: VERIFIED_MODELS_STALE_TIME,+ });+ return fetchAllOpenHandsModels(verifiedByProvider, null, new Set(), 0);+ },+ staleTime: VERIFIED_MODELS_STALE_TIME,+ gcTime: VERIFIED_MODELS_GC_TIME,+ });+};++/**+ * Fetches the DB-driven free / default flags once and mirrors them into the+ * {@link useFreeModelsStore}. Mount this high in the tree (inside the query+ * provider). Leaf display components then read the flags synchronously via the+ * {@link useFreeModels} / {@link useDefaultModel} zustand selectors, so they+ * stay renderable in isolation without a QueryClientProvider in scope.+ */+export const useHydrateFreeModels = (): void => {+ const { backend, orgId } = useActiveBackend();+ const { data, isError } = useOpenHandsModels();+ const setFlags = useFreeModelsStore((state) => state.setFlags);+ const markDefaultModelReady = useFreeModelsStore(+ (state) => state.markDefaultModelReady,+ );+ const resetFlags = useFreeModelsStore((state) => state.resetFlags);++ React.useEffect(() => {+ resetFlags();+ }, [backend.id, backend.connectionRevision, orgId, resetFlags]);++ React.useEffect(() => {+ if (!data) return;+ const freeModels = new Set(+ data+ .filter((model) => model.free)+ .map((model) => `${OPENHANDS_PROVIDER}/${model.name}`),+ );+ const defaultEntry = data.find((model) => model.default);+ setFlags({+ freeModels,+ defaultModel: defaultEntry+ ? `${OPENHANDS_PROVIDER}/${defaultEntry.name}`+ : null,+ });+ }, [data, setFlags]);++ React.useEffect(() => {+ if (isError) markDefaultModelReady();+ }, [isError, markDefaultModelReady]);+};++/**+ * Set of free ``openhands/<model>`` ids, sourced from the backend model list+ * (DB-driven on cloud via the `free` flag). Returns an empty set on backends+ * without free metadata (e.g. the local agent-server), so callers uniformly+ * treat "not in set" as paid and the frontend keeps no hardcoded free list.+ */+export const useFreeModels = (): FreeModelSet =>+ useFreeModelsStore((state) => state.freeModels);++/**+ * DB-driven default OpenHands model id (``openhands/<model>``), used to+ * preselect a model on onboarding and when creating a new OpenHands model.+ * Returns `null` on backends without default metadata.+ */+export const useDefaultModel = (): string | null =>+ useFreeModelsStore((state) => state.defaultModel);++export const useDefaultModelReady = (): boolean =>+ useFreeModelsStore((state) => state.defaultModelReady);diff --git a/src/hooks/query/use-local-git-info.ts b/src/hooks/query/use-local-git-info.tsindex c7c5347ee9..6e87e4673f 100644--- a/src/hooks/query/use-local-git-info.ts+++ b/src/hooks/query/use-local-git-info.ts@@ -133,7 +133,7 @@ export const useLocalGitInfo = () => {// runCommandRef is a ref (always stable); the linter cannot infer this so// we disable the exhaustive-deps check here.- // eslint-disable-next-line @tanstack/query/exhaustive-deps+return useQuery<LocalGitInfo>({queryKey: ["local-git-info",diff --git a/src/hooks/query/use-provider-models.ts b/src/hooks/query/use-provider-models.tsindex 8ac72981a4..84477ca1dd 100644--- a/src/hooks/query/use-provider-models.ts+++ b/src/hooks/query/use-provider-models.ts@@ -1,6 +1,7 @@import { useQuery } from "@tanstack/react-query";import ConfigService from "#/api/config-service/config-service.api";import type { LLMModel } from "#/api/config-service/config-service.types";+import { useActiveBackend } from "#/contexts/active-backend-context";import {VERIFIED_MODELS_GC_TIME,VERIFIED_MODELS_QUERY_KEY,@@ -41,12 +42,24 @@ async function fetchPage(return page.items;}-export const useProviderModels = (provider: string | null) =>- useQuery({- queryKey: ["config", "models", provider],+export const useProviderModels = (provider: string | null) => {+ // `ActiveBackendProvider` deliberately does not blanket-invalidate on+ // backend/org switches, so the query key must carry the active backend+ // identity (id, connection revision, org id). Otherwise React Query serves+ // the previous backend/org's cached page — including DB-driven `free`/+ // `default`/`verified` flags — for the full stale window after a switch.+ const { backend, orgId } = useActiveBackend();+ const backendScope = [+ backend.id,+ backend.connectionRevision ?? 0,+ orgId,+ ] as const;++ return useQuery({+ queryKey: ["config", "models", provider, ...backendScope],queryFn: async ({ client }) => {const verifiedByProvider = await client.fetchQuery({- queryKey: VERIFIED_MODELS_QUERY_KEY,+ queryKey: [...VERIFIED_MODELS_QUERY_KEY, ...backendScope],queryFn: fetchVerifiedModelsByProvider,staleTime: VERIFIED_MODELS_STALE_TIME,});@@ -56,3 +69,4 @@ export const useProviderModels = (provider: string | null) =>staleTime: VERIFIED_MODELS_STALE_TIME,gcTime: VERIFIED_MODELS_GC_TIME,});+};diff --git a/src/hooks/query/use-search-providers.ts b/src/hooks/query/use-search-providers.tsindex cfac2c01c4..134b0fe5b4 100644--- a/src/hooks/query/use-search-providers.ts+++ b/src/hooks/query/use-search-providers.ts@@ -1,6 +1,7 @@import { useQuery } from "@tanstack/react-query";import ConfigService from "#/api/config-service/config-service.api";import type { LLMProvider } from "#/api/config-service/config-service.types";+import { useActiveBackend } from "#/contexts/active-backend-context";import {VERIFIED_MODELS_GC_TIME,VERIFIED_MODELS_QUERY_KEY,@@ -54,12 +55,24 @@ async function fetchAllProviders(return [...page.items, ...rest];}-export const useSearchProviders = () =>- useQuery({- queryKey: ["config", "providers"],+export const useSearchProviders = () => {+ // `ActiveBackendProvider` deliberately does not blanket-invalidate on+ // backend/org switches, so the query key must carry the active backend+ // identity (id, connection revision, org id). Otherwise React Query serves+ // the previous backend/org's cached provider list — including DB-driven+ // `verified` flags — for the full stale window after a switch.+ const { backend, orgId } = useActiveBackend();+ const backendScope = [+ backend.id,+ backend.connectionRevision ?? 0,+ orgId,+ ] as const;++ return useQuery({+ queryKey: ["config", "providers", ...backendScope],queryFn: async ({ client }): Promise<LLMProvider[]> => {const verifiedByProvider = await client.fetchQuery({- queryKey: VERIFIED_MODELS_QUERY_KEY,+ queryKey: [...VERIFIED_MODELS_QUERY_KEY, ...backendScope],queryFn: fetchVerifiedModelsByProvider,staleTime: VERIFIED_MODELS_STALE_TIME,});@@ -71,3 +84,4 @@ export const useSearchProviders = () =>staleTime: VERIFIED_MODELS_STALE_TIME,gcTime: VERIFIED_MODELS_GC_TIME,});+};diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex f555462abb..db383de480 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -11797,6 +11797,23 @@"uk": "Ключі API дозволяють вам програмно автентифікуватися за допомогою API OpenHands. Зберігайте свої ключі API в безпеці; будь-хто, хто має ваш ключ API, може отримати доступ до вашого облікового запису. Для отримання додаткової інформації про використання API, перегляньте нашу <a>документацію API</a>.","ca": "Les claus d'API us permeten autenticar-vos amb l'API d'OpenHands de manera programàtica. Manteniu les vostres claus d'API segures; qualsevol persona amb la vostra clau d'API pot accedir al vostre compte. Per obtenir més informació sobre com fer servir l'API, consulteu la nostra <a>documentació de l'API</a>."},+ "SETTINGS$OPENHANDS_FREE_MODELS_NOTE": {+ "en": "Free OpenHands models: {{ids}}. Other provider endpoints with similar model names may require separate billing.",+ "ja": "無料の OpenHands モデル: {{ids}}。同じようなモデル名を持つ他のプロバイダーのエンドポイントでは、別途料金が発生する場合があります。",+ "zh-CN": "免费的 OpenHands 模型:{{ids}}。其他提供商中名称相似的模型端点可能需要单独付费。",+ "zh-TW": "免費的 OpenHands 模型:{{ids}}。其他供應商中名稱相似的模型端點可能需要另外付費。",+ "ko-KR": "무료 OpenHands 모델: {{ids}}. 이름이 비슷한 다른 제공업체의 모델 엔드포인트에는 별도 요금이 부과될 수 있습니다.",+ "no": "Gratis OpenHands-modeller: {{ids}}. Endepunkter hos andre leverandører med lignende modellnavn kan kreve separat betaling.",+ "it": "Modelli OpenHands gratuiti: {{ids}}. Gli endpoint di altri provider con nomi di modello simili potrebbero richiedere una fatturazione separata.",+ "pt": "Modelos OpenHands gratuitos: {{ids}}. Endpoints de outros provedores com nomes de modelo semelhantes podem exigir cobrança separada.",+ "es": "Modelos gratuitos de OpenHands: {{ids}}. Los endpoints de otros proveedores con nombres de modelo similares pueden requerir una facturación separada.",+ "ar": "نماذج OpenHands المجانية: {{ids}}. قد تتطلب نقاط نهاية موفّري الخدمة الآخرين ذات أسماء النماذج المشابهة فوترة منفصلة.",+ "fr": "Modèles OpenHands gratuits : {{ids}}. Les points de terminaison d’autres fournisseurs portant des noms de modèles similaires peuvent nécessiter une facturation distincte.",+ "tr": "Ücretsiz OpenHands modelleri: {{ids}}. Benzer model adlarına sahip diğer sağlayıcı uç noktaları ayrı ücretlendirme gerektirebilir.",+ "de": "Kostenlose OpenHands-Modelle: {{ids}}. Endpunkte anderer Anbieter mit ähnlichen Modellnamen können eine separate Abrechnung erfordern.",+ "uk": "Безкоштовні моделі OpenHands: {{ids}}. Кінцеві точки інших постачальників зі схожими назвами моделей можуть потребувати окремої оплати.",+ "ca": "Models gratuïts d’OpenHands: {{ids}}. Els endpoints d’altres proveïdors amb noms de model similars poden requerir una facturació separada."+ },"SETTINGS$OPENHANDS_API_KEY_HELP_TEXT": {"en": "You can find your OpenHands Provider LLM Key in the","ja": "OpenHands Provider LLM Key は",diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.tsindex 7e831b5ae8..81e6cd843b 100644--- a/src/mocks/settings-handlers.ts+++ b/src/mocks/settings-handlers.ts@@ -630,6 +630,12 @@ const MOCK_VERIFIED_MODELS = new Set(["openhands/glm-5.2",]);+// DB-driven free / default flags for the OpenHands provider. Mirrors the+// enterprise verified-models seed used to render the "Free" badge and preselect+// the default model.+const MOCK_FREE_MODELS = new Set(["openhands/glm-5.2"]);+const MOCK_DEFAULT_MODEL = "openhands/glm-5.2";+const MOCK_VERIFIED_PROVIDERS = ["openhands","anthropic",@@ -806,6 +812,8 @@ export const SETTINGS_HANDLERS = [provider: provider || null,name,verified: MOCK_VERIFIED_MODELS.has(m),+ free: MOCK_FREE_MODELS.has(m),+ default: m === MOCK_DEFAULT_MODEL,};});diff --git a/src/routes/app-settings.tsx b/src/routes/app-settings.tsxindex b6e76b0e04..d00cba5e3e 100644--- a/src/routes/app-settings.tsx+++ b/src/routes/app-settings.tsx@@ -21,6 +21,7 @@ import { AppSettingsInputsSkeleton } from "#/components/features/settings/app-seimport { SettingsDropdownInput } from "#/components/features/settings/settings-dropdown-input";import { NavigationLink } from "#/components/shared/navigation-link";import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";+import { useFreeModels } from "#/hooks/query/use-free-models";import { useActiveBackend } from "#/contexts/active-backend-context";import { formatModelNameForDisplay } from "#/utils/format-model-name";@@ -35,6 +36,7 @@ export function AppSettingsScreen() {const isCloudBackend = activeBackend.backend.kind === "cloud";const { data: llmProfiles, isLoading: areLlmProfilesLoading } =useLlmProfiles();+ const freeModels = useFreeModels();const [languageInputHasChanged, setLanguageInputHasChanged] =React.useState(false);@@ -74,12 +76,14 @@ export function AppSettingsScreen() {label: profile.model? t(I18nKey.SETTINGS$TITLE_GENERATION_PROFILE_OPTION, {name: profile.name,- model: formatModelNameForDisplay(profile.model) ?? profile.model,+ model:+ formatModelNameForDisplay(profile.model, freeModels) ??+ profile.model,}): profile.name,})) ?? []),],- [llmProfiles?.profiles, t],+ [llmProfiles?.profiles, freeModels, t],);const formAction = (formData: FormData) => {diff --git a/src/routes/llm-settings.tsx b/src/routes/llm-settings.tsxindex 7206ab17c1..c9990da6ea 100644--- a/src/routes/llm-settings.tsx+++ b/src/routes/llm-settings.tsx@@ -1,5 +1,4 @@import React from "react";-import { Info } from "lucide-react";import { useTranslation } from "react-i18next";import { ModelSelector } from "#/components/shared/modals/settings/model-selector";import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema";@@ -35,11 +34,12 @@ import {import { useOpenAISubscriptionModels } from "#/hooks/query/use-llm-subscription-models";import { useProviderConnections } from "#/hooks/query/use-provider-connections";import { useActiveBackend } from "#/contexts/active-backend-context";+import { useDefaultModel, useFreeModels } from "#/hooks/query/use-free-models";import {- FREE_OPENHANDS_MODEL_NOTE,isFreeOpenHandsModel,isOpenHandsProviderModel,} from "#/utils/format-model-name";+import { FreeOpenHandsModelsNote } from "#/components/shared/free-models-note";/** Form-values key for the shared provider connection a profile links to. */export const LLM_PROVIDER_CONNECTION_KEY = "llm.provider_connection_id";@@ -121,18 +121,6 @@ function OpenHandsApiKeyHelp({ testId }: OpenHandsApiKeyHelpProps) {);}-function OpenHandsFreeModelsNote() {- return (- <p- data-testid="openhands-free-models-note"- className="flex items-start gap-2 text-xs text-warning"- >- <Info className="mt-0.5 size-4 shrink-0 text-warning" aria-hidden />- <span>{FREE_OPENHANDS_MODEL_NOTE}</span>- </p>- );-}-export function LlmSettingsScreen({scope = "personal",onSaveSuccess,@@ -208,10 +196,17 @@ export function LlmSettingsScreen({}}, [initialAuthType]);- const defaultModel = String(- (DEFAULT_SETTINGS.agent_settings?.llm as Record<string, unknown>)?.model ??- "",- );+ const freeModels = useFreeModels();+ const dbDefaultModel = useDefaultModel();++ // Prefer the DB-driven default (cloud) and fall back to the bundled default+ // when the backend exposes none (e.g. the local agent-server).+ const defaultModel =+ dbDefaultModel ??+ String(+ (DEFAULT_SETTINGS.agent_settings?.llm as Record<string, unknown>)+ ?.model ?? "",+ );const getInitialView = React.useCallback((@@ -511,8 +506,8 @@ export function LlmSettingsScreen({{showOpenHandsApiKeyHelp && !isLinkedToConnection ? (<>- {isFreeOpenHandsModel(modelValue) ? (- <OpenHandsFreeModelsNote />+ {isFreeOpenHandsModel(modelValue, freeModels) ? (+ <FreeOpenHandsModelsNote modelIds={freeModels} />) : null}</>) : null}@@ -556,6 +551,7 @@ export function LlmSettingsScreen({defaultModel,embedded,isCloud,+ freeModels,isWaitingForSubscriptionModels,settings?.llm_api_key_set,subscriptionModels,diff --git a/src/stores/free-models-store.ts b/src/stores/free-models-store.tsnew file mode 100644index 0000000000..3aaebb79b5--- /dev/null+++ b/src/stores/free-models-store.ts@@ -0,0 +1,53 @@+import { create } from "zustand";+import type { FreeModelSet } from "#/utils/format-model-name";++interface FreeModelsState {+ /**+ * DB-driven set of free ``provider/model`` ids (the same channel that carries+ * `verified`). Empty on backends without free metadata (e.g. the local+ * agent-server), so consumers uniformly treat "not in set" as paid.+ */+ freeModels: FreeModelSet;+ /** DB-driven default OpenHands model id (``openhands/<model>``), or null. */+ defaultModel: string | null;+ /** True once the backend flags query has settled at least once. */+ defaultModelReady: boolean;+}++interface FreeModelsActions {+ /**+ * Replaces the DB-driven flags. Called once by the app-level hydrator+ * ({@link useHydrateFreeModels}) after the backend model list is fetched, so+ * leaf components can read the flags synchronously via zustand selectors+ * without needing a QueryClientProvider in scope.+ */+ setFlags: (flags: {+ freeModels: FreeModelSet;+ defaultModel: string | null;+ }) => void;+ markDefaultModelReady: () => void;+ resetFlags: () => void;+}++type FreeModelsStore = FreeModelsState & FreeModelsActions;++const EMPTY_FREE_MODELS: FreeModelSet = new Set<string>();++export const useFreeModelsStore = create<FreeModelsStore>()((set) => ({+ freeModels: EMPTY_FREE_MODELS,+ defaultModel: null,+ defaultModelReady: false,+ setFlags: (flags) =>+ set({+ freeModels: flags.freeModels,+ defaultModel: flags.defaultModel,+ defaultModelReady: true,+ }),+ markDefaultModelReady: () => set({ defaultModelReady: true }),+ resetFlags: () =>+ set({+ freeModels: EMPTY_FREE_MODELS,+ defaultModel: null,+ defaultModelReady: false,+ }),+}));diff --git a/src/utils/format-model-name.test.ts b/src/utils/format-model-name.test.tsnew file mode 100644index 0000000000..4e933b9497--- /dev/null+++ b/src/utils/format-model-name.test.ts@@ -0,0 +1,17 @@+import { describe, expect, it } from "vitest";+import { formatModelPillLabel } from "./format-model-name";++describe("formatModelPillLabel", () => {+ it("keeps the pretty OpenHands label without a free suffix unless backend marks it free", () => {+ expect(formatModelPillLabel("openhands/deepseek-v4-flash")).toBe(+ "OpenHands DeepSeek V4 Flash",+ );++ expect(+ formatModelPillLabel(+ "openhands/deepseek-v4-flash",+ new Set(["openhands/deepseek-v4-flash"]),+ ),+ ).toBe("OpenHands DeepSeek V4 Flash (free)");+ });+});diff --git a/src/utils/format-model-name.ts b/src/utils/format-model-name.tsindex 8be17b076f..b2789a73de 100644--- a/src/utils/format-model-name.ts+++ b/src/utils/format-model-name.ts@@ -1,11 +1,28 @@export const FREE_MODEL_BADGE_LABEL = "Free";+/** Suffix appended to a display name for a DB-flagged free OpenHands model. */+export const FREE_MODEL_SUFFIX = " (free)";++/**+ * Static pretty-print labels for OpenHands models known at build time. Free+ * status still comes only from the backend-provided `freeModels` set.+ */export const FREE_OPENHANDS_MODELS = {- "openhands/deepseek-v4-flash": "OpenHands DeepSeek V4 Flash (free)",+ "openhands/deepseek-v4-flash": "OpenHands DeepSeek V4 Flash",} as const;export const FREE_OPENHANDS_MODEL_IDS = Object.keys(FREE_OPENHANDS_MODELS);+/**+ * Set of free ``provider/model`` ids. The frontend no longer hardcodes which+ * OpenHands models are free — the set is sourced from the backend model list+ * (DB-driven), the same channel that carries `verified`. See+ * {@link useFreeModels}. Callers that lack the set treat every model as paid.+ */+export type FreeModelSet = ReadonlySet<string>;++const EMPTY_FREE_MODELS: FreeModelSet = new Set<string>();+/*** Whether a model id routes through the OpenHands provider (the `openhands/`* prefix). On cloud the OpenHands provider is backed by a server-minted LLM@@ -16,31 +33,31 @@ export const isOpenHandsProviderModel = (model: string | null | undefined,): boolean => Boolean(model?.startsWith("openhands/"));-export const FREE_OPENHANDS_MODEL_NOTE = `Free OpenHands models: ${FREE_OPENHANDS_MODEL_IDS.join(- ", ",-)}. Other provider endpoints with similar model names may require separate billing.`;-export const isFreeOpenHandsModel = (model: string | null | undefined,-): model is keyof typeof FREE_OPENHANDS_MODELS =>- Boolean(model && model in FREE_OPENHANDS_MODELS);+ freeModels: FreeModelSet = EMPTY_FREE_MODELS,+): boolean => Boolean(model && freeModels.has(model));++function appendFreeSuffix(display: string, isFree: boolean): string {+ return isFree ? `${display}${FREE_MODEL_SUFFIX}` : display;+}export function formatModelNameForDisplay(model: string | null | undefined,+ freeModels: FreeModelSet = EMPTY_FREE_MODELS,): string | null {if (!model) return null;- return isFreeOpenHandsModel(model) ? FREE_OPENHANDS_MODELS[model] : model;+ return appendFreeSuffix(model, isFreeOpenHandsModel(model, freeModels));}export function formatProviderModelNameForDisplay(provider: string | null | undefined,model: string | null | undefined,+ freeModels: FreeModelSet = EMPTY_FREE_MODELS,): string | null {if (!model) return null;const fullModel = provider ? `${provider}/${model}` : model;- return isFreeOpenHandsModel(fullModel)- ? FREE_OPENHANDS_MODELS[fullModel]- : model;+ return appendFreeSuffix(model, isFreeOpenHandsModel(fullModel, freeModels));}/**@@ -54,14 +71,35 @@ export function formatProviderModelNameForDisplay(* string when stripping the prefix would leave nothing (e.g. a trailing slash)* — never an empty string, which would collapse the chip text.*+ * A DB-flagged free model (matched against ``freeModels`` on its full id) keeps+ * the free suffix so the chip still signals it is free.+ ** Display-only: unlike {@link deriveProfileNameFromModel} this does not sanitize* to an identifier, so it keeps the real model id intact for the chip.*/export function formatNativeModelName(model: string | null | undefined,+ freeModels: FreeModelSet = EMPTY_FREE_MODELS,): string | null {if (!model) return null;- if (isFreeOpenHandsModel(model)) return FREE_OPENHANDS_MODELS[model];+ const isFree = isFreeOpenHandsModel(model, freeModels);const lastSegment = model.split("/").pop();- return lastSegment || model;+ return appendFreeSuffix(lastSegment || model, isFree);+}++/**+ * Display label used by the LLM-profile picker sub-line. Looks up the model in+ * the static label table for a prettier name, but appends `(free)` only when the+ * backend-provided `freeModels` set marks the concrete model free.+ */+export function formatModelPillLabel(+ model: string | null | undefined,+ freeModels: FreeModelSet = EMPTY_FREE_MODELS,+): string | null {+ if (!model) return null;+ const display =+ model in FREE_OPENHANDS_MODELS+ ? FREE_OPENHANDS_MODELS[model as keyof typeof FREE_OPENHANDS_MODELS]+ : model;+ return appendFreeSuffix(display, isFreeOpenHandsModel(model, freeModels));}