π OpenHands: AI-Driven Development
fix: preserve canonical LLM settings during onboarding (#17211)
Graham Neubig505ff3c7a7ab
diff --git a/__tests__/components/onboarding/setup-llm-step.test.tsx b/__tests__/components/onboarding/setup-llm-step.test.tsxnew file mode 100644index 0000000000..403209877d--- /dev/null+++ b/__tests__/components/onboarding/setup-llm-step.test.tsx@@ -0,0 +1,173 @@+import { screen, waitFor } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { SetupLlmStep } from "#/components/features/onboarding/steps/setup-llm-step";+import type { SdkSectionSaveControl } from "#/components/features/settings/sdk-settings/sdk-section-page";+import { renderWithProviders } from "../../../test-utils";++const saveProfile = vi.hoisted(() => vi.fn());+const activateProfile = vi.hoisted(() => vi.fn());+const applyAgentProfile = vi.hoisted(() => vi.fn());+const displayErrorToast = vi.hoisted(() => vi.fn());+let finishSettingsSave: (() => void) | undefined;+const formState = vi.hoisted(() => ({+ llm: {} as Record<string, unknown>,+}));++vi.mock("#/contexts/active-backend-context", () => ({+ useActiveBackend: () => ({ backend: { kind: "local" } }),+}));++vi.mock("#/hooks/mutation/use-save-llm-profile", () => ({+ useSaveLlmProfile: () => ({ mutateAsync: saveProfile }),+}));++vi.mock("#/hooks/mutation/use-activate-llm-profile", () => ({+ useActivateLlmProfile: () => ({ mutateAsync: activateProfile }),+}));++vi.mock("#/hooks/mutation/use-apply-onboarding-agent-profile", () => ({+ useApplyOnboardingAgentProfile: () => applyAgentProfile,+}));++vi.mock("#/hooks/query/use-free-models", () => ({+ useDefaultModel: () => null,+ useDefaultModelReady: () => true,+}));++vi.mock("#/utils/custom-toast-handlers", () => ({+ displayErrorToast,+}));++vi.mock("#/routes/llm-settings", async () => {+ const React = await import("react");+ return {+ LlmSettingsScreen: ({+ onSaveControlChange,+ onSaveSuccess,+ }: {+ onSaveControlChange: (control: SdkSectionSaveControl) => void;+ onSaveSuccess: () => void;+ }) => {+ const canonicalLlm = formState.llm;+ finishSettingsSave = onSaveSuccess;+ React.useEffect(() => {+ const buildControl = (isDirty: boolean): SdkSectionSaveControl => ({+ save: () => {+ onSaveControlChange(buildControl(false));+ finishSettingsSave?.();+ },+ isSaving: false,+ isDirty,+ values: Object.fromEntries(+ Object.entries(canonicalLlm).map(([key, value]) => [+ `llm.${key}`,+ String(value),+ ]),+ ),+ view: "basic",+ getDirtyPayload: () => ({ llm: canonicalLlm }),+ getSavePayload: () => ({+ agent_settings_diff: { llm: canonicalLlm },+ }),+ });+ onSaveControlChange(buildControl(true));+ }, [onSaveControlChange]);+ return <div data-testid="llm-settings-screen" />;+ },+ };+});++describe("SetupLlmStep", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ formState.llm = {+ model: "gpt-5.6-luna",+ auth_type: "subscription",+ subscription_vendor: "openai",+ temperature: 0.2,+ };+ finishSettingsSave = undefined;+ saveProfile.mockResolvedValue(undefined);+ activateProfile.mockResolvedValue(undefined);+ applyAgentProfile.mockResolvedValue(undefined);+ });++ it("persists and activates the canonically serialized subscription profile", async () => {+ const onNext = vi.fn();+ renderWithProviders(<SetupLlmStep onBack={vi.fn()} onNext={onNext} />);++ await userEvent.click(await screen.findByTestId("onboarding-llm-next"));++ await waitFor(() => {+ expect(saveProfile).toHaveBeenCalledWith({+ name: "gpt-5.6-luna",+ request: {+ llm: {+ model: "gpt-5.6-luna",+ auth_type: "subscription",+ subscription_vendor: "openai",+ temperature: 0.2,+ },+ include_secrets: true,+ },+ });+ });+ expect(activateProfile).toHaveBeenCalledWith("gpt-5.6-luna");+ expect(applyAgentProfile).toHaveBeenCalledWith({+ agent_kind: "openhands",+ llm_profile_ref: "gpt-5.6-luna",+ });+ expect(onNext).toHaveBeenCalledTimes(1);+ });++ it("preserves typed advanced options when creating the activated profile", async () => {+ formState.llm = {+ model: "openai/gpt-4o-mini",+ api_key: "test-key",+ base_url: "http://localhost:19118/v1",+ timeout: 3,+ num_retries: 1,+ retry_min_wait: 0,+ retry_max_wait: 0,+ stream: true,+ };+ const onNext = vi.fn();+ renderWithProviders(<SetupLlmStep onBack={vi.fn()} onNext={onNext} />);++ await userEvent.click(await screen.findByTestId("onboarding-llm-next"));++ await waitFor(() => {+ expect(saveProfile).toHaveBeenCalledWith({+ name: "gpt-4o-mini",+ request: { llm: formState.llm, include_secrets: true },+ });+ });+ expect(activateProfile).toHaveBeenCalledWith("gpt-4o-mini");+ expect(applyAgentProfile).toHaveBeenCalledWith({+ agent_kind: "openhands",+ llm_profile_ref: "gpt-4o-mini",+ });+ expect(onNext).toHaveBeenCalledTimes(1);+ });++ it.each([+ ["profile save", saveProfile],+ ["profile activation", activateProfile],+ ])("does not advance when %s fails", async (_label, failingMutation) => {+ failingMutation.mockRejectedValueOnce(new Error("profile unavailable"));+ const onNext = vi.fn();+ renderWithProviders(<SetupLlmStep onBack={vi.fn()} onNext={onNext} />);++ await userEvent.click(await screen.findByTestId("onboarding-llm-next"));++ await waitFor(() => expect(displayErrorToast).toHaveBeenCalled());+ expect(onNext).not.toHaveBeenCalled();+ expect(applyAgentProfile).not.toHaveBeenCalled();+ const nextButton = screen.getByTestId("onboarding-llm-next");+ expect(nextButton).toBeEnabled();++ await userEvent.click(nextButton);+ await waitFor(() => expect(onNext).toHaveBeenCalledTimes(1));+ });+});diff --git a/__tests__/routes/llm-settings.test.tsx b/__tests__/routes/llm-settings.test.tsxindex db431b6035..dbe378d01a 100644--- a/__tests__/routes/llm-settings.test.tsx+++ b/__tests__/routes/llm-settings.test.tsx@@ -24,6 +24,7 @@ import LLMSubscriptionService from "#/api/llm-subscription-service";import ProviderConnectionsService, {type ProviderConnection,} from "#/api/provider-connections-service/provider-connections-service.api";+import type { SdkSectionSaveControl } from "#/components/features/settings/sdk-settings/sdk-section-page";vi.mock("#/hooks/query/use-llm-profiles");// The profile manager gates mutate controls on this hook; default to a user@@ -253,6 +254,53 @@ describe("LlmSettingsScreen", () => {expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();});+ it("exposes canonical subscription metadata through the save control", async () => {+ vi.spyOn(LLMSubscriptionService, "getOpenAIStatus").mockResolvedValue({+ vendor: "openai",+ connected: true,+ accountEmail: "[email protected]",+ expiresAt: null,+ });+ vi.spyOn(LLMSubscriptionService, "getOpenAIModels").mockResolvedValue([+ "gpt-5.6-luna",+ ]);+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({+ llm_model: "gpt-5.6-luna",+ agent_settings: {+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,+ llm: {+ model: "gpt-5.6-luna",+ auth_type: "subscription",+ subscription_vendor: "openai",+ },+ },+ }),+ );+ const saveControlRef: { current: SdkSectionSaveControl | null } = {+ current: null,+ };++ renderLlmSettingsScreen({+ onSaveControlChange: (control) => {+ saveControlRef.current = control;+ },+ });++ await screen.findByTestId("llm-subscription-settings");+ await waitFor(() => expect(saveControlRef.current).not.toBeNull());+ expect(saveControlRef.current?.getSavePayload()).toEqual({+ agent_settings_diff: {+ llm: {+ auth_type: "subscription",+ model: "gpt-5.6-luna",+ subscription_vendor: "openai",+ temperature: null,+ },+ },+ });+ });+it("disables subscription model controls while models are loading", async () => {vi.spyOn(LLMSubscriptionService, "getOpenAIStatus").mockResolvedValue({vendor: "openai",diff --git a/__tests__/vitest-setup-progress-event.test.ts b/__tests__/vitest-setup-progress-event.test.tsindex 2d7fe3c90f..27f52757d4 100644--- a/__tests__/vitest-setup-progress-event.test.ts+++ b/__tests__/vitest-setup-progress-event.test.ts@@ -60,3 +60,28 @@ describe("ProgressEvent fallback in vitest.setup.ts", () => {expect("ProgressEvent" in {}).toBe(false);});});++describe("XMLHttpRequestUpload fallback in vitest.setup.ts", () => {+ it("resolves the bare identifier after teardown deletes the own property", () => {+ const live = Object.getOwnPropertyDescriptor(+ globalThis,+ "XMLHttpRequestUpload",+ );+ expect(live).toBeDefined();++ delete (globalThis as { XMLHttpRequestUpload?: unknown })+ .XMLHttpRequestUpload;++ try {+ expect(typeof XMLHttpRequestUpload).toBe("function");+ } finally {+ if (live) {+ Object.defineProperty(globalThis, "XMLHttpRequestUpload", live);+ }+ }+ });++ it("does not add XMLHttpRequestUpload to plain objects", () => {+ expect("XMLHttpRequestUpload" in {}).toBe(false);+ });+});diff --git a/src/components/features/onboarding/steps/setup-llm-step.tsx b/src/components/features/onboarding/steps/setup-llm-step.tsxindex d3d6528e73..0f06d5a3f2 100644--- a/src/components/features/onboarding/steps/setup-llm-step.tsx+++ b/src/components/features/onboarding/steps/setup-llm-step.tsx@@ -14,6 +14,8 @@ import {} 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";+import type { SaveProfileRequest } from "#/api/profiles-service/profiles-service.api";+import { displayErrorToast } from "#/utils/custom-toast-handlers";interface SetupLlmStepProps {onBack: () => void;@@ -57,6 +59,11 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {const [saveControl, setSaveControl] =React.useState<SdkSectionSaveControl | null>(null);const [isFinalizing, setIsFinalizing] = React.useState(false);+ const [hasFinalizationError, setHasFinalizationError] = React.useState(false);+ const profileDraftRef = React.useRef<{+ name: string;+ llm: SaveProfileRequest["llm"];+ } | null>(null);// On local backends the LLM profiles list is the user-facing source of// truth; without this step the form save only updates agent_settings and@@ -68,39 +75,34 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {string | null> => {if (!isLocalBackend || !saveControl) return null;- const values = saveControl.values;- const model =- typeof values["llm.model"] === "string" ? values["llm.model"] : "";- if (!model) return null;- const apiKey =- typeof values["llm.api_key"] === "string" ? values["llm.api_key"] : "";- const baseUrl =- typeof values["llm.base_url"] === "string" ? values["llm.base_url"] : "";- const name = deriveProfileNameFromModel(model);- const llmConfig: { model: string; api_key?: string; base_url?: string } = {- model,- };- if (apiKey) llmConfig.api_key = apiKey;- if (baseUrl) llmConfig.base_url = baseUrl;-- try {- await saveProfile.mutateAsync({- name,- request: { llm: llmConfig, include_secrets: true },- });- await activateProfile.mutateAsync(name);- return name;- } catch (error) {- // Best-effort: the agent_settings save already succeeded, so the- // user is not blocked from completing onboarding.- console.error("Failed to persist onboarding LLM as profile:", error);- return null;+ let profileDraft = profileDraftRef.current;+ if (!profileDraft) {+ const payload = saveControl.getSavePayload();+ const agentSettings = payload.agent_settings_diff;+ if (!agentSettings || typeof agentSettings !== "object") return null;+ const llmConfig = (agentSettings as Record<string, unknown>).llm;+ if (!llmConfig || typeof llmConfig !== "object") return null;+ const model = (llmConfig as Record<string, unknown>).model;+ if (typeof model !== "string" || !model) return null;+ profileDraft = {+ name: deriveProfileNameFromModel(model),+ llm: llmConfig as SaveProfileRequest["llm"],+ };+ profileDraftRef.current = profileDraft;}++ await saveProfile.mutateAsync({+ name: profileDraft.name,+ request: { llm: profileDraft.llm, include_secrets: true },+ });+ await activateProfile.mutateAsync(profileDraft.name);+ return profileDraft.name;}, [isLocalBackend, saveControl, saveProfile, activateProfile]);const handleSaveSuccess = React.useCallback(async () => {setIsFinalizing(true);+ setHasFinalizationError(false);try {const llmProfileName = await persistAsProfile();// Point the active AGENT profile at the LLM the user just configured so@@ -121,19 +123,29 @@ export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {llm_profile_ref: llmProfileName,});}+ profileDraftRef.current = null;+ onNext();+ } catch {+ setHasFinalizationError(true);+ displayErrorToast(t(I18nKey.ERROR$GENERIC));} finally {setIsFinalizing(false);- onNext();}- }, [persistAsProfile, applyAgentProfile, onNext]);+ }, [persistAsProfile, applyAgentProfile, onNext, t]);const handleNext = () => {if (saveControl?.isDirty) {+ profileDraftRef.current = null;+ setHasFinalizationError(false);saveControl.save();// `onSaveSuccess` (wired to `handleSaveSuccess` below) will advance// once the mutation resolves successfully.return;}+ if (hasFinalizationError) {+ void handleSaveSuccess();+ return;+ }onNext();};diff --git a/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/src/components/features/settings/sdk-settings/sdk-section-page.tsxindex ff2a08daf3..c53b3e8428 100644--- a/src/components/features/settings/sdk-settings/sdk-section-page.tsx+++ b/src/components/features/settings/sdk-settings/sdk-section-page.tsx@@ -158,6 +158,11 @@ export interface SdkSectionSaveControl {values: SettingsFormValues;/** The active view tier (basic/advanced/all) the form is rendering. */view: SettingsView;+ /**+ * Returns the exact payload the built-in save action sends, including any+ * feature-specific canonicalization supplied through `buildPayload`.+ */+ getSavePayload: () => Record<string, unknown>;/*** Returns the coerced, dirty-only payload as a nested object* (e.g. `{ llm: { temperature: 0.7 } }`). Lets a custom save flow persist@@ -579,9 +584,15 @@ export function SdkSectionPage({handleSaveRef.current();}, []);- // Stable accessor for the coerced, dirty-only payload. Mirrors the- // `handleSaveRef` pattern so the exposed function reference stays stable- // across renders while always reading the latest closure at call time.+ // Stable payload accessors mirror `handleSaveRef`: consumers keep stable+ // function identities while each call reads the latest form closure.+ const buildSavePayloadRef = React.useRef<() => Record<string, unknown>>(+ () => ({}),+ );+ const stableGetSavePayload = React.useCallback(+ () => buildSavePayloadRef.current(),+ [],+ );const buildDirtyPayloadRef = React.useRef<() => Record<string, unknown>>(() => ({}),);@@ -590,41 +601,45 @@ export function SdkSectionPage({[],);+ buildSavePayloadRef.current = () => {+ const defaultPayload: Record<string, unknown> = {};+ for (const src of resolvedSources) {+ if (!src.filteredSchema) continue;+ const sourceValues = valuesBySource[src.settingsSource] ?? {};+ const sourceDirty = dirtyBySource[src.settingsSource] ?? {};+ const diff = buildSdkSettingsPayloadForView(+ src.filteredSchema,+ sourceValues,+ sourceDirty,+ view,+ );+ if (Object.keys(diff).length > 0) {+ const diffKey = PAYLOAD_DIFF_KEY[src.settingsSource];+ defaultPayload[diffKey] = {+ ...((defaultPayload[diffKey] as+ | Record<string, unknown>+ | undefined) ?? {}),+ ...diff,+ };+ }+ }++ return buildPayload+ ? buildPayload(defaultPayload, {+ values: flatValues,+ dirty: flatDirty,+ view,+ })+ : defaultPayload;+ };+const handleSave = () => {if (isReadOnly) return;if (resolvedSources.some((src) => !src.filteredSchema)) return;let payload: Record<string, unknown>;try {- const defaultPayload: Record<string, unknown> = {};- for (const src of resolvedSources) {- const schema = src.filteredSchema!;- const sourceValues = valuesBySource[src.settingsSource] ?? {};- const sourceDirty = dirtyBySource[src.settingsSource] ?? {};- const diff = buildSdkSettingsPayloadForView(- schema,- sourceValues,- sourceDirty,- view,- );- if (Object.keys(diff).length > 0) {- const diffKey = PAYLOAD_DIFF_KEY[src.settingsSource];- defaultPayload[diffKey] = {- ...((defaultPayload[diffKey] as- | Record<string, unknown>- | undefined) ?? {}),- ...diff,- };- }- }-- payload = buildPayload- ? buildPayload(defaultPayload, {- values: flatValues,- dirty: flatDirty,- view,- })- : defaultPayload;+ payload = stableGetSavePayload();} catch (error) {displayErrorToast(error instanceof Error ? error.message : t(I18nKey.ERROR$GENERIC),@@ -677,6 +692,7 @@ export function SdkSectionPage({isDirty: saveControlIsDirty,values: flatValues,view,+ getSavePayload: stableGetSavePayload,getDirtyPayload: stableGetDirtyPayload,});}, [isPending, saveControlIsDirty, flatValues, view]);diff --git a/tests/e2e/support/onboarding-helpers.ts b/tests/e2e/support/onboarding-helpers.tsindex 28023096bf..59e8624786 100644--- a/tests/e2e/support/onboarding-helpers.ts+++ b/tests/e2e/support/onboarding-helpers.ts@@ -64,6 +64,19 @@ export async function showOnboarding(page: Page,{ apiKey, beforeGoto }: ShowOnboardingOptions,) {+ const consentResponse = await page.request.patch("/api/settings", {+ headers: { "X-Session-API-Key": apiKey },+ data: {+ misc_settings_diff: {+ app_preferences: { user_consents_to_analytics: false },+ },+ },+ });+ expect(+ consentResponse.ok(),+ `failed to seed backend analytics consent: ${consentResponse.status()}`,+ ).toBe(true);+await page.addInitScript(({ apiKey: initApiKey }) => {window.localStorage.removeItem("openhands-onboarded");