Skip to content

🙌 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.tsx
index 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.tsx
index 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.tsx
index 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(
<ConversationCard
title="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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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-pr
import * 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.tsx
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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 (
<ContextMenuListItem
key={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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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-profile
import { 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.tsx
index 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 (
<div
diff --git a/src/components/providers/agent-server-ui-providers.tsx b/src/components/providers/agent-server-ui-providers.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.tsx
index 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-se
import { 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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));
}