🙌 OpenHands: AI-Driven Development
Add multi-step onboarding modal (#257)
Robert Brennan8482aeda2690
diff --git a/AGENTS.md b/AGENTS.mdindex 7de09980a8..e573e4ab91 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -178,3 +178,5 @@- Backend dropdown connectivity indicator: `useBackendsHealth` (`src/hooks/query/use-backends-health.ts`) polls each registered backend every 10s. Local agent-server backends are probed via `ServerClient.getServerInfo()` (`/server_info`); cloud SaaS backends are probed via `getCurrentCloudApiKey()` (`/api/keys/current` through the bundled `/api/cloud-proxy`). Verdicts are surfaced as a colored dot rendered through `DropdownOption.prefix` (added to `src/ui/dropdown/types.ts`); the trigger reads its prefix from the live `options` array (not downshift's frozen `selectedItem`) so the indicator updates without remounting. The same dot is also rendered in each row of `ManageBackendsModal`. Tests live in `__tests__/hooks/query/use-backends-health.test.tsx`, the `connection indicator` block of `__tests__/components/backends/backend-selector.test.tsx`, and `__tests__/components/backends/manage-backends-modal.test.tsx`.- Manage Backends modal: `src/components/features/backends/manage-backends-modal.tsx` lets users edit (host/name/api-key/kind) and remove existing backends, plus add new ones inline via a "+ Add Backend" footer button that opens a `BackendFormModal`. Both the dropdown footer's "Add backend" and the manage modal's "+ Add Backend" reuse `BackendFormModal` (see `backend-form-modal.tsx`), with `mode="add"` or `mode="edit"`; `AddBackendModal` is now a thin compatibility wrapper for `BackendFormModal mode="add"`. The modal is also auto-rendered (with a no-op `onClose`) by `src/root.tsx` when the active backend is unreachable, replacing the old full-screen `MissingAgentServerNotice` onboarding screen.++- Onboarding modal: `src/components/features/onboarding/onboarding-modal.tsx` is a 4-step welcome flow rendered by `<OnboardingHost />` (mounted on the home route) and gated by the `openhands-onboarded` localStorage flag (`use-onboarding-completion.ts`). The four steps live under `steps/`: choose-agent (Step 0 – OpenHands selectable, Claude Code & Codex disabled with a "coming soon" note), check-backend (embeds the new `BackendForm` extracted from `backend-form-modal.tsx` plus a colored connection banner driven by `useBackendsHealth`), setup-llm (renders `<LlmSettingsScreen onSaveSuccess={onNext} />` so the existing settings UI keeps owning validation), and say-hello (text input pre-filled from `ONBOARDING$HELLO_DEFAULT_MESSAGE`, launches a no-workspace conversation via `useCreateConversation` and closes the modal). Animation: all four panels are mounted as siblings inside a horizontal rail; advancing/retreating just sets `currentStep`, which translates the rail by `-(step * 100)%` for the slide effect. Progress is rendered by `OnboardingProgressBar` with `data-state` per segment (`completed` | `current` | `upcoming`). When extending, refactor `BackendFormModal` carefully — the inner `BackendForm` is the public surface used both by the modal and by `CheckBackendStep`; the modal version still owns dirty/save tracking so it keeps "Save"/"Cancel" footer behavior.diff --git a/__tests__/components/onboarding/choose-agent-step.test.tsx b/__tests__/components/onboarding/choose-agent-step.test.tsxnew file mode 100644index 0000000000..99dff24189--- /dev/null+++ b/__tests__/components/onboarding/choose-agent-step.test.tsx@@ -0,0 +1,73 @@+import React from "react";+import { render, screen } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { describe, expect, it, vi } from "vitest";+import {+ ChooseAgentStep,+ type OnboardingAgentId,+} from "#/components/features/onboarding/steps/choose-agent-step";++function renderStep(initial: OnboardingAgentId = "openhands") {+ const onSelect = vi.fn();+ const onNext = vi.fn();+ render(+ <ChooseAgentStep+ selectedAgentId={initial}+ onSelect={onSelect}+ onNext={onNext}+ />,+ );+ return { onSelect, onNext };+}++describe("ChooseAgentStep", () => {+ it("renders the three agent options with OpenHands marked selected", () => {+ renderStep();++ const openhands = screen.getByTestId("onboarding-agent-option-openhands");+ const claude = screen.getByTestId("onboarding-agent-option-claude-code");+ const codex = screen.getByTestId("onboarding-agent-option-codex");++ expect(openhands).toHaveAttribute("aria-checked", "true");+ expect(openhands).not.toBeDisabled();++ // Claude Code and Codex are visible but disabled / coming-soon.+ expect(claude).toBeDisabled();+ expect(claude).toHaveAttribute("aria-disabled", "true");+ expect(codex).toBeDisabled();+ expect(codex).toHaveAttribute("aria-disabled", "true");++ // The "coming soon" note is rendered.+ expect(+ screen.getByTestId("onboarding-agent-coming-soon"),+ ).toBeInTheDocument();+ });++ it("ignores clicks on the disabled agent options", async () => {+ const { onSelect } = renderStep();+ const user = userEvent.setup();++ await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));+ await user.click(screen.getByTestId("onboarding-agent-option-codex"));++ expect(onSelect).not.toHaveBeenCalled();+ });++ it("invokes onSelect when the OpenHands option is clicked", async () => {+ const { onSelect } = renderStep();+ const user = userEvent.setup();++ await user.click(screen.getByTestId("onboarding-agent-option-openhands"));++ expect(onSelect).toHaveBeenCalledWith("openhands");+ });++ it("invokes onNext when the Next button is clicked", async () => {+ const { onNext } = renderStep();+ const user = userEvent.setup();++ await user.click(screen.getByTestId("onboarding-agent-next"));++ expect(onNext).toHaveBeenCalledTimes(1);+ });+});diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsxnew file mode 100644index 0000000000..d2aac10f74--- /dev/null+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx@@ -0,0 +1,210 @@+import React from "react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { render, screen, waitFor } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";+import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import { OnboardingModal } from "#/components/features/onboarding/onboarding-modal";+import { NavigationProvider } from "#/context/navigation-context";++// Both the backend status badge in the embedded edit form and the+// step-1 health probe ride on `useBackendsHealth`, which itself+// resolves through these two clients.+vi.mock("#/api/typescript-client", () => ({+ createServerClient: vi.fn(() => ({+ getServerInfo: vi.fn().mockResolvedValue({ version: "1.18.0" }),+ })),+}));++vi.mock("#/api/cloud/organization-service.api", () => ({+ getCurrentCloudApiKey: vi.fn().mockResolvedValue({+ orgId: null,+ isLegacyKey: true,+ }),+}));++// The LLM step renders the full `LlmSettingsScreen`, which transitively+// pulls in agent-server config + schema queries we don't need to+// exercise here. Stub it to a marker so we can still verify the LLM+// step is mounted.+vi.mock("#/routes/llm-settings", () => ({+ LlmSettingsScreen: () => (+ <div data-testid="llm-settings-screen-stub">llm settings</div>+ ),+}));++vi.mock("#/hooks/use-is-creating-conversation", () => ({+ useIsCreatingConversation: () => false,+}));++vi.mock("#/hooks/mutation/use-create-conversation", () => ({+ useCreateConversation: () => ({+ mutate: vi.fn(),+ isPending: false,+ isSuccess: false,+ }),+}));++function renderModal(onClose = vi.fn()) {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ const navigationValue = {+ currentPath: "/",+ conversationId: null,+ isNavigating: false,+ navigate: vi.fn(),+ };+ return render(+ <QueryClientProvider client={queryClient}>+ <ActiveBackendProvider>+ <NavigationProvider value={navigationValue}>+ <OnboardingModal onClose={onClose} />+ </NavigationProvider>+ </ActiveBackendProvider>+ </QueryClientProvider>,+ );+}++beforeEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+});+afterEach(() => {+ window.localStorage.clear();+ __resetActiveStoreForTests();+});++describe("OnboardingModal", () => {+ it("starts on the Choose Agent step with each slide offset by its index", () => {+ renderModal();++ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(+ "data-current-step",+ "0",+ );+ expect(+ screen.getByTestId("onboarding-step-choose-agent"),+ ).toBeInTheDocument();++ // Active slide sits at offset 0; later slides are translated 100%+ // per index away to the right and absolute-positioned so they+ // don't bleed into the modal box.+ expect(screen.getByTestId("onboarding-slide-0")).toHaveAttribute(+ "data-active",+ "true",+ );+ expect(+ screen.getByTestId("onboarding-slide-0").style.transform,+ ).toBe("translateX(0%)");+ expect(+ screen.getByTestId("onboarding-slide-1").style.transform,+ ).toBe("translateX(100%)");+ expect(+ screen.getByTestId("onboarding-slide-2").style.transform,+ ).toBe("translateX(200%)");+ expect(+ screen.getByTestId("onboarding-slide-3").style.transform,+ ).toBe("translateX(300%)");++ // Progress bar reflects step 1 of 4.+ expect(+ screen.getByTestId("onboarding-progress-step-0"),+ ).toHaveAttribute("data-state", "current");+ expect(+ screen.getByTestId("onboarding-progress-step-1"),+ ).toHaveAttribute("data-state", "upcoming");+ });++ it("advances each step via the per-step Next button and reframes slide offsets", async () => {+ renderModal();+ const user = userEvent.setup();++ // Step 0 → 1+ await user.click(screen.getByTestId("onboarding-agent-next"));+ await waitFor(() =>+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(+ "data-current-step",+ "1",+ ),+ );+ expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(+ "data-active",+ "true",+ );+ expect(+ screen.getByTestId("onboarding-slide-0").style.transform,+ ).toBe("translateX(-100%)");+ expect(+ screen.getByTestId("onboarding-slide-1").style.transform,+ ).toBe("translateX(0%)");+ expect(+ screen.getByTestId("onboarding-slide-2").style.transform,+ ).toBe("translateX(100%)");++ // Once the backend health probe resolves, step 1's Next is enabled.+ await waitFor(() =>+ expect(+ screen.getByTestId("onboarding-backend-next"),+ ).not.toBeDisabled(),+ );+ await user.click(screen.getByTestId("onboarding-backend-next"));+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(+ "data-current-step",+ "2",+ );+ expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(+ "data-active",+ "true",+ );++ // Step 2 → 3+ await user.click(screen.getByTestId("onboarding-llm-next"));+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(+ "data-current-step",+ "3",+ );+ expect(screen.getByTestId("onboarding-slide-3")).toHaveAttribute(+ "data-active",+ "true",+ );+ expect(+ screen.getByTestId("onboarding-slide-3").style.transform,+ ).toBe("translateX(0%)");+ });++ it("Skip immediately closes the modal", async () => {+ const onClose = vi.fn();+ renderModal(onClose);++ const user = userEvent.setup();+ await user.click(screen.getByTestId("onboarding-skip"));++ expect(onClose).toHaveBeenCalledTimes(1);+ });++ it("pre-fills the say-hello input with the default greeting on step 3", async () => {+ renderModal();+ const user = userEvent.setup();++ await user.click(screen.getByTestId("onboarding-agent-next"));+ await waitFor(() =>+ expect(+ screen.getByTestId("onboarding-backend-next"),+ ).not.toBeDisabled(),+ );+ await user.click(screen.getByTestId("onboarding-backend-next"));+ await user.click(screen.getByTestId("onboarding-llm-next"));++ const helloInput = screen.getByTestId(+ "onboarding-hello-input",+ ) as HTMLInputElement;+ // Translation is mocked to return the key; the default-message+ // hook still pre-fills with whatever t() returns, which here is+ // the I18nKey itself. The contract under test is that the input+ // is non-empty and matches the resolved default message.+ expect(helloInput.value).toBe("ONBOARDING$HELLO_DEFAULT_MESSAGE");+ });+});diff --git a/__tests__/components/onboarding/onboarding-progress-bar.test.tsx b/__tests__/components/onboarding/onboarding-progress-bar.test.tsxnew file mode 100644index 0000000000..adf19a181f--- /dev/null+++ b/__tests__/components/onboarding/onboarding-progress-bar.test.tsx@@ -0,0 +1,42 @@+import { render, screen } from "@testing-library/react";+import { describe, expect, it } from "vitest";+import { OnboardingProgressBar } from "#/components/features/onboarding/onboarding-progress-bar";++describe("OnboardingProgressBar", () => {+ it("renders one segment per step and marks the current segment", () => {+ render(<OnboardingProgressBar currentStep={1} totalSteps={4} />);++ const bar = screen.getByTestId("onboarding-progress-bar");+ expect(bar).toHaveAttribute("aria-valuenow", "2");+ expect(bar).toHaveAttribute("aria-valuemin", "1");+ expect(bar).toHaveAttribute("aria-valuemax", "4");++ // Segment states match the current step.+ expect(+ screen.getByTestId("onboarding-progress-step-0"),+ ).toHaveAttribute("data-state", "completed");+ expect(+ screen.getByTestId("onboarding-progress-step-1"),+ ).toHaveAttribute("data-state", "current");+ expect(+ screen.getByTestId("onboarding-progress-step-2"),+ ).toHaveAttribute("data-state", "upcoming");+ expect(+ screen.getByTestId("onboarding-progress-step-3"),+ ).toHaveAttribute("data-state", "upcoming");+ });++ it("treats the first step as current with no completed segments", () => {+ render(<OnboardingProgressBar currentStep={0} totalSteps={3} />);++ expect(+ screen.getByTestId("onboarding-progress-step-0"),+ ).toHaveAttribute("data-state", "current");+ expect(+ screen.getByTestId("onboarding-progress-step-1"),+ ).toHaveAttribute("data-state", "upcoming");+ expect(+ screen.getByTestId("onboarding-progress-step-2"),+ ).toHaveAttribute("data-state", "upcoming");+ });+});diff --git a/__tests__/components/onboarding/use-onboarding-completion.test.tsx b/__tests__/components/onboarding/use-onboarding-completion.test.tsxnew file mode 100644index 0000000000..26184f80ea--- /dev/null+++ b/__tests__/components/onboarding/use-onboarding-completion.test.tsx@@ -0,0 +1,58 @@+import React from "react";+import { act, renderHook } from "@testing-library/react";+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import {+ ONBOARDING_COMPLETED_STORAGE_KEY,+ useOnboardingCompletion,+} from "#/components/features/onboarding/use-onboarding-completion";++beforeEach(() => {+ window.localStorage.clear();+});+afterEach(() => {+ window.localStorage.clear();+});++describe("useOnboardingCompletion", () => {+ it("starts incomplete when the localStorage flag is missing", () => {+ const { result } = renderHook(() => useOnboardingCompletion());+ expect(result.current.isCompleted).toBe(false);+ });++ it("starts complete when the localStorage flag is set", () => {+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");+ const { result } = renderHook(() => useOnboardingCompletion());+ expect(result.current.isCompleted).toBe(true);+ });++ it("persists completion to localStorage and flips the flag", () => {+ const { result } = renderHook(() => useOnboardingCompletion());+ expect(result.current.isCompleted).toBe(false);++ act(() => {+ result.current.markCompleted();+ });++ expect(result.current.isCompleted).toBe(true);+ expect(+ window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),+ ).not.toBeNull();+ });++ it("syncs across tabs via the storage event", () => {+ const { result } = renderHook(() => useOnboardingCompletion());+ expect(result.current.isCompleted).toBe(false);++ act(() => {+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");+ window.dispatchEvent(+ new StorageEvent("storage", {+ key: ONBOARDING_COMPLETED_STORAGE_KEY,+ newValue: "1",+ }),+ );+ });++ expect(result.current.isCompleted).toBe(true);+ });+});diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsxindex 0fb5411930..7057d4b466 100644--- a/src/components/features/backends/backend-form-modal.tsx+++ b/src/components/features/backends/backend-form-modal.tsx@@ -1,11 +1,15 @@import React from "react";+import { useQuery } from "@tanstack/react-query";import { useTranslation } from "react-i18next";import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";import { BrandButton } from "#/components/features/settings/brand-button";import { SettingsInput } from "#/components/features/settings/settings-input";import { useActiveBackendContext } from "#/contexts/active-backend-context";+import { useBackendsHealth } from "#/hooks/query/use-backends-health";+import { createServerClient } from "#/api/typescript-client";import { I18nKey } from "#/i18n/declaration";import type { Backend, BackendKind } from "#/api/backend-registry/types";+import { BackendStatusDot } from "./backend-status-dot";export type BackendFormMode = "add" | "edit";@@ -32,15 +36,116 @@ function normalizeHost(host: string): string {}/**- * Single form used for both adding a new backend and editing an- * existing one. The shape of `Backend` is identical in both cases — the- * only difference is whether we call `addBackend` or `updateBackend`.+ * Live status row for the edit form: shows a connection dot, a+ * "Local"/"Cloud" label, and the agent server's reported version when+ * available. Replaces the legacy local/cloud radio fieldset (kind is+ * now inferred from the host).*/-export function BackendFormModal({+function BackendStatusBadge({+ backend,+ testIdRoot,+}: {+ backend: Backend;+ testIdRoot: string;+}) {+ const { t } = useTranslation("openhands");+ const healthByBackendId = useBackendsHealth([backend]);+ const isConnected = healthByBackendId[backend.id]?.isConnected ?? null;++ const { data: version } = useQuery({+ queryKey: ["backend-version", backend.host, backend.apiKey],+ queryFn: async () => {+ const info = await createServerClient({+ host: backend.host,+ sessionApiKey: backend.apiKey || null,+ timeout: 5000,+ }).getServerInfo();+ return info.version ?? null;+ },+ retry: false,+ staleTime: 60_000,+ enabled: backend.kind === "local",+ });++ let statusLabel: string;+ if (isConnected === true) {+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_CONNECTED);+ } else if (isConnected === false) {+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_DISCONNECTED);+ } else {+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING);+ }++ const kindLabel =+ backend.kind === "cloud"+ ? t(I18nKey.BACKEND$KIND_CLOUD)+ : t(I18nKey.BACKEND$KIND_LOCAL);++ return (+ <div+ data-testid={`${testIdRoot}-status`}+ className="flex items-center gap-3 text-sm"+ >+ <BackendStatusDot isConnected={isConnected} />+ <span className="text-white" data-testid={`${testIdRoot}-status-label`}>+ {statusLabel}+ </span>+ <span className="text-tertiary-alt">·</span>+ <span className="text-gray-300">{kindLabel}</span>+ {version ? (+ <span+ className="text-xs text-gray-400"+ data-testid={`${testIdRoot}-version`}+ >+ {t(I18nKey.BACKEND$VERSION_LABEL, { version })}+ </span>+ ) : null}+ </div>+ );+}++export interface BackendFormProps {+ mode: BackendFormMode;+ /** Required when `mode === "edit"`. */+ backend?: Backend;+ /**+ * Called after the form is submitted and the backend has been+ * persisted. Use this to dismiss a containing modal, advance an+ * onboarding step, etc.+ */+ onSubmitted: () => void;+ /**+ * Optional render slot rendered in place of the default+ * Save / Cancel button row, so callers (e.g. the onboarding flow)+ * can re-skin the action area while still owning submission via the+ * standard `<form onSubmit>` flow. Receives the form's submit-ready+ * state.+ */+ renderActions?: (state: {+ canSubmit: boolean;+ testIdRoot: string;+ }) => React.ReactNode;+ /** Used to disambiguate test ids across the same screen. */+ testIdRoot?: string;+}++/**+ * Reusable form body for adding / editing a backend. Renders the+ * common name / host / API-key inputs plus the kind selector+ * (radio buttons in `add` mode, status badge in `edit` mode).+ *+ * Rendered as a `<form>`, so consumers should put any extra controls+ * either inside `renderActions` or as siblings inside a wrapping+ * element — but submission flows through the standard form submit so+ * Enter-to-submit still works.+ */+export function BackendForm({mode,backend,- onClose,-}: BackendFormModalProps) {+ onSubmitted,+ renderActions,+ testIdRoot: explicitTestIdRoot,+}: BackendFormProps) {const { t } = useTranslation("openhands");const { addBackend, updateBackend } = useActiveBackendContext();@@ -61,12 +166,15 @@ export function BackendFormModal({}}, [host, touchedKind]);+ const testIdRoot =+ explicitTestIdRoot ?? (mode === "edit" ? "edit-backend" : "add-backend");+const canSubmit =name.trim().length > 0 &&host.trim().length > 0 &&(kind === "local" || apiKey.trim().length > 0);- const onSubmit = (event: React.FormEvent<HTMLFormElement>) => {+ const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {event.preventDefault();if (!canSubmit) return;@@ -89,67 +197,51 @@ export function BackendFormModal({addBackend(payload);}- onClose();+ onSubmitted();};- const titleKey =- mode === "edit" ? I18nKey.BACKEND$EDIT_TITLE : I18nKey.BACKEND$ADD_TITLE;- const testIdRoot = mode === "edit" ? "edit-backend" : "add-backend";-return (- <ModalBackdrop- onClose={onClose}- closeOnEscape={false}- aria-label={t(titleKey)}+ <form+ data-testid={`${testIdRoot}-form`}+ onSubmit={handleSubmit}+ className="flex flex-col gap-4">- <form- data-testid={`${testIdRoot}-modal`}- onSubmit={onSubmit}- className="bg-base-secondary p-6 rounded-xl flex flex-col gap-4 border border-tertiary"- style={{ width: "480px" }}- >- <div className="flex flex-col gap-1">- <h3 className="text-xl font-bold">{t(titleKey)}</h3>- {mode === "add" ? (- <p className="text-xs text-gray-400">- {t(I18nKey.BACKEND$ADD_SUBTITLE)}- </p>- ) : null}- </div>-- <SettingsInput- testId={`${testIdRoot}-name`}- name={`${testIdRoot}-name`}- type="text"- label={t(I18nKey.BACKEND$NAME_LABEL)}- value={name}- onChange={setName}- placeholder="Production"- className="w-full"- />+ <SettingsInput+ testId={`${testIdRoot}-name`}+ name={`${testIdRoot}-name`}+ type="text"+ label={t(I18nKey.BACKEND$NAME_LABEL)}+ value={name}+ onChange={setName}+ placeholder="Production"+ className="w-full"+ />- <SettingsInput- testId={`${testIdRoot}-host`}- name={`${testIdRoot}-host`}- type="text"- label={t(I18nKey.BACKEND$HOST_LABEL)}- value={host}- onChange={setHost}- placeholder="https://app.all-hands.dev"- className="w-full"- />+ <SettingsInput+ testId={`${testIdRoot}-host`}+ name={`${testIdRoot}-host`}+ type="text"+ label={t(I18nKey.BACKEND$HOST_LABEL)}+ value={host}+ onChange={setHost}+ placeholder="https://app.all-hands.dev"+ className="w-full"+ />- <SettingsInput- testId={`${testIdRoot}-api-key`}- name={`${testIdRoot}-api-key`}- type="password"- label={t(I18nKey.BACKEND$KEY_LABEL)}- value={apiKey}- onChange={setApiKey}- placeholder=""- className="w-full"- />+ <SettingsInput+ testId={`${testIdRoot}-api-key`}+ name={`${testIdRoot}-api-key`}+ type="password"+ label={t(I18nKey.BACKEND$KEY_LABEL)}+ value={apiKey}+ onChange={setApiKey}+ placeholder=""+ className="w-full"+ />+ {mode === "edit" && backend ? (+ <BackendStatusBadge backend={backend} testIdRoot={testIdRoot} />+ ) : (<fieldset className="flex flex-col"><legend className="text-sm mb-3">{t(I18nKey.BACKEND$KIND_LABEL)}@@ -188,7 +280,11 @@ export function BackendFormModal({: t(I18nKey.BACKEND$KEY_HELPER_LOCAL)}</p></fieldset>+ )}+ {renderActions ? (+ renderActions({ canSubmit, testIdRoot })+ ) : (<div className="grid grid-cols-2 gap-2 mt-2 w-full"><BrandButtontype="submit"@@ -202,14 +298,61 @@ export function BackendFormModal({<BrandButtontype="button"variant="secondary"- onClick={onClose}+ onClick={onSubmitted}testId={`${testIdRoot}-cancel`}className="w-full text-center">{t(I18nKey.BUTTON$CANCEL)}</BrandButton></div>- </form>+ )}+ </form>+ );+}++/**+ * Modal wrapper around `BackendForm`. Used by both the dropdown's+ * "Add backend" trigger and the manage-backends modal's edit /+ * add-inline buttons.+ */+export function BackendFormModal({+ mode,+ backend,+ onClose,+}: BackendFormModalProps) {+ const { t } = useTranslation("openhands");++ const titleKey =+ mode === "edit" ? I18nKey.BACKEND$EDIT_TITLE : I18nKey.BACKEND$ADD_TITLE;+ const testIdRoot = mode === "edit" ? "edit-backend" : "add-backend";++ return (+ <ModalBackdrop+ onClose={onClose}+ closeOnEscape={false}+ aria-label={t(titleKey)}+ >+ <div+ data-testid={`${testIdRoot}-modal`}+ className="bg-base-secondary p-6 rounded-xl flex flex-col gap-4 border border-tertiary"+ style={{ width: "480px" }}+ >+ <div className="flex flex-col gap-1">+ <h3 className="text-xl font-bold">{t(titleKey)}</h3>+ {mode === "add" ? (+ <p className="text-xs text-gray-400">+ {t(I18nKey.BACKEND$ADD_SUBTITLE)}+ </p>+ ) : null}+ </div>++ <BackendForm+ mode={mode}+ backend={backend}+ onSubmitted={onClose}+ testIdRoot={testIdRoot}+ />+ </div></ModalBackdrop>);}diff --git a/src/components/features/onboarding/index.ts b/src/components/features/onboarding/index.tsnew file mode 100644index 0000000000..57573b7b1a--- /dev/null+++ b/src/components/features/onboarding/index.ts@@ -0,0 +1,7 @@+export { OnboardingModal } from "./onboarding-modal";+export { OnboardingHost } from "./onboarding-host";+export { OnboardingProgressBar } from "./onboarding-progress-bar";+export {+ useOnboardingCompletion,+ ONBOARDING_COMPLETED_STORAGE_KEY,+} from "./use-onboarding-completion";diff --git a/src/components/features/onboarding/onboarding-host.tsx b/src/components/features/onboarding/onboarding-host.tsxnew file mode 100644index 0000000000..468b7acdc0--- /dev/null+++ b/src/components/features/onboarding/onboarding-host.tsx@@ -0,0 +1,19 @@+import React from "react";+import { OnboardingModal } from "./onboarding-modal";+import { useOnboardingCompletion } from "./use-onboarding-completion";++/**+ * Mounts the onboarding modal automatically the first time the user+ * lands on a host route (i.e. when the localStorage onboarding flag+ * isn't set yet). Closing or completing the flow marks it done so the+ * modal won't re-appear on subsequent visits.+ *+ * Renders nothing once onboarding has been completed.+ */+export function OnboardingHost() {+ const { isCompleted, markCompleted } = useOnboardingCompletion();++ if (isCompleted) return null;++ return <OnboardingModal onClose={markCompleted} />;+}diff --git a/src/components/features/onboarding/onboarding-modal.tsx b/src/components/features/onboarding/onboarding-modal.tsxnew file mode 100644index 0000000000..dcae1215b8--- /dev/null+++ b/src/components/features/onboarding/onboarding-modal.tsx@@ -0,0 +1,159 @@+import React from "react";+import { useTranslation } from "react-i18next";+import { X } from "lucide-react";+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";+import { I18nKey } from "#/i18n/declaration";+import { cn } from "#/utils/utils";+import { OnboardingProgressBar } from "./onboarding-progress-bar";+import {+ ChooseAgentStep,+ type OnboardingAgentId,+} from "./steps/choose-agent-step";+import { CheckBackendStep } from "./steps/check-backend-step";+import { SetupLlmStep } from "./steps/setup-llm-step";+import { SayHelloStep } from "./steps/say-hello-step";++const TOTAL_STEPS = 4;++interface SlideProps {+ /** Index of this slide in the step sequence. */+ index: number;+ /** Index of the currently visible step. */+ currentStep: number;+ children: React.ReactNode;+}++/**+ * One step panel inside the slide rail.+ *+ * Only the active slide is in normal flow — it drives the surrounding+ * container's height. Inactive slides are absolutely positioned so+ * they don't add their height to the modal box (which previously made+ * the modal "overhang" with empty space sized to the tallest step).+ *+ * Each slide is translated horizontally by `(index - currentStep) *+ * 100%` so the active step sits at offset 0, with prior steps off to+ * the left and upcoming steps off to the right. Changes to+ * `currentStep` smoothly animate the transform.+ */+function Slide({ index, currentStep, children }: SlideProps) {+ const isActive = index === currentStep;+ const offsetPct = (index - currentStep) * 100;+ return (+ <div+ data-testid={`onboarding-slide-${index}`}+ data-active={isActive}+ aria-hidden={!isActive}+ style={{ transform: `translateX(${offsetPct}%)` }}+ className={cn(+ "w-full transition-transform duration-300 ease-out",+ // Inactive slides are taken out of flow so the rail's height+ // tracks just the active step; they stay overlaid via inset-0+ // so they slide in/out of view across the same horizontal box.+ !isActive && "pointer-events-none absolute inset-0",+ )}+ >+ {children}+ </div>+ );+}++interface OnboardingModalProps {+ /** Called when the user dismisses the modal (skip / X / launch). */+ onClose: () => void;+}++/**+ * Top-level onboarding modal for first-time users.+ *+ * The flow is a fixed sequence of four steps:+ * 0. Choose agent+ * 1. Check backend+ * 2. Set up LLM+ * 3. Say hello (creates a fresh conversation, then closes)+ *+ * Each step lives in its own slide; all four are mounted at once and+ * the rail is translated horizontally by step index, so transitioning+ * between steps animates the new step in from the right.+ */+export function OnboardingModal({ onClose }: OnboardingModalProps) {+ const { t } = useTranslation("openhands");+ const [currentStep, setCurrentStep] = React.useState(0);+ const [selectedAgentId, setSelectedAgentId] =+ React.useState<OnboardingAgentId>("openhands");++ const goNext = React.useCallback(+ () => setCurrentStep((step) => (step >= TOTAL_STEPS - 1 ? step : step + 1)),+ [],+ );+ const goBack = React.useCallback(+ () => setCurrentStep((step) => (step <= 0 ? 0 : step - 1)),+ [],+ );++ return (+ <ModalBackdrop+ onClose={onClose}+ closeOnEscape={false}+ aria-label={t(I18nKey.ONBOARDING$TITLE)}+ >+ <section+ data-testid="onboarding-modal"+ data-current-step={currentStep}+ className={cn(+ "flex flex-col gap-6 rounded-2xl border border-white/10 bg-base-secondary shadow-2xl",+ "w-[560px] max-w-[92vw]",+ )}+ >+ <header className="flex flex-col gap-3 px-7 pt-7">+ <div className="flex items-center justify-between gap-3">+ <p className="text-sm text-gray-400">+ {t(I18nKey.ONBOARDING$STEP_LABEL, {+ current: currentStep + 1,+ total: TOTAL_STEPS,+ })}+ </p>+ <button+ type="button"+ data-testid="onboarding-skip"+ onClick={onClose}+ className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-gray-400 hover:bg-white/5 hover:text-white"+ >+ <span>{t(I18nKey.ONBOARDING$SKIP)}</span>+ <X className="size-3.5" aria-hidden />+ </button>+ </div>+ <OnboardingProgressBar+ currentStep={currentStep}+ totalSteps={TOTAL_STEPS}+ />+ </header>++ <div className="px-7 pb-7">+ <div+ data-testid="onboarding-slide-rail"+ data-current-step={currentStep}+ className="relative overflow-hidden"+ >+ <Slide index={0} currentStep={currentStep}>+ <ChooseAgentStep+ selectedAgentId={selectedAgentId}+ onSelect={setSelectedAgentId}+ onNext={goNext}+ />+ </Slide>+ <Slide index={1} currentStep={currentStep}>+ <CheckBackendStep onBack={goBack} onNext={goNext} />+ </Slide>+ <Slide index={2} currentStep={currentStep}>+ <SetupLlmStep onBack={goBack} onNext={goNext} />+ </Slide>+ <Slide index={3} currentStep={currentStep}>+ <SayHelloStep onBack={goBack} onLaunched={onClose} />+ </Slide>+ </div>+ </div>+ </section>+ </ModalBackdrop>+ );+}diff --git a/src/components/features/onboarding/onboarding-progress-bar.tsx b/src/components/features/onboarding/onboarding-progress-bar.tsxnew file mode 100644index 0000000000..244c4f37d3--- /dev/null+++ b/src/components/features/onboarding/onboarding-progress-bar.tsx@@ -0,0 +1,50 @@+import { cn } from "#/utils/utils";++interface OnboardingProgressBarProps {+ /** Index of the current step (0-based). */+ currentStep: number;+ /** Total number of steps in the flow. */+ totalSteps: number;+ className?: string;+}++/**+ * Segmented progress bar rendered at the top of the onboarding modal.+ * Each step is its own pill that fills in as the user moves forward,+ * giving an at-a-glance sense of how far they have to go.+ */+export function OnboardingProgressBar({+ currentStep,+ totalSteps,+ className,+}: OnboardingProgressBarProps) {+ return (+ <div+ role="progressbar"+ aria-valuemin={1}+ aria-valuemax={totalSteps}+ aria-valuenow={currentStep + 1}+ data-testid="onboarding-progress-bar"+ className={cn("flex w-full items-center gap-2", className)}+ >+ {Array.from({ length: totalSteps }, (_, index) => {+ const isCompleted = index < currentStep;+ const isCurrent = index === currentStep;+ return (+ <div+ key={index}+ data-testid={`onboarding-progress-step-${index}`}+ data-state={+ // eslint-disable-next-line no-nested-ternary+ isCompleted ? "completed" : isCurrent ? "current" : "upcoming"+ }+ className={cn(+ "h-1.5 flex-1 rounded-full transition-colors duration-300",+ isCompleted || isCurrent ? "bg-primary" : "bg-white/15",+ )}+ />+ );+ })}+ </div>+ );+}diff --git a/src/components/features/onboarding/steps/check-backend-step.tsx b/src/components/features/onboarding/steps/check-backend-step.tsxnew file mode 100644index 0000000000..9b3c9f474c--- /dev/null+++ b/src/components/features/onboarding/steps/check-backend-step.tsx@@ -0,0 +1,142 @@+import React from "react";+import { useTranslation } from "react-i18next";+import { CheckCircle2, Loader2, AlertCircle } from "lucide-react";+import { BackendForm } from "#/components/features/backends/backend-form-modal";+import { BrandButton } from "#/components/features/settings/brand-button";+import { useActiveBackendContext } from "#/contexts/active-backend-context";+import { useBackendsHealth } from "#/hooks/query/use-backends-health";+import { I18nKey } from "#/i18n/declaration";+import { cn } from "#/utils/utils";++interface CheckBackendStepProps {+ onBack: () => void;+ onNext: () => void;+}++function ConnectionBanner({ isConnected }: { isConnected: boolean | null }) {+ const { t } = useTranslation("openhands");++ if (isConnected === true) {+ return (+ <div+ role="status"+ data-testid="onboarding-backend-connected"+ className={cn(+ "flex items-start gap-3 rounded-xl border border-green-500/40 bg-green-500/10 px-4 py-3",+ )}+ >+ <CheckCircle2 className="mt-0.5 size-5 shrink-0 text-green-400" />+ <div className="flex flex-col gap-1">+ <span className="text-sm font-medium text-green-200">+ {t(I18nKey.ONBOARDING$BACKEND_CONNECTED_TITLE)}+ </span>+ <span className="text-xs text-green-200/80">+ {t(I18nKey.ONBOARDING$BACKEND_CONNECTED_BODY)}+ </span>+ </div>+ </div>+ );+ }++ if (isConnected === false) {+ return (+ <div+ role="alert"+ data-testid="onboarding-backend-disconnected"+ className="flex items-start gap-3 rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3"+ >+ <AlertCircle className="mt-0.5 size-5 shrink-0 text-red-400" />+ <div className="flex flex-col gap-1">+ <span className="text-sm font-medium text-red-200">+ {t(I18nKey.ONBOARDING$BACKEND_DISCONNECTED_TITLE)}+ </span>+ <span className="text-xs text-red-200/80">+ {t(I18nKey.ONBOARDING$BACKEND_DISCONNECTED_BODY)}+ </span>+ </div>+ </div>+ );+ }++ return (+ <div+ role="status"+ data-testid="onboarding-backend-checking"+ className="flex items-start gap-3 rounded-xl border border-white/10 bg-white/5 px-4 py-3"+ >+ <Loader2 className="mt-0.5 size-5 shrink-0 animate-spin text-gray-300" />+ <span className="text-sm text-gray-200">+ {t(I18nKey.ONBOARDING$BACKEND_CHECKING)}+ </span>+ </div>+ );+}++/**+ * Step 1: embed the "edit backend" form pre-populated with the+ * default/active backend, plus a contextual success/error banner that+ * reacts to the live health probe.+ */+export function CheckBackendStep({ onBack, onNext }: CheckBackendStepProps) {+ const { t } = useTranslation("openhands");+ const { active } = useActiveBackendContext();+ const { backend } = active;+ const healthByBackendId = useBackendsHealth([backend]);+ const isConnected = healthByBackendId[backend.id]?.isConnected ?? null;++ return (+ <div+ data-testid="onboarding-step-check-backend"+ className="flex flex-col gap-6"+ >+ <header className="flex flex-col gap-2">+ <h2 className="text-2xl font-semibold text-white">+ {t(I18nKey.ONBOARDING$BACKEND_TITLE)}+ </h2>+ <p className="text-sm text-gray-400">+ {t(I18nKey.ONBOARDING$BACKEND_SUBTITLE)}+ </p>+ </header>++ <ConnectionBanner isConnected={isConnected} />++ <BackendForm+ mode="edit"+ backend={backend}+ onSubmitted={() => {}}+ testIdRoot="onboarding-backend"+ renderActions={({ canSubmit, testIdRoot }) => (+ <div className="flex items-center justify-between gap-2 mt-2">+ <BrandButton+ testId="onboarding-backend-back"+ type="button"+ variant="secondary"+ onClick={onBack}+ >+ {t(I18nKey.ONBOARDING$BACK)}+ </BrandButton>+ <div className="flex gap-2">+ <BrandButton+ testId={`${testIdRoot}-submit`}+ type="submit"+ variant="secondary"+ isDisabled={!canSubmit}+ >+ {t(I18nKey.BACKEND$SAVE)}+ </BrandButton>+ <BrandButton+ testId="onboarding-backend-next"+ type="button"+ variant="primary"+ isDisabled={isConnected !== true}+ onClick={onNext}+ >+ {t(I18nKey.ONBOARDING$NEXT)}+ </BrandButton>+ </div>+ </div>+ )}+ />+ </div>+ );+}diff --git a/src/components/features/onboarding/steps/choose-agent-step.tsx b/src/components/features/onboarding/steps/choose-agent-step.tsxnew file mode 100644index 0000000000..9cc03cdf74--- /dev/null+++ b/src/components/features/onboarding/steps/choose-agent-step.tsx@@ -0,0 +1,139 @@+import React from "react";+import { useTranslation } from "react-i18next";+import { Check, Sparkles } from "lucide-react";+import { BrandButton } from "#/components/features/settings/brand-button";+import { I18nKey } from "#/i18n/declaration";+import { cn } from "#/utils/utils";++export type OnboardingAgentId = "openhands" | "claude-code" | "codex";++interface AgentOption {+ id: OnboardingAgentId;+ label: string;+ descriptionKey: I18nKey;+ enabled: boolean;+}++const AGENT_OPTIONS: AgentOption[] = [+ {+ id: "openhands",+ label: "OpenHands",+ descriptionKey: I18nKey.ONBOARDING$AGENT_OPENHANDS_DESCRIPTION,+ enabled: true,+ },+ {+ id: "claude-code",+ label: "Claude Code",+ descriptionKey: I18nKey.ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION,+ enabled: false,+ },+ {+ id: "codex",+ label: "Codex",+ descriptionKey: I18nKey.ONBOARDING$AGENT_CODEX_DESCRIPTION,+ enabled: false,+ },+];++interface ChooseAgentStepProps {+ selectedAgentId: OnboardingAgentId;+ onSelect: (agentId: OnboardingAgentId) => void;+ onNext: () => void;+}++export function ChooseAgentStep({+ selectedAgentId,+ onSelect,+ onNext,+}: ChooseAgentStepProps) {+ const { t } = useTranslation("openhands");++ return (+ <div+ data-testid="onboarding-step-choose-agent"+ className="flex flex-col gap-6"+ >+ <header className="flex flex-col gap-2">+ <h2 className="text-2xl font-semibold text-white">+ {t(I18nKey.ONBOARDING$AGENT_TITLE)}+ </h2>+ <p className="text-sm text-gray-400">+ {t(I18nKey.ONBOARDING$AGENT_SUBTITLE)}+ </p>+ </header>++ <div+ role="note"+ data-testid="onboarding-agent-coming-soon"+ className={cn(+ "flex items-start gap-3 rounded-xl border border-primary/40 bg-primary/10 px-4 py-3",+ )}+ >+ <Sparkles className="mt-0.5 size-5 shrink-0 text-primary" aria-hidden />+ <p className="text-sm font-medium text-primary">+ {t(I18nKey.ONBOARDING$AGENT_COMING_SOON)}+ </p>+ </div>++ <div+ role="radiogroup"+ aria-label={t(I18nKey.ONBOARDING$AGENT_TITLE)}+ className="flex flex-col gap-3"+ >+ {AGENT_OPTIONS.map((option) => {+ const isSelected = option.id === selectedAgentId;+ return (+ <button+ key={option.id}+ type="button"+ role="radio"+ aria-checked={isSelected}+ aria-disabled={!option.enabled}+ disabled={!option.enabled}+ data-testid={`onboarding-agent-option-${option.id}`}+ data-selected={isSelected}+ onClick={() => option.enabled && onSelect(option.id)}+ className={cn(+ "flex items-start justify-between gap-4 rounded-xl border px-4 py-3 text-left transition-colors",+ option.enabled+ ? "cursor-pointer hover:border-primary/60 hover:bg-white/5"+ : "cursor-not-allowed opacity-50",+ isSelected+ ? "border-primary bg-primary/10"+ : "border-white/10 bg-base-secondary",+ )}+ >+ <div className="flex flex-col gap-1">+ <span className="text-base font-medium text-white">+ {option.label}+ </span>+ <span className="text-xs text-gray-400">+ {t(option.descriptionKey)}+ </span>+ </div>+ {isSelected ? (+ <Check+ width={18}+ height={18}+ className="mt-1 shrink-0 text-primary"+ aria-hidden+ />+ ) : null}+ </button>+ );+ })}+ </div>++ <div className="flex justify-end">+ <BrandButton+ testId="onboarding-agent-next"+ type="button"+ variant="primary"+ onClick={onNext}+ >+ {t(I18nKey.ONBOARDING$NEXT)}+ </BrandButton>+ </div>+ </div>+ );+}diff --git a/src/components/features/onboarding/steps/say-hello-step.tsx b/src/components/features/onboarding/steps/say-hello-step.tsxnew file mode 100644index 0000000000..e8ddf523e6--- /dev/null+++ b/src/components/features/onboarding/steps/say-hello-step.tsx@@ -0,0 +1,105 @@+import React from "react";+import { useTranslation } from "react-i18next";+import { Send } from "lucide-react";+import { BrandButton } from "#/components/features/settings/brand-button";+import { useNavigation } from "#/context/navigation-context";+import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";+import { useIsCreatingConversation } from "#/hooks/use-is-creating-conversation";+import { I18nKey } from "#/i18n/declaration";++interface SayHelloStepProps {+ onBack: () => void;+ /** Called once the conversation has been created — used by the parent+ * modal to mark the onboarding as complete before unmounting. */+ onLaunched: () => void;+}++/**+ * Step 3: a simple text input pre-filled with "hello OpenHands!" that+ * launches a brand-new conversation with no workspace and navigates+ * to it. Completing this step finishes the onboarding flow.+ */+export function SayHelloStep({ onBack, onLaunched }: SayHelloStepProps) {+ const { t } = useTranslation("openhands");+ const { navigate } = useNavigation();+ const defaultMessage = t(I18nKey.ONBOARDING$HELLO_DEFAULT_MESSAGE);+ const [message, setMessage] = React.useState(defaultMessage);++ const {+ mutate: createConversation,+ isPending,+ isSuccess,+ } = useCreateConversation();+ const isCreatingElsewhere = useIsCreatingConversation();+ const isLaunching = isPending || isSuccess || isCreatingElsewhere;++ const canSubmit = message.trim().length > 0 && !isLaunching;++ const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {+ event.preventDefault();+ if (!canSubmit) return;++ // Explicitly omit `repository` and `workingDir` so the+ // conversation starts with no workspace, per the spec.+ createConversation(+ { query: message.trim() },+ {+ onSuccess: (data) => {+ onLaunched();+ navigate(`/conversations/${data.conversation_id}`);+ },+ },+ );+ };++ return (+ <form+ data-testid="onboarding-step-say-hello"+ onSubmit={handleSubmit}+ className="flex flex-col gap-6"+ >+ <header className="flex flex-col gap-2">+ <h2 className="text-2xl font-semibold text-white">+ {t(I18nKey.ONBOARDING$HELLO_TITLE)}+ </h2>+ <p className="text-sm text-gray-400">+ {t(I18nKey.ONBOARDING$HELLO_SUBTITLE)}+ </p>+ </header>++ <input+ data-testid="onboarding-hello-input"+ aria-label={t(I18nKey.ONBOARDING$HELLO_TITLE)}+ type="text"+ value={message}+ onChange={(event) => setMessage(event.target.value)}+ placeholder={defaultMessage}+ disabled={isLaunching}+ className="w-full rounded-xl border border-white/10 bg-base-secondary px-4 py-3 text-base text-white placeholder:text-gray-500 focus:border-primary focus:outline-none disabled:opacity-60"+ />++ <div className="flex items-center justify-between gap-2">+ <BrandButton+ testId="onboarding-hello-back"+ type="button"+ variant="secondary"+ onClick={onBack}+ isDisabled={isLaunching}+ >+ {t(I18nKey.ONBOARDING$BACK)}+ </BrandButton>+ <BrandButton+ testId="onboarding-hello-launch"+ type="submit"+ variant="primary"+ isDisabled={!canSubmit}+ startContent={<Send className="size-4" aria-hidden />}+ >+ {isLaunching+ ? t(I18nKey.ONBOARDING$HELLO_LAUNCHING)+ : t(I18nKey.ONBOARDING$HELLO_LAUNCH)}+ </BrandButton>+ </div>+ </form>+ );+}diff --git a/src/components/features/onboarding/steps/setup-llm-step.tsx b/src/components/features/onboarding/steps/setup-llm-step.tsxnew file mode 100644index 0000000000..ce09fd1c08--- /dev/null+++ b/src/components/features/onboarding/steps/setup-llm-step.tsx@@ -0,0 +1,96 @@+import React from "react";+import { useTranslation } from "react-i18next";+import { BrandButton } from "#/components/features/settings/brand-button";+import { I18nKey } from "#/i18n/declaration";+import { LlmSettingsScreen } from "#/routes/llm-settings";+import type { SdkSectionSaveControl } from "#/components/features/settings/sdk-settings/sdk-section-page";++interface SetupLlmStepProps {+ onBack: () => void;+ onNext: () => void;+}++/**+ * Pre-fills the LLM form with Anthropic / Claude Opus when the user+ * lands on this onboarding step. The global `DEFAULT_SETTINGS` ships+ * the OpenHands-prefixed Opus, but the onboarding spec calls for+ * routing directly through Anthropic, and these overrides are also+ * marked dirty so the Next button is enabled immediately.+ */+const ONBOARDING_LLM_OVERRIDES = {+ "llm.model": "anthropic/claude-opus-4-5-20251101",+} as const;++/**+ * Step 2: embed the LLM settings form. The screen runs in `embedded`+ * mode (so it doesn't render its own sticky Save bar) and with+ * `hideSaveButton` set, surfacing its save state via+ * `onSaveControlChange`. We then render a single Next button at the+ * modal footer level matching the other onboarding steps; clicking+ * Next saves the form and `onSaveSuccess` advances to the next step.+ *+ * If the form happens to be untouched (no dirty fields), Next falls+ * through to advancing without a save call, so users with already-+ * configured settings aren't blocked.+ */+export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {+ const { t } = useTranslation("openhands");+ const [saveControl, setSaveControl] =+ React.useState<SdkSectionSaveControl | null>(null);++ const handleNext = () => {+ if (saveControl?.isDirty) {+ saveControl.save();+ // `onSaveSuccess` (wired to `onNext` below) will advance once+ // the mutation resolves successfully.+ return;+ }+ onNext();+ };++ return (+ <div+ data-testid="onboarding-step-setup-llm"+ className="flex flex-col gap-6"+ >+ <header className="flex flex-col gap-2">+ <h2 className="text-2xl font-semibold text-white">+ {t(I18nKey.ONBOARDING$LLM_TITLE)}+ </h2>+ <p className="text-sm text-gray-400">+ {t(I18nKey.ONBOARDING$LLM_SUBTITLE)}+ </p>+ </header>++ <div data-testid="onboarding-llm-settings">+ <LlmSettingsScreen+ embedded+ hideSaveButton+ initialValueOverrides={ONBOARDING_LLM_OVERRIDES}+ onSaveSuccess={onNext}+ onSaveControlChange={setSaveControl}+ />+ </div>++ <div className="flex items-center justify-between gap-2">+ <BrandButton+ testId="onboarding-llm-back"+ type="button"+ variant="secondary"+ onClick={onBack}+ >+ {t(I18nKey.ONBOARDING$BACK)}+ </BrandButton>+ <BrandButton+ testId="onboarding-llm-next"+ type="button"+ variant="primary"+ isDisabled={saveControl?.isSaving ?? false}+ onClick={handleNext}+ >+ {t(I18nKey.ONBOARDING$NEXT)}+ </BrandButton>+ </div>+ </div>+ );+}diff --git a/src/components/features/onboarding/use-onboarding-completion.ts b/src/components/features/onboarding/use-onboarding-completion.tsnew file mode 100644index 0000000000..3853e1869f--- /dev/null+++ b/src/components/features/onboarding/use-onboarding-completion.ts@@ -0,0 +1,53 @@+import React from "react";++/**+ * localStorage key persisting whether the welcome onboarding flow has+ * been completed (or skipped). Once present, the modal won't auto-show+ * again on subsequent visits.+ */+export const ONBOARDING_COMPLETED_STORAGE_KEY = "openhands-onboarded";++function readCompletedFromStorage(): boolean {+ if (typeof window === "undefined") return true;+ try {+ return (+ window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY) !== null+ );+ } catch {+ // Inaccessible localStorage (private mode, SSR, …) — assume the+ // user has already onboarded so we don't loop on every render.+ return true;+ }+}++/**+ * Tracks whether the welcome onboarding modal has been completed.+ * The hook returns the current `isCompleted` flag plus an imperative+ * `markCompleted()` callback. State is mirrored to localStorage and+ * synced across tabs via the `storage` event.+ */+export function useOnboardingCompletion() {+ const [isCompleted, setIsCompleted] = React.useState<boolean>(() =>+ readCompletedFromStorage(),+ );++ React.useEffect(() => {+ const handleStorage = (event: StorageEvent) => {+ if (event.key !== ONBOARDING_COMPLETED_STORAGE_KEY) return;+ setIsCompleted(readCompletedFromStorage());+ };+ window.addEventListener("storage", handleStorage);+ return () => window.removeEventListener("storage", handleStorage);+ }, []);++ const markCompleted = React.useCallback(() => {+ try {+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");+ } catch {+ // best-effort; we still flip the in-memory flag below.+ }+ setIsCompleted(true);+ }, []);++ return { isCompleted, markCompleted } as const;+}diff --git a/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/src/components/features/settings/sdk-settings/sdk-section-page.tsxindex 9ec9b14365..673867924f 100644--- a/src/components/features/settings/sdk-settings/sdk-section-page.tsx+++ b/src/components/features/settings/sdk-settings/sdk-section-page.tsx@@ -101,6 +101,21 @@ export interface SdkSectionHeaderProps {onChange: (key: string, value: string | boolean) => void;}+/**+ * Snapshot of the page's save state, surfaced to the parent so it can+ * render its own Save/Next button (e.g. in onboarding) when+ * {@link SdkSectionPage}'s built-in button is hidden via+ * `hideSaveButton`.+ */+export interface SdkSectionSaveControl {+ /** Trigger a save of the currently-dirty fields. No-op while `isSaving` or `!isDirty`. */+ save: () => void;+ /** A save mutation is in flight. */+ isSaving: boolean;+ /** At least one field is dirty (or `extraDirty` was passed in). */+ isDirty: boolean;+}+/*** A generic SDK-schema–driven settings page that renders fields* from one or more schema sections.@@ -122,6 +137,10 @@ export function SdkSectionPage({getInitialView,forceShowAdvancedView = false,allowAllView = true,+ initialValueOverrides,+ embedded = false,+ hideSaveButton = false,+ onSaveControlChange,testId = "sdk-section-settings-screen",}: {sectionKeys: string[];@@ -146,6 +165,34 @@ export function SdkSectionPage({) => SettingsView;forceShowAdvancedView?: boolean;allowAllView?: boolean;+ /**+ * Per-field initial value overrides that win over the values+ * derived from `useSettings`. The keys of each override are also+ * marked dirty on hydration so the user can save the form without+ * having to touch the prefilled fields. Useful when the page is+ * embedded in a flow that wants to nudge brand-new users toward a+ * particular default (e.g. onboarding pre-filling Anthropic/Opus).+ */+ initialValueOverrides?: SettingsFormValues;+ /**+ * When true, the Save button container is rendered inline (no+ * sticky positioning, no contrasting `bg-base` band) so the page+ * can be dropped into a modal/card without a hard footer break.+ */+ embedded?: boolean;+ /**+ * Suppress the built-in Save Changes button entirely. Pair with+ * {@link onSaveControlChange} to drive saving from a parent-rendered+ * action (e.g. an onboarding "Next" button).+ */+ hideSaveButton?: boolean;+ /**+ * Fires whenever the save state changes (a mutation starts/finishes,+ * dirty status flips). Provides a stable `save()` callback the+ * parent can wire to its own button. Useful when the form is+ * embedded in a custom flow and the built-in Save button is hidden.+ */+ onSaveControlChange?: (control: SdkSectionSaveControl) => void;testId?: string;}) {const { t } = useTranslation("openhands");@@ -201,14 +248,24 @@ export function SdkSectionPage({[activeSchemaQuery.error, t],);+ const overridesSignature = React.useMemo(+ () => (initialValueOverrides ? JSON.stringify(initialValueOverrides) : ""),+ [initialValueOverrides],+ );+const initialValues = React.useMemo(() => {if (!settings || !filteredSchema) return null;- return buildInitialSettingsFormValues(+ const base = buildInitialSettingsFormValues(settings,filteredSchema,settingsSource,);- }, [settings, filteredSchema, settingsSource]);+ if (!initialValueOverrides) return base;+ return { ...base, ...initialValueOverrides };+ // overridesSignature keeps the memo reactive without depending on+ // a (potentially recreated) object reference each render.+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [settings, filteredSchema, settingsSource, overridesSignature]);const initialView = React.useMemo(() => {if (!settings || !filteredSchema) return null;@@ -238,7 +295,16 @@ export function SdkSectionPage({if (!initialValues || !initialView) return;setValues(initialValues);- setDirty({});+ // Override-supplied keys are pre-populated for the user, so mark+ // them dirty up-front; otherwise the Save button stays disabled+ // until the user touches a field, defeating the point of the+ // override.+ const overrideDirty: SettingsDirtyState = initialValueOverrides+ ? Object.fromEntries(+ Object.keys(initialValueOverrides).map((key) => [key, true]),+ )+ : {};+ setDirty(overrideDirty);setView((currentView) => {if (!hasHydratedViewRef.current) {hasHydratedViewRef.current = true;@@ -247,6 +313,10 @@ export function SdkSectionPage({return getLessDetailedView(currentView, initialView);});+ // initialValueOverrides is intentionally tracked via+ // overridesSignature on initialValues; including the object ref+ // here would re-fire the effect every render.+ // eslint-disable-next-line react-hooks/exhaustive-deps}, [initialValues, initialView]);const visibleSections = React.useMemo(() => {@@ -275,6 +345,14 @@ export function SdkSectionPage({[t],);+ // Stable save callback so `onSaveControlChange` can hand a single+ // function reference to the parent across renders. The latest+ // closure is kept up to date via `handleSaveRef`.+ const handleSaveRef = React.useRef<() => void>(() => {});+ const stableSave = React.useCallback(() => {+ handleSaveRef.current();+ }, []);+const handleSave = () => {if (!filteredSchema || isReadOnly) return;@@ -314,6 +392,25 @@ export function SdkSectionPage({});};+ handleSaveRef.current = handleSave;++ // Surface save state to the parent. Hooks must run before any+ // conditional early-returns below, so this lives here rather than+ // alongside the JSX. The dependency list deliberately excludes+ // `stableSave` (it never changes) and `onSaveControlChange` (we+ // tolerate ref-instability of the callback to avoid spamming the+ // parent on every render).+ const saveControlIsDirty = Object.keys(dirty).length > 0 || extraDirty;+ React.useEffect(() => {+ if (!onSaveControlChange) return;+ onSaveControlChange({+ save: stableSave,+ isSaving: isPending,+ isDirty: saveControlIsDirty,+ });+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [isPending, saveControlIsDirty]);+if (isLoading || isFetching || isSchemaLoading) {return <LlmSettingsInputsSkeleton />;}@@ -338,7 +435,16 @@ export function SdkSectionPage({isDisabled={isReadOnly}/>- <div className="flex flex-col gap-8 pb-20">+ {/* `pb-20` reserves space for the sticky Save button. When the+ button is hidden (or rendered inline via `embedded`) that+ padding becomes a meaningless gap, so collapse it. */}+ <div+ className={+ embedded || hideSaveButton+ ? "flex flex-col gap-8"+ : "flex flex-col gap-8 pb-20"+ }+ >{header?.({values,isDisabled: isReadOnly,@@ -365,8 +471,8 @@ export function SdkSectionPage({))}</div>- {!isReadOnly ? (- <div className="sticky bottom-0 bg-base py-4">+ {!isReadOnly && !hideSaveButton ? (+ <div className={embedded ? "pt-2" : "sticky bottom-0 bg-base py-4"}><BrandButtontestId="save-button"type="button"diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex 41e46509fd..1fe23a8d6c 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -22834,5 +22834,89 @@"de": "Aktionen einklappen","uk": "Згорнути дії","ca": "Replega les accions"+ },+ "ONBOARDING$TITLE": {+ "en": "Welcome to OpenHands"+ },+ "ONBOARDING$STEP_LABEL": {+ "en": "Step {{current}} of {{total}}"+ },+ "ONBOARDING$NEXT": {+ "en": "Next"+ },+ "ONBOARDING$BACK": {+ "en": "Back"+ },+ "ONBOARDING$SKIP": {+ "en": "Skip for now"+ },+ "ONBOARDING$AGENT_TITLE": {+ "en": "Choose your agent"+ },+ "ONBOARDING$AGENT_SUBTITLE": {+ "en": "Pick the agent that will drive your conversations. You can change this later."+ },+ "ONBOARDING$AGENT_OPENHANDS_DESCRIPTION": {+ "en": "The default OpenHands agent. Best for general-purpose coding and exploration."+ },+ "ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION": {+ "en": "Anthropic's Claude Code agent."+ },+ "ONBOARDING$AGENT_CODEX_DESCRIPTION": {+ "en": "OpenAI's Codex agent."+ },+ "ONBOARDING$AGENT_COMING_SOON": {+ "en": "Support for other agents coming soon!"+ },+ "ONBOARDING$BACKEND_TITLE": {+ "en": "Check your backend"+ },+ "ONBOARDING$BACKEND_SUBTITLE": {+ "en": "OpenHands talks to an agent server. Make sure the default backend is reachable."+ },+ "ONBOARDING$BACKEND_CONNECTED_TITLE": {+ "en": "You're connected! 🎉"+ },+ "ONBOARDING$BACKEND_CONNECTED_BODY": {+ "en": "Your agent server is up and running. Let's keep going."+ },+ "ONBOARDING$BACKEND_CHECKING": {+ "en": "Checking your backend connection…"+ },+ "ONBOARDING$BACKEND_DISCONNECTED_TITLE": {+ "en": "We can't reach your backend"+ },+ "ONBOARDING$BACKEND_DISCONNECTED_BODY": {+ "en": "Update the connection details below and save to retry."+ },+ "ONBOARDING$BACKEND_STATUS_CONNECTED": {+ "en": "Connected"+ },+ "ONBOARDING$BACKEND_STATUS_DISCONNECTED": {+ "en": "Disconnected"+ },+ "ONBOARDING$BACKEND_STATUS_CHECKING": {+ "en": "Checking…"+ },+ "ONBOARDING$LLM_TITLE": {+ "en": "Set up your LLM"+ },+ "ONBOARDING$LLM_SUBTITLE": {+ "en": "Pick a provider and model. We've pre-selected Anthropic Claude Opus."+ },+ "ONBOARDING$HELLO_TITLE": {+ "en": "Say hello 👋"+ },+ "ONBOARDING$HELLO_SUBTITLE": {+ "en": "Send your first message to OpenHands. We'll start a fresh conversation with no workspace."+ },+ "ONBOARDING$HELLO_DEFAULT_MESSAGE": {+ "en": "hello OpenHands!"+ },+ "ONBOARDING$HELLO_LAUNCH": {+ "en": "Send"+ },+ "ONBOARDING$HELLO_LAUNCHING": {+ "en": "Starting conversation…"}}diff --git a/src/routes/home.tsx b/src/routes/home.tsxindex 0d45345e8a..41d611dc55 100644--- a/src/routes/home.tsx+++ b/src/routes/home.tsx@@ -4,6 +4,7 @@ import { RepoConnector } from "#/components/features/home/repo-connector";import { TaskSuggestions } from "#/components/features/home/tasks/task-suggestions";import { NewConversation } from "#/components/features/home/new-conversation/new-conversation";import { RecentConversations } from "#/components/features/home/recent-conversations/recent-conversations";+import { OnboardingHost } from "#/components/features/onboarding";<PrefetchPageLinks page="/conversations/:conversationId" />;@@ -34,6 +35,8 @@ function HomeScreen() {<TaskSuggestions /></div></div>++ <OnboardingHost /></div>);}diff --git a/src/routes/llm-settings.tsx b/src/routes/llm-settings.tsxindex 0f0f039106..4adade7fd2 100644--- a/src/routes/llm-settings.tsx+++ b/src/routes/llm-settings.tsx@@ -9,12 +9,14 @@ import { KeyStatusIcon } from "#/components/features/settings/key-status-icon";import {SdkSectionHeaderProps,SdkSectionPage,+ SdkSectionSaveControl,} from "#/components/features/settings/sdk-settings/sdk-section-page";import { I18nKey } from "#/i18n/declaration";import { Settings, SettingsSchema, SettingsScope } from "#/types/settings";import { extractModelAndProvider } from "#/utils/extract-model-and-provider";import {inferInitialView,+ type SettingsFormValues,type SettingsView,} from "#/utils/sdk-settings-schema";import { DEFAULT_SETTINGS } from "#/services/settings";@@ -92,8 +94,23 @@ function OpenHandsApiKeyHelp({ testId }: OpenHandsApiKeyHelpProps) {export function LlmSettingsScreen({scope = "personal",+ onSaveSuccess,+ initialValueOverrides,+ embedded,+ hideSaveButton,+ onSaveControlChange,}: {scope?: SettingsScope;+ /** Optional hook fired after a successful save (e.g. advance an onboarding step). */+ onSaveSuccess?: () => void;+ /** Forwarded to {@link SdkSectionPage}. */+ initialValueOverrides?: SettingsFormValues;+ /** Forwarded to {@link SdkSectionPage}. */+ embedded?: boolean;+ /** Forwarded to {@link SdkSectionPage}. */+ hideSaveButton?: boolean;+ /** Forwarded to {@link SdkSectionPage}. */+ onSaveControlChange?: (control: SdkSectionSaveControl) => void;}) {const { t } = useTranslation("openhands");@@ -274,6 +291,11 @@ export function LlmSettingsScreen({getInitialView={getInitialView}forceShowAdvancedViewallowAllView+ onSaveSuccess={onSaveSuccess}+ initialValueOverrides={initialValueOverrides}+ embedded={embedded}+ hideSaveButton={hideSaveButton}+ onSaveControlChange={onSaveControlChange}testId="llm-settings-screen"/>);