π OpenHands: AI-Driven Development
fix: schedule deletion of legacy/compatibility surface (issue #1337) (#1340)
aivong-openhandsee09546928fd
diff --git a/AGENTS.md b/AGENTS.mdindex 9af2ce3b80..4fe45fd892 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -101,7 +101,7 @@ The env var is a JSON string of:}```-All keys under `services` are optional and omitted when the corresponding service isn't running. `frontend.kind` is `"vite"` for dev launchers running the Vite dev server and `"static"` for stacks serving a pre-built `build/` directory (`dev:static`, the published `agent-canvas` binary). `services.vite` is accepted as a legacy alias for `services.frontend` by the renderer.+All keys under `services` are optional and omitted when the corresponding service isn't running. `frontend.kind` is `"vite"` for dev launchers running the Vite dev server and `"static"` for stacks serving a pre-built `build/` directory (`dev:static`, the published `agent-canvas` binary).### Example `<RUNTIME_SERVICES>` block (dev with automation)@@ -471,8 +471,8 @@ When adding code that needs a new string, decide up front which rule it falls un- For local screenshot/GIF capture of SPA routes, serve `build/` with an SPA fallback (for example `sirv build --single`) and restart the static server after each rebuild so hashed asset URLs stay in sync.- Git provider tokens are stored exclusively on the agent-server via `SecretsService` (`PUT /api/settings/secrets`). They are NOT mirrored to localStorage; the frontend reads which providers are connected from `settings.provider_tokens_set` (populated by `GET /api/settings`). Older notes about an `openhands-agent-server-git-provider-tokens` localStorage key are obsolete β no such key is read or written anywhere in the codebase.-- App-level user preferences (language, sound notifications, analytics consent, git identity, disabled skills) are persisted server-side under `PersistedSettings.misc_settings.app_preferences` since agent-server 1.27. `misc_settings` is a generic container for frontend-owned settings the agent doesn't interpret; `app_preferences` is currently its only nested category, but additional categories (e.g. a future `ui_preferences` for sidebar layout / view modes) drop in as additional siblings without churning the top-level wire shape. `GET /api/settings` returns the block under `misc_settings.app_preferences`, and `PATCH /api/settings` accepts a `misc_settings_diff` that is **deep-merged** into the persisted block (same semantics as `agent_settings_diff` / `conversation_settings_diff`). Partial diffs like `{"misc_settings_diff": {"app_preferences": {"language": "fr"}}}` update only the named nested field; sibling `app_preferences` fields are left untouched. Lists (`disabled_skills`) are replaced wholesale by the deep-merge. `SettingsService.transformApiResponse` hoists the nested fields onto the flat `Settings` shape so the rest of the GUI keeps reading them as top-level keys (`settings.language`, `settings.disabled_skills`, β¦). The previous localStorage workaround (keys `openhands-agent-server-app-preferences` and `openhands-agent-server-disabled-skills`) is gone; `src/api/settings-service/legacy-app-preferences-migration.ts` migrates any leftover legacy values to the server on first `getSettings()` call once the server reports a `misc_settings` block, and clears the legacy keys after a successful PATCH. Do NOT reintroduce a localStorage fallback for these fields β `disabled_skills` and the rest belong in `misc_settings_diff.app_preferences`. The previous flat `app_preferences` / `app_preferences_diff` API (introduced in SDK PR #3539, never shipped to users) has been replaced by the `misc_settings` container before either side reached a stable release; on-disk v2 settings files written by the flat shape are migrated automatically on first read by the agent-server.-- Agent server connection settings now live at `Settings > Agent Server` (`/settings/agent-server`). The page reads deployment defaults from `VITE_BACKEND_BASE_URL` / `VITE_SESSION_API_KEY`, saves user overrides in the `openhands-agent-server-config` localStorage key, and must stay reachable even when the backend compatibility probe fails so users can recover from missing or wrong backend configuration.+- App-level user preferences (language, sound notifications, analytics consent, git identity, disabled skills) are persisted server-side under `PersistedSettings.misc_settings.app_preferences` since agent-server 1.27. `misc_settings` is a generic container for frontend-owned settings the agent doesn't interpret; `app_preferences` is currently its only nested category, but additional categories (e.g. a future `ui_preferences` for sidebar layout / view modes) drop in as additional siblings without churning the top-level wire shape. `GET /api/settings` returns the block under `misc_settings.app_preferences`, and `PATCH /api/settings` accepts a `misc_settings_diff` that is **deep-merged** into the persisted block (same semantics as `agent_settings_diff` / `conversation_settings_diff`). Partial diffs like `{"misc_settings_diff": {"app_preferences": {"language": "fr"}}}` update only the named nested field; sibling `app_preferences` fields are left untouched. Lists (`disabled_skills`) are replaced wholesale by the deep-merge. `SettingsService.transformApiResponse` hoists the nested fields onto the flat `Settings` shape so the rest of the GUI keeps reading them as top-level keys (`settings.language`, `settings.disabled_skills`, β¦). Do NOT reintroduce a localStorage fallback for these fields β `disabled_skills` and the rest belong in `misc_settings_diff.app_preferences`. The previous flat `app_preferences` / `app_preferences_diff` API (introduced in SDK PR #3539, never shipped to users) was replaced by the `misc_settings` container before either side reached a stable release; on-disk v2 settings files written by the flat shape are migrated automatically on first read by the agent-server. The legacy localStorage migration (`src/api/settings-service/legacy-app-preferences-migration.ts`) was removed in issue #1337 after a one-release drain period β it is no longer needed.+- Agent server connection settings now live at `Settings > Agent Server` (`/settings/agent-server`). The page reads deployment defaults from `VITE_BACKEND_BASE_URL` / `VITE_SESSION_API_KEY`, saves user overrides in the `openhands-agent-server-config` localStorage key, and must stay reachable even when the backend compatibility probe fails so users can recover from missing or wrong backend configuration. Note: the backend registry seeds directly from the launcher-provided defaults.- Auth modes for `agent-canvas` (dev and production):- **Local mode** (default, no `--public` flag): A session API key is auto-generated and persisted to `~/.openhands/agent-canvas/session-api-key.txt`. The key is baked into the Vite dev server via `VITE_SESSION_API_KEY` or injected into static builds via `static-server.mjs --session-api-key`. Users never need to paste a key.- **Public mode** (`--public` flag): Requires `LOCAL_BACKEND_API_KEY` env var. The key is used as the agent-server session key (`OH_SESSION_API_KEYS_0`) but is NOT baked into the frontend (no `VITE_SESSION_API_KEY`, no `--session-api-key` to static-server). The frontend detects a 401 from `/server_info` via `isAgentServerAuthError()` and shows `ApiKeyEntryScreen` (`src/components/features/backends/api-key-entry-screen.tsx`). The screen reuses `BackendForm` with the host pre-filled (read-only) and prompts for the API key. On submit, the key is persisted to `localStorage['openhands-agent-server-config']` and the page reloads.@@ -480,7 +480,7 @@ When adding code that needs a new string, decide up front which rule it falls un- Production usage: `LOCAL_BACKEND_API_KEY=my-secret npx @openhands/agent-canvas --public`- The `--public` flag is supported by both `scripts/dev-with-automation.mjs` (parsed in `parseArgs()`, propagated via `config.isPublic`) and `bin/agent-canvas.mjs` (passed as `isPublic` to `main()`).- The 401 detection lives in `src/api/agent-server-compatibility.ts` (`isAgentServerAuthError()`), and the gate is in `src/root.tsx`'s `App` component, between the `AgentServerUnavailableError` check and the `<Outlet />` render.- - **Key rotation resilience (non-public):** Stale registry entries are reconciled in two places. (1) `syncLauncherDefaultLocalBackend()` in `src/api/backend-registry/storage.ts` re-runs at module init: for any stored backend whose id is `default-local` and whose host matches (or is loopback-equivalent to) the launcher's default, its `apiKey` is overwritten with the current `makeDefaultLocalBackend().apiKey` (sourced from `VITE_SESSION_API_KEY` or, in the published-binary path, `window.__AGENT_CANVAS_SESSION_API_KEY__`). (2) `scripts/static-server.mjs`'s injection script always overwrites `localStorage['openhands-agent-server-config'].sessionApiKey` when it differs from the runtime key, keeping any code that still reads that legacy storage in sync. E2E coverage: `tests/e2e/mock-llm/mock-llm-auth-modes.spec.ts` (fresh-install, key-rotation, and public-mode scenarios).+ - **Key rotation resilience (non-public):** `syncLauncherDefaultLocalBackend()` in `src/api/backend-registry/storage.ts` re-runs at module init: for any stored backend whose id is `"default-local"` and whose host matches (or is loopback-equivalent to) the launcher's default, its `apiKey` is overwritten with the current `makeDefaultLocalBackend().apiKey` (sourced from `VITE_SESSION_API_KEY` or, in the published-binary path, `window.__AGENT_CANVAS_SESSION_API_KEY__`). E2E coverage: `tests/e2e/mock-llm/mock-llm-auth-modes.spec.ts` (fresh-install, key-rotation, and public-mode scenarios).- Backend/footer actions that launch modals from inside a dropdown or popover should intercept `onMouseDown` to keep the menu mounted, then perform the actual open on `onClick`. Current examples: `Add backend` / `Manage backends` in `src/components/features/backends/backend-selector.tsx`, plus the mirrored workspace-footer buttons in `src/components/features/conversation-panel/new-conversation-button.tsx`.- `BackendSelector`'s cloud-org switch paths should never rethrow from the dropdown `onChange` handler: unexpected non-Axios failures need a generic error toast instead of an unhandled promise rejection, and the malformed `(cloud backend, null org)` self-heal path should fall back to the bundled backend if `/switch` fails.- `NewConversationButton` should support keyboard dismissal (`Escape`) for its inline popover, while still keeping the popover open when its modal children (`FolderBrowserModal`, `ManageWorkspacesModal`) are active.@@ -572,8 +572,8 @@ When adding code that needs a new string, decide up front which rule it falls un- Custom secrets are NOT auto-attached by the agent-server. `POST /api/conversations` only persists what the client sends in `request.secrets`; the persisted secrets store (`/api/settings/secrets`) is never read at conversation-start. `buildStartConversationRequestWithEncryptedSettings` enumerates `SecretsService.getSecrets()` and turns each entry into a `LookupSecret` whose `url` points back at `/api/settings/secrets/{name}` and whose `headers` carry `X-Session-API-Key` for auth. Pre-1.21.x agent-server SDKs would silently drop that header during validation when `secrets_encrypted=true` (the cipher in the validation context tried to `cipher.decrypt(plaintext_session_key)`, failed, and the validator removed the header β the conversation runtime then got 401s for every saved secret). The SDK fix preserves plaintext header values when decryption fails; if you still see saved secrets unavailable inside a conversation, verify the running agent-server bundles a `LookupSecret._validate_secrets` that falls back to plaintext on decrypt failure.-- MCP page layout: MCP is a **top-level** nav entry at `/mcp` (rendered by `src/routes/mcp.tsx`), shown right below "Skills" in `src/components/features/sidebar/sidebar.tsx`. The legacy `/settings/mcp` route still works as a redirect via `src/routes/mcp-settings-redirect.tsx`, and `src/routes/mcp-settings.tsx` re-exports the new page so the published `MCPSettings` library symbol (in `src/components/settings/index.ts`) keeps the same shape. Marketplace catalog data and MCP logo mappings live in the MCP-capable entries from `@openhands/extensions/integrations`; the Slack API catalog option should point at `https://github.com/zencoderai/slack-mcp-server` and use `@zencoderai/slack-mcp-server`. Deprecated marketplace entries removed upstream (for example GitLab / Google Maps / Postgres / Puppeteer / SQLite) should disappear from the marketplace grid. The Installed section still needs to render and search arbitrary non-catalog custom servers via the raw server `name` / `command` fallback in `src/utils/mcp-marketplace-utils.ts` + `InstalledServerCard`. Tavily is a regular stdio MCP entry (`tavily-mcp` + `TAVILY_API_KEY`), not a special built-in sentinel anymore. Components are colocated under `src/components/features/mcp-page/` and reuse the existing `MCPServerForm` for the "Add custom server" / edit flow.-- MCP catalog runtime patching: `getMcpMarketplaceCatalog()` in `src/utils/mcp-marketplace-utils.ts` still patches Linear from the deprecated SSE endpoint to streamable HTTP. Do not reintroduce the old GitHub Docker/native-binary patch: GitHub MCP is hosted (`https://api.githubcopilot.com/mcp/`) via `@openhands/extensions` 0.5.x, and the Docker image no longer bundles `/usr/local/bin/github-mcp-server`.+- MCP page layout: MCP is a **top-level** nav entry at `/mcp` (rendered by `src/routes/mcp.tsx`), shown right below "Skills" in `src/components/features/sidebar/sidebar.tsx`. `src/routes/mcp-settings.tsx` re-exports the new page so the published `MCPSettings` library symbol (in `src/components/settings/index.ts`) keeps the same shape. The legacy `/settings/mcp` redirect was removed in issue #1337. Marketplace catalog data and MCP logo mappings live in the MCP-capable entries from `@openhands/extensions/integrations`; the Slack API catalog option should point at `https://github.com/zencoderai/slack-mcp-server` and use `@zencoderai/slack-mcp-server`. Deprecated marketplace entries removed upstream (for example GitLab / Google Maps / Postgres / Puppeteer / SQLite) should disappear from the marketplace grid. The Installed section still needs to render and search arbitrary non-catalog custom servers via the raw server `name` / `command` fallback in `src/utils/mcp-marketplace-utils.ts` + `InstalledServerCard`. Tavily is a regular stdio MCP entry (`tavily-mcp` + `TAVILY_API_KEY`), not a special built-in sentinel anymore. Components are colocated under `src/components/features/mcp-page/` and reuse the existing `MCPServerForm` for the "Add custom server" / edit flow.+- MCP catalog runtime patching: `getMcpMarketplaceCatalog()` in `src/utils/mcp-marketplace-utils.ts` pipes every catalog entry through patch functions before the UI sees it. Two patches exist: `patchLinearEntry` (rewrites the deprecated Linear SSE endpoint to streamable HTTP) and `patchGitHubEntry` (rewrites the `docker run` transport to the native `github-mcp-server stdio` binary, only when `getDeploymentMode() === "docker"`). The `getDeploymentMode()` helper is exported from `src/api/agent-server-adapter.ts` and reads the `mode` field from the runtime services info. The Docker image pre-installs the `github-mcp-server` Go binary at `/usr/local/bin/github-mcp-server` via a dedicated Dockerfile download stage (`github-mcp-download`). This avoids a Docker-in-Docker requirement β GitHub is the only catalog entry that uses `docker` as its stdio command; all others use `npx` or `uvx`. When adding similar patches for other entries, follow the same pattern: guard on `entry.id`, check environment conditionally, spread immutably.- Library packaging notes:- Public npm entrypoints now come from `src/index.ts` β `src/lib/index.ts`, with domain barrels under `src/components/{conversation,terminal,browser,files,settings,sidebar}/index.ts`.diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.tsindex 5092885917..21a576b3cc 100644--- a/__tests__/api/agent-server-adapter.test.ts+++ b/__tests__/api/agent-server-adapter.test.ts@@ -1071,26 +1071,6 @@ describe("buildRuntimeServicesSystemSuffix", () => {expect(suffix).not.toContain("Vite frontend");});- it("accepts the legacy `vite` service key", () => {- // Older launchers may still emit `services.vite`. Render it under the- // new "Frontend" label rather than dropping the entry.- vi.stubEnv(- "VITE_RUNTIME_SERVICES_INFO",- JSON.stringify({- mode: "dev:safe",- services: {- agent_server: { url_from_agent: "http://localhost:18000" },- vite: {- description: "Vite dev server",- url_from_agent: "http://localhost:3001",- },- },- }),- );- const suffix = buildRuntimeServicesSystemSuffix();- expect(suffix).toContain("* Frontend: http://localhost:3001");- });-it("explicitly mentions when automation is absent", () => {vi.stubEnv("VITE_RUNTIME_SERVICES_INFO",diff --git a/__tests__/api/backend-registry/active-store.test.ts b/__tests__/api/backend-registry/active-store.test.tsindex ef3888bcc6..8177df52ee 100644--- a/__tests__/api/backend-registry/active-store.test.ts+++ b/__tests__/api/backend-registry/active-store.test.ts@@ -8,7 +8,7 @@ import {setRegisteredBackends,subscribeActiveBackend,} from "#/api/backend-registry/active-store";-import { DEFAULT_LOCAL_BACKEND_ID } from "#/api/backend-registry/default-backend";+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";import type { Backend } from "#/api/backend-registry/types";beforeEach(() => {@@ -58,7 +58,7 @@ describe("active-store", () => {__resetActiveStoreForTests();const { backend, orgId } = getActiveBackend();- expect(backend.id).toBe(DEFAULT_LOCAL_BACKEND_ID);+ expect(backend.id).toBe(SEEDED_DEFAULT_BACKEND_ID);expect(backend.kind).toBe("local");expect(orgId).toBeNull();});diff --git a/__tests__/api/backend-registry/storage.test.ts b/__tests__/api/backend-registry/storage.test.tsindex f794d34f11..0e0d7fa1ed 100644--- a/__tests__/api/backend-registry/storage.test.ts+++ b/__tests__/api/backend-registry/storage.test.ts@@ -69,32 +69,6 @@ describe("backend-registry storage", () => {expect(readStoredBackends()).toEqual(result);});- it("migrates legacy agent-server config into the backend registry on first read", () => {- window.localStorage.setItem(- "openhands-agent-server-config",- JSON.stringify({- baseUrl: "localhost:18000/",- sessionApiKey: "legacy-session-key",- }),- );-- const result = readStoredBackends();-- expect(result).toEqual([- {- id: "default-local",- name: "Local",- host: "http://localhost:18000",- apiKey: "legacy-session-key",- kind: "local",- },- ]);- expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).not.toBeNull();- expect(- window.localStorage.getItem("openhands-agent-server-config"),- ).toBeNull();- });-it("re-seeds the default Local backend when storage holds an empty array and launcher details are available", () => {vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");diff --git a/__tests__/api/settings-service.test.ts b/__tests__/api/settings-service.test.tsindex c019571708..1ec5fcfb06 100644--- a/__tests__/api/settings-service.test.ts+++ b/__tests__/api/settings-service.test.ts@@ -2,7 +2,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { http, HttpResponse } from "msw";import SettingsService from "#/api/settings-service/settings-service.api";-import { __TEST_ONLY as LEGACY_MIGRATION_KEYS } from "#/api/settings-service/legacy-app-preferences-migration";import {__resetActiveStoreForTests,setActiveSelection,@@ -228,128 +227,6 @@ describe("SettingsService", () => {]);});- it("migrates legacy localStorage app preferences to the server on first read", async () => {- // Simulate an existing user on an older agent-canvas version: app prefs- // and disabled_skills sit in localStorage and have never been pushed to- // the new server-side store. The first getSettings call after upgrade- // should send them up via misc_settings_diff and clear the keys.- window.localStorage.setItem(- LEGACY_MIGRATION_KEYS.LEGACY_APP_PREFERENCES_KEY,- JSON.stringify({- language: "fr",- git_user_name: "Alice",- }),- );- window.localStorage.setItem(- LEGACY_MIGRATION_KEYS.LEGACY_DISABLED_SKILLS_KEY,- JSON.stringify(["SSH Microagent"]),- );-- // The migration path is: initial GET β server reports empty- // misc_settings.app_preferences (server is new enough to support the- // field) β push localStorage values up via PATCH β re-fetch GET so the- // cache sees the migrated values. The test handlers below simulate that- // round-trip without leaning on the default MSW state, which the PATCH- // override would not update.- const patchBodies: Array<Record<string, unknown>> = [];- let migrated = false;- server.use(- http.get("*/api/settings", async () =>- HttpResponse.json({- agent_settings: {},- conversation_settings: {},- llm_api_key_is_set: false,- misc_settings: {- app_preferences: migrated- ? {- language: "fr",- git_user_name: "Alice",- disabled_skills: ["SSH Microagent"],- }- : {},- },- }),- ),- http.patch("*/api/settings", async ({ request }) => {- patchBodies.push((await request.json()) as Record<string, unknown>);- migrated = true;- return HttpResponse.json({- agent_settings: {},- conversation_settings: {},- llm_api_key_is_set: false,- misc_settings: {- app_preferences: {- language: "fr",- git_user_name: "Alice",- disabled_skills: ["SSH Microagent"],- },- },- });- }),- );-- const settings = await SettingsService.getSettings();-- // Single migration PATCH carrying every legacy value:- expect(patchBodies).toEqual([- {- misc_settings_diff: {- app_preferences: {- language: "fr",- git_user_name: "Alice",- disabled_skills: ["SSH Microagent"],- },- },- },- ]);- // Legacy keys are cleared:- expect(- window.localStorage.getItem(- LEGACY_MIGRATION_KEYS.LEGACY_APP_PREFERENCES_KEY,- ),- ).toBeNull();- expect(- window.localStorage.getItem(- LEGACY_MIGRATION_KEYS.LEGACY_DISABLED_SKILLS_KEY,- ),- ).toBeNull();- // β¦and the returned Settings reflect the migrated values:- expect(settings.language).toBe("fr");- expect(settings.git_user_name).toBe("Alice");- expect(settings.disabled_skills).toEqual(["SSH Microagent"]);- });-- it("skips migration when the server omits misc_settings (pre-1.27)", async () => {- // Older agent-servers don't return the misc_settings field at all. The- // migration must no-op so we don't drop user data before the server can- // accept it.- window.localStorage.setItem(- LEGACY_MIGRATION_KEYS.LEGACY_APP_PREFERENCES_KEY,- JSON.stringify({ language: "fr" }),- );-- server.use(- http.get("*/api/settings", async () =>- HttpResponse.json({- agent_settings: {},- conversation_settings: {},- llm_api_key_is_set: false,- // No misc_settings key β simulates pre-1.27 server.- }),- ),- );-- await SettingsService.getSettings();-- // Legacy key still present, ready for a later retry once the user- // upgrades the server.- expect(- window.localStorage.getItem(- LEGACY_MIGRATION_KEYS.LEGACY_APP_PREFERENCES_KEY,- ),- ).not.toBeNull();- });-it("forwards app-level preferences as flat top-level fields to the cloud save", async () => {// Arrange: switch the active backend to cloud so saveSettings routes// through saveCloudSettings (mocked).diff --git a/__tests__/api/to-app-conversation-session-key.test.ts b/__tests__/api/to-app-conversation-session-key.test.tsindex cf2c068da1..f71da56122 100644--- a/__tests__/api/to-app-conversation-session-key.test.ts+++ b/__tests__/api/to-app-conversation-session-key.test.ts@@ -5,7 +5,7 @@ import {__resetActiveStoreForTests,setRegisteredBackends,} from "#/api/backend-registry/active-store";-import { DEFAULT_LOCAL_BACKEND_ID } from "#/api/backend-registry/default-backend";+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";const directInfo = (id: string) => ({id,@@ -25,7 +25,7 @@ describe("toAppConversation session_api_key hydration", () => {setRegisteredBackends([{- id: DEFAULT_LOCAL_BACKEND_ID,+ id: SEEDED_DEFAULT_BACKEND_ID,name: "Local",host: window.location.origin,apiKey: "stale-session-key",diff --git a/__tests__/components/backends/manage-backends-modal.test.tsx b/__tests__/components/backends/manage-backends-modal.test.tsxindex 00f864f3e0..42baf0bbe1 100644--- a/__tests__/components/backends/manage-backends-modal.test.tsx+++ b/__tests__/components/backends/manage-backends-modal.test.tsx@@ -4,7 +4,7 @@ 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 { DEFAULT_LOCAL_BACKEND_ID } from "#/api/backend-registry/default-backend";+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";import {BACKEND_HEALTH_STORAGE_KEY,MAX_CONSECUTIVE_FAILURES,@@ -157,7 +157,7 @@ describe("ManageBackendsModal", () => {window.localStorage.setItem(BACKEND_HEALTH_STORAGE_KEY,JSON.stringify({- [DEFAULT_LOCAL_BACKEND_ID]: {+ [SEEDED_DEFAULT_BACKEND_ID]: {consecutiveFailures: MAX_CONSECUTIVE_FAILURES,lastError: "Network Error",lastFailureAt: Date.now(),diff --git a/__tests__/contexts/active-backend-context.test.tsx b/__tests__/contexts/active-backend-context.test.tsxindex 6d390ffed7..8a0211ef98 100644--- a/__tests__/contexts/active-backend-context.test.tsx+++ b/__tests__/contexts/active-backend-context.test.tsx@@ -6,7 +6,7 @@ import {__resetActiveStoreForTests,NO_BACKEND_ID,} from "#/api/backend-registry/active-store";-import { DEFAULT_LOCAL_BACKEND_ID } from "#/api/backend-registry/default-backend";+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage";import {__resetHealthStoreForTests,@@ -50,10 +50,10 @@ describe("ActiveBackendProvider", () => {wrapper: makeWrapper(),});- expect(result.current.active.backend.id).toBe(DEFAULT_LOCAL_BACKEND_ID);+ expect(result.current.active.backend.id).toBe(SEEDED_DEFAULT_BACKEND_ID);expect(result.current.backends).toHaveLength(1);expect(result.current.backends[0]).toMatchObject({- id: DEFAULT_LOCAL_BACKEND_ID,+ id: SEEDED_DEFAULT_BACKEND_ID,kind: "local",});});@@ -88,7 +88,7 @@ describe("ActiveBackendProvider", () => {wrapper: makeWrapper(),});- expect(result.current.active.backend.id).toBe(DEFAULT_LOCAL_BACKEND_ID);+ expect(result.current.active.backend.id).toBe(SEEDED_DEFAULT_BACKEND_ID);let added: { id: string } | null = null;act(() => {@@ -104,7 +104,7 @@ describe("ActiveBackendProvider", () => {// Previous backends remain in the registry.expect(result.current.backends).toHaveLength(2);expect(- result.current.backends.find((b) => b.id === DEFAULT_LOCAL_BACKEND_ID),+ result.current.backends.find((b) => b.id === SEEDED_DEFAULT_BACKEND_ID),).toBeDefined();});@@ -163,9 +163,9 @@ describe("ActiveBackendProvider", () => {act(() => {result.current.removeBackend(id);});- expect(result.current.active.backend.id).toBe(DEFAULT_LOCAL_BACKEND_ID);+ expect(result.current.active.backend.id).toBe(SEEDED_DEFAULT_BACKEND_ID);expect(result.current.backends).toHaveLength(1);- expect(result.current.backends[0].id).toBe(DEFAULT_LOCAL_BACKEND_ID);+ expect(result.current.backends[0].id).toBe(SEEDED_DEFAULT_BACKEND_ID);});// @spec BM-003 β Fallback on active backend removal@@ -177,7 +177,7 @@ describe("ActiveBackendProvider", () => {expect(result.current.backends).toHaveLength(1);act(() => {- result.current.removeBackend(DEFAULT_LOCAL_BACKEND_ID);+ result.current.removeBackend(SEEDED_DEFAULT_BACKEND_ID);});expect(result.current.backends).toEqual([]);diff --git a/__tests__/hooks/query/use-backends-health.test.tsx b/__tests__/hooks/query/use-backends-health.test.tsxindex 57c9b5f8d6..4ccdbf624c 100644--- a/__tests__/hooks/query/use-backends-health.test.tsx+++ b/__tests__/hooks/query/use-backends-health.test.tsx@@ -6,7 +6,7 @@ import React from "react";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { act, renderHook, waitFor } from "@testing-library/react";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";-import { DEFAULT_LOCAL_BACKEND_ID } from "#/api/backend-registry/default-backend";+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";import {BACKEND_HEALTH_STORAGE_KEY,MAX_CONSECUTIVE_FAILURES,@@ -37,7 +37,7 @@ vi.mock("#/api/cloud/organization-service.api", () => ({}));const localBackend: Backend = {- id: DEFAULT_LOCAL_BACKEND_ID,+ id: SEEDED_DEFAULT_BACKEND_ID,name: "Local",host: "http://localhost:18000",apiKey: "",diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.tsindex 0151d0885e..6998da09d4 100644--- a/src/api/agent-server-adapter.ts+++ b/src/api/agent-server-adapter.ts@@ -208,10 +208,7 @@ export function buildRuntimeServicesSystemSuffix(): string | undefined {);const { agent_server, ingress, automation } = info.services;- // Accept `frontend` (current key) or `vite` (legacy key) for the- // frontend service entry. The legacy fallback can be removed once all- // launchers in this repo emit `frontend`.- const frontend = info.services.frontend ?? info.services.vite;+ const { frontend } = info.services;if (agent_server?.url_from_agent) {lines.push(diff --git a/src/api/backend-registry/default-backend.ts b/src/api/backend-registry/default-backend.tsindex 0bbe676549..77b7f1fad0 100644--- a/src/api/backend-registry/default-backend.ts+++ b/src/api/backend-registry/default-backend.ts@@ -5,12 +5,13 @@ import {import type { Backend } from "./types";/**- * Stable id for the default local backend that is auto-seeded into the- * registry when the launcher provides both a backend host and API key.- * After seeding, this backend is a normal registered entry β the user can- * rename it, edit its host/api key, or remove it like any other backend.+ * Stable id for the seeded default local backend that is auto-registered in+ * the backend registry when the launcher provides both a backend host and+ * API key. After seeding, this backend is a normal registered entry β the+ * user can rename it, edit its host/api key, or remove it like any other+ * backend.*/-export const DEFAULT_LOCAL_BACKEND_ID = "default-local";+export const SEEDED_DEFAULT_BACKEND_ID = "default-local";export const DEFAULT_LOCAL_BACKEND_NAME = "Local";@@ -29,7 +30,7 @@ export function makeDefaultLocalBackend(): Backend | null {if (!host || !apiKey) return null;return {- id: DEFAULT_LOCAL_BACKEND_ID,+ id: SEEDED_DEFAULT_BACKEND_ID,name: DEFAULT_LOCAL_BACKEND_NAME,host,apiKey,diff --git a/src/api/backend-registry/storage.ts b/src/api/backend-registry/storage.tsindex a29e90f105..e2fb656ecb 100644--- a/src/api/backend-registry/storage.ts+++ b/src/api/backend-registry/storage.ts@@ -1,6 +1,5 @@import {- DEFAULT_LOCAL_BACKEND_ID,- DEFAULT_LOCAL_BACKEND_NAME,+ SEEDED_DEFAULT_BACKEND_ID,makeDefaultLocalBackend,} from "./default-backend";import type { Backend, BackendKind, BackendSelection } from "./types";@@ -8,8 +7,6 @@ import type { Backend, BackendKind, BackendSelection } from "./types";export const BACKENDS_STORAGE_KEY = "openhands-backends";export const ACTIVE_BACKEND_STORAGE_KEY = "openhands-active-backend";-const LEGACY_AGENT_SERVER_CONFIG_STORAGE_KEY = "openhands-agent-server-config";-function isValidKind(value: unknown): value is BackendKind {return value === "local" || value === "cloud";}@@ -27,52 +24,6 @@ function isValidBackend(value: unknown): value is Backend {);}-function normalizeLegacyBaseUrl(value: unknown): string | null {- if (typeof value !== "string") return null;- const trimmed = value.trim().replace(/\/+$/, "");- if (!trimmed) return null;- if (/^https?:\/\//i.test(trimmed)) return trimmed;- return `http://${trimmed}`;-}--function readLegacyBackend(): Backend | null {- const raw = window.localStorage.getItem(- LEGACY_AGENT_SERVER_CONFIG_STORAGE_KEY,- );- if (!raw) return null;-- try {- const parsed = JSON.parse(raw) as Record<string, unknown>;- const host = normalizeLegacyBaseUrl(parsed.baseUrl);- const apiKey =- typeof parsed.sessionApiKey === "string"- ? parsed.sessionApiKey.trim()- : "";-- if (!host || !apiKey) return null;-- return {- id: DEFAULT_LOCAL_BACKEND_ID,- name: DEFAULT_LOCAL_BACKEND_NAME,- host,- apiKey,- kind: "local",- };- } catch {- return null;- }-}--function clearLegacyBackendConfig(): void {- window.localStorage.removeItem(LEGACY_AGENT_SERVER_CONFIG_STORAGE_KEY);-}--function seedBackends(backends: Backend[]): Backend[] {- writeStoredBackends(backends);- clearLegacyBackendConfig();- return backends;-}-function isLoopbackUrl(value: string): boolean {try {const { hostname } = new URL(value);@@ -91,7 +42,7 @@ function shouldSyncLauncherDefaultLocalBackend(backend: Backend,defaultBackend: Backend,): boolean {- if (backend.id !== DEFAULT_LOCAL_BACKEND_ID || backend.kind !== "local") {+ if (backend.id !== SEEDED_DEFAULT_BACKEND_ID || backend.kind !== "local") {return false;}@@ -141,17 +92,14 @@ export function readStoredBackends(): Backend[] {try {const raw = window.localStorage.getItem(BACKENDS_STORAGE_KEY);- // First install: migrate one legacy local backend if present, otherwise- // seed only when the launcher supplied enough information for a usable- // local backend.+ // First install: seed only when the launcher supplied enough information+ // for a usable local backend.if (raw === null) {- const legacyBackend = readLegacyBackend();- if (legacyBackend) return seedBackends([legacyBackend]);-const defaultBackend = makeDefaultLocalBackend();if (!defaultBackend) return [];- return seedBackends([defaultBackend]);+ writeStoredBackends([defaultBackend]);+ return [defaultBackend];}const parsed = JSON.parse(raw);@@ -164,11 +112,11 @@ export function readStoredBackends(): Backend[] {const defaultBackend = makeDefaultLocalBackend();if (!defaultBackend) return [];- return seedBackends([defaultBackend]);+ writeStoredBackends([defaultBackend]);+ return [defaultBackend];}const synced = syncLauncherDefaultLocalBackend(valid);- clearLegacyBackendConfig();return synced;} catch {return [];diff --git a/src/api/settings-service/legacy-app-preferences-migration.ts b/src/api/settings-service/legacy-app-preferences-migration.tsdeleted file mode 100644index fe68d05ded..0000000000--- a/src/api/settings-service/legacy-app-preferences-migration.ts+++ /dev/null@@ -1,136 +0,0 @@-/**- * One-shot migration: promote app preferences and disabled_skills from- * pre-1.27 agent-canvas's localStorage into the agent-server's persisted- * `misc_settings.app_preferences` block (introduced via SDK PRs #3539 +- * follow-up refactor).- *- * Older versions stored these fields under two localStorage keys because- * the local agent-server had no native home for them:- *- * - `openhands-agent-server-app-preferences` β { language?, git_user_name?,- * git_user_email?, enable_sound_notifications?, user_consents_to_analytics? }- * - `openhands-agent-server-disabled-skills` β string[]- *- * Once the server reports a `misc_settings` block (even one with empty- * defaults), we check those legacy keys, push any non-empty values up to- * the server via a single PATCH, and clear the keys. The check is- * idempotent: on subsequent calls both keys are absent and the function- * no-ops.- *- * Failures during the PATCH are tolerated β the legacy keys are left in- * place so a later attempt can retry. This keeps the migration a best-effort- * side-effect of `getSettings`; if it never succeeds, the user just sees- * empty server-side preferences (the same as a fresh install).- */--import type { SettingsValue } from "#/types/settings";-import type {- AppPreferences,- SettingsApiResponse,-} from "./settings-service.api";--const LEGACY_APP_PREFERENCES_KEY = "openhands-agent-server-app-preferences";-const LEGACY_DISABLED_SKILLS_KEY = "openhands-agent-server-disabled-skills";--const isBrowser = (): boolean => typeof window !== "undefined";--const readLegacyAppPreferences = (): AppPreferences | null => {- if (!isBrowser()) return null;- try {- const raw = window.localStorage.getItem(LEGACY_APP_PREFERENCES_KEY);- if (!raw) return null;- const parsed = JSON.parse(raw) as unknown;- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {- return null;- }- return parsed as AppPreferences;- } catch {- return null;- }-};--const readLegacyDisabledSkills = (): string[] | null => {- if (!isBrowser()) return null;- try {- const raw = window.localStorage.getItem(LEGACY_DISABLED_SKILLS_KEY);- if (!raw) return null;- const parsed = JSON.parse(raw) as unknown;- if (!Array.isArray(parsed)) return null;- return parsed.filter((v): v is string => typeof v === "string");- } catch {- return null;- }-};--const clearLegacyKeys = (): void => {- if (!isBrowser()) return;- try {- window.localStorage.removeItem(LEGACY_APP_PREFERENCES_KEY);- window.localStorage.removeItem(LEGACY_DISABLED_SKILLS_KEY);- } catch {- // ignore; the migration will be retried on next read- }-};--const APP_PREFERENCE_KEYS = [- "language",- "user_consents_to_analytics",- "enable_sound_notifications",- "git_user_name",- "git_user_email",-] as const;--const buildDiff = (- storedPrefs: AppPreferences | null,- storedSkills: string[] | null,-): AppPreferences | null => {- const diff: Record<string, unknown> = {};- if (storedPrefs) {- for (const key of APP_PREFERENCE_KEYS) {- const value = (storedPrefs as Record<string, unknown>)[key];- if (value !== undefined) {- diff[key] = value;- }- }- }- if (storedSkills) {- diff.disabled_skills = storedSkills;- }- return Object.keys(diff).length > 0- ? (diff as Record<string, SettingsValue> as AppPreferences)- : null;-};--/**- * Returns `true` when a migration PATCH was issued (caller should re-fetch- * settings). Returns `false` when no legacy data was present.- */-export const migrateLegacyAppPreferences = async (- serverResponse: SettingsApiResponse,- pushDiff: (diff: AppPreferences) => Promise<unknown>,-): Promise<boolean> => {- // Only run when the server actually returns a `misc_settings` block- // (server is new enough to accept the diff). Older servers omit the- // field entirely; the migration stays pending until the user upgrades.- if (!serverResponse.misc_settings) return false;-- const storedPrefs = readLegacyAppPreferences();- const storedSkills = readLegacyDisabledSkills();- const diff = buildDiff(storedPrefs, storedSkills);- if (!diff) return false;-- try {- await pushDiff(diff);- clearLegacyKeys();- return true;- } catch {- // Leave the legacy keys for a later retry; we don't want to lose data on- // a transient network failure.- return false;- }-};--export const __TEST_ONLY = {- LEGACY_APP_PREFERENCES_KEY,- LEGACY_DISABLED_SKILLS_KEY,-};diff --git a/src/api/settings-service/settings-service.api.ts b/src/api/settings-service/settings-service.api.tsindex fa4582bd8f..c2d6a5a592 100644--- a/src/api/settings-service/settings-service.api.ts+++ b/src/api/settings-service/settings-service.api.ts@@ -9,7 +9,6 @@ import {saveCloudSettings,} from "../cloud/settings-service.api";import { getAgentServerClientOptions } from "../agent-server-client-options";-import { migrateLegacyAppPreferences } from "./legacy-app-preferences-migration";/*** Fields the agent-server stores under `misc_settings.app_preferences` (see@@ -327,23 +326,7 @@ class SettingsService {}try {- let response = await this.fetchSettingsFromApi();- // One-shot migration: if the user previously stored app preferences in- // localStorage (older agent-canvas versions) and the server has no- // app_preferences for this user yet, promote the local values to the- // server now. Re-fetches so the cache is seeded with the migrated- // response. Safe to call repeatedly β clears the legacy keys after a- // successful push and no-ops thereafter.- const migrated = await migrateLegacyAppPreferences(- response,- (diff) =>- new SettingsClient(getAgentServerClientOptions()).updateSettings({- misc_settings_diff: { app_preferences: diff },- }) as Promise<unknown>,- );- if (migrated) {- response = await this.fetchSettingsFromApi();- }+ const response = await this.fetchSettingsFromApi();settingsCache.redacted = response;settingsCache.timestamp = Date.now();return syncDerivedSettings(transformApiResponse(response));diff --git a/src/components/features/settings/agent-server-onboarding.tsx b/src/components/features/settings/agent-server-onboarding.tsxindex 8f485d00e0..79fa549dfc 100644--- a/src/components/features/settings/agent-server-onboarding.tsx+++ b/src/components/features/settings/agent-server-onboarding.tsx@@ -7,7 +7,7 @@ import {setRegisteredBackends,} from "#/api/backend-registry/active-store";import {- DEFAULT_LOCAL_BACKEND_ID,+ SEEDED_DEFAULT_BACKEND_ID,DEFAULT_LOCAL_BACKEND_NAME,} from "#/api/backend-registry/default-backend";import type { Backend } from "#/api/backend-registry/types";@@ -54,7 +54,7 @@ export function AgentServerConnectionForm({const trimmedKey = sessionApiKey.trim();const current = getRegisteredBackends();const defaultEntry: Backend = {- id: DEFAULT_LOCAL_BACKEND_ID,+ id: SEEDED_DEFAULT_BACKEND_ID,name: DEFAULT_LOCAL_BACKEND_NAME,host: trimmedHost,apiKey: trimmedKey,@@ -62,7 +62,7 @@ export function AgentServerConnectionForm({};const existingIndex = current.findIndex(- (b) => b.id === DEFAULT_LOCAL_BACKEND_ID,+ (b) => b.id === SEEDED_DEFAULT_BACKEND_ID,);if (existingIndex === -1) {setRegisteredBackends([defaultEntry, ...current]);diff --git a/src/routes.ts b/src/routes.tsindex 7a46b252e8..955e2dc2d4 100644--- a/src/routes.ts+++ b/src/routes.ts@@ -25,8 +25,6 @@ export default [route("agent", "routes/agent-settings.tsx"),route("condenser", "routes/condenser-settings.tsx"),route("verification", "routes/verification-settings.tsx"),- // Legacy entry: redirects to /mcp (preserves old bookmarks).- route("mcp", "routes/mcp-settings-redirect.tsx"),route("app", "routes/app-settings.tsx"),route("secrets", "routes/secrets-settings.tsx"),]),diff --git a/src/routes/mcp-settings-redirect.tsx b/src/routes/mcp-settings-redirect.tsxdeleted file mode 100644index d351d0c1f5..0000000000--- a/src/routes/mcp-settings-redirect.tsx+++ /dev/null@@ -1,10 +0,0 @@-import { redirect } from "react-router";--// MCP settings used to live at /settings/mcp. It now has a dedicated-// top-level entry under the main left-hand navigation, so this route-// just redirects to keep old links working.-export const clientLoader = async () => redirect("/mcp");--export default function MCPSettingsRedirect() {- return null;-}