Skip to content

πŸ™Œ 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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");