Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: schedule deletion of legacy/compatibility surface (issue #1337) (#1340)

aivong-openhandsee09546928fd
diff --git a/AGENTS.md b/AGENTS.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
index 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.tsx
index 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.ts
index 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.tsx
deleted file mode 100644
index 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;
-}