Skip to content

πŸ™Œ OpenHands: AI-Driven Development

settings: persist app preferences and `disabled_skills` on the agent-server (#1191)

chuckbutkusf93cb3c9ee92
diff --git a/AGENTS.md b/AGENTS.md
index 9843406e42..4c6cd878be 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -493,6 +493,7 @@ 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.
- 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.
@@ -512,10 +513,10 @@ When adding code that needs a new string, decide up front which rule it falls un
- `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation β€” no permanent `uv tool install` needed. Environment variables (highest precedence first):
- `OH_AGENT_SERVER_LOCAL_PATH` β€” absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
- `OH_AGENT_SERVER_GIT_REF` β€” git commit SHA or branch name (takes precedence over version)
- - `OH_AGENT_SERVER_VERSION` β€” specific PyPI version (e.g., "1.26.0")
+ - `OH_AGENT_SERVER_VERSION` β€” specific PyPI version (e.g., "1.27.0")
- `OH_SECRET_KEY` β€” secret key for settings encryption; auto-generated and persisted to `~/.openhands/agent-canvas/secret-key.txt` on first run (same file Docker uses), ensuring dev mode and Docker share the same key when both mount the same `~/.openhands` directory. Override with the env var to pin a specific key.
- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β€” session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)
- - Default: released PyPI version `1.26.0` for agent-server SDK libraries
+ - Default: released PyPI version `1.27.0` for agent-server SDK libraries
- Security: `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:
- `SESSION_API_KEY` β€” 64-character hex (256-bit) for agent-server API authentication; persisted at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden via env var
diff --git a/__tests__/api/settings-service.test.ts b/__tests__/api/settings-service.test.ts
index 974bfe012e..c019571708 100644
--- a/__tests__/api/settings-service.test.ts
+++ b/__tests__/api/settings-service.test.ts
@@ -1,10 +1,8 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { http, HttpResponse } from "msw";
-import SettingsService, {
- DISABLED_SKILLS_STORAGE_KEY,
-} from "#/api/settings-service/settings-service.api";
-import { APP_PREFERENCES_STORAGE_KEY } from "#/api/app-preferences-store";
+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,
@@ -141,115 +139,215 @@ describe("SettingsService", () => {
fetchSpy.mockRestore();
});
- it("persists disabled_skills to localStorage and skips PATCH on a local backend", async () => {
- // The local agent-server has no endpoint for disabled_skills, so we store
- // them in localStorage instead and never send them in the PATCH body.
- const fetchSpy = vi.spyOn(SettingsService, "fetchSettingsFromApi");
+ it("sends disabled_skills under misc_settings_diff.app_preferences on a local backend", async () => {
+ // disabled_skills is one of the AppPreferences fields (along with
+ // language, git identity, …) and is persisted server-side under
+ // `PersistedSettings.misc_settings.app_preferences` since the
+ // misc_settings container was introduced as a follow-up to PR #3539.
+ const patchBodies: Array<Record<string, unknown>> = [];
+ server.use(
+ http.patch("*/api/settings", async ({ request }) => {
+ patchBodies.push((await request.json()) as Record<string, unknown>);
+ return HttpResponse.json({
+ agent_settings: {},
+ conversation_settings: {},
+ llm_api_key_is_set: false,
+ misc_settings: {
+ app_preferences: { disabled_skills: ["SSH Microagent"] },
+ },
+ });
+ }),
+ );
const result = await SettingsService.saveSettings({
disabled_skills: ["SSH Microagent"],
});
expect(result).toBe(true);
- // The PATCH must not be called β€” disabled_skills is not a server field.
- expect(fetchSpy).not.toHaveBeenCalled();
- // The value must be written to localStorage so getSettings can read it back.
- const raw = window.localStorage.getItem(DISABLED_SKILLS_STORAGE_KEY);
- expect(raw && JSON.parse(raw)).toEqual(["SSH Microagent"]);
-
- fetchSpy.mockRestore();
- });
-
- it("surfaces stored disabled_skills in getSettings on a local backend", async () => {
- // Pre-seed localStorage as if a previous save had persisted them.
- window.localStorage.setItem(
- DISABLED_SKILLS_STORAGE_KEY,
- JSON.stringify(["SSH Microagent"]),
- );
-
- const settings = await SettingsService.getSettings();
-
- expect(settings.disabled_skills).toEqual(["SSH Microagent"]);
+ expect(patchBodies).toEqual([
+ {
+ misc_settings_diff: {
+ app_preferences: { disabled_skills: ["SSH Microagent"] },
+ },
+ },
+ ]);
});
- it("persists app-level preferences to localStorage when saving on a local backend", async () => {
- // Arrange: no diffs, only the 5 app-level preference fields.
+ it("surfaces server-side misc_settings.app_preferences in getSettings on a local backend", async () => {
+ // The local agent-server returns app_preferences nested under
+ // `misc_settings` on GET /api/settings. The mock handler echoes whatever
+ // was last PATCH'd; seed it through the real save path so the round-trip
+ // matches production.
const appPrefs = {
language: "fr",
git_user_name: "Alice",
git_user_email: "[email protected]",
enable_sound_notifications: true,
user_consents_to_analytics: true,
+ disabled_skills: ["SSH Microagent"],
};
-
- // Act
await SettingsService.saveSettings(appPrefs);
+ SettingsService.invalidateCache();
- // Assert: localStorage holds the saved fields under the dedicated key.
- const raw = window.localStorage.getItem(APP_PREFERENCES_STORAGE_KEY);
- expect(raw && JSON.parse(raw)).toEqual(appPrefs);
- });
-
- it("surfaces stored app-level preferences in getSettings on a local backend", async () => {
- // Arrange: pre-seed localStorage as if a previous save had persisted them.
- const appPrefs = {
- language: "fr",
- git_user_name: "Alice",
- git_user_email: "[email protected]",
- enable_sound_notifications: true,
- user_consents_to_analytics: true,
- };
- window.localStorage.setItem(
- APP_PREFERENCES_STORAGE_KEY,
- JSON.stringify(appPrefs),
- );
-
- // Act
const settings = await SettingsService.getSettings();
- // Assert: each stored field is reflected on the returned Settings.
expect({
language: settings.language,
git_user_name: settings.git_user_name,
git_user_email: settings.git_user_email,
enable_sound_notifications: settings.enable_sound_notifications,
user_consents_to_analytics: settings.user_consents_to_analytics,
+ disabled_skills: settings.disabled_skills,
}).toEqual(appPrefs);
});
- it("excludes app-level fields from the local PATCH body when mixed with diffs", async () => {
- // Arrange: capture the PATCH body the local agent-server would receive.
- // The handler must echo a valid response so saveSettings does not throw.
- // Use "*" prefix to match both relative paths and absolute URLs (e.g.,
- // http://127.0.0.1:8000/api/...) when VITE_BACKEND_BASE_URL is configured.
+ it("routes app-level fields into misc_settings_diff when mixed with agent diffs", async () => {
const patchBodies: Array<Record<string, unknown>> = [];
server.use(
http.patch("*/api/settings", async ({ request }) => {
patchBodies.push((await request.json()) as Record<string, unknown>);
return HttpResponse.json({
- agent_settings: {},
+ agent_settings: { agent: "CodeActAgent" },
conversation_settings: {},
llm_api_key_is_set: false,
+ misc_settings: { app_preferences: { git_user_name: "Alice" } },
});
}),
);
- // Act: send both an agent diff and an app-level field in the same save.
await SettingsService.saveSettings({
git_user_name: "Alice",
agent_settings_diff: { agent: "CodeActAgent" },
});
- // Assert: the local backend only sees the diff; the app field is
- // confined to localStorage.
expect(patchBodies).toEqual([
- { agent_settings_diff: { agent: "CodeActAgent" } },
+ {
+ agent_settings_diff: { agent: "CodeActAgent" },
+ misc_settings_diff: { app_preferences: { git_user_name: "Alice" } },
+ },
]);
+ });
+
+ 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(
- JSON.parse(
- window.localStorage.getItem(APP_PREFERENCES_STORAGE_KEY) ?? "{}",
+ window.localStorage.getItem(
+ LEGACY_MIGRATION_KEYS.LEGACY_APP_PREFERENCES_KEY,
),
- ).toEqual({ git_user_name: "Alice" });
+ ).not.toBeNull();
});
it("forwards app-level preferences as flat top-level fields to the cloud save", async () => {
@@ -571,23 +669,18 @@ describe("SettingsService", () => {
}
});
- it("lets the cloud response override locally-stored app preferences", async () => {
- // Arrange: localStorage holds a stale "fr" while the cloud is the
- // authoritative source and returns "ja".
+ it("surfaces cloud app preferences on getSettings", async () => {
+ // The cloud returns app-preference fields flat at the top level
+ // (language, git identity, …) β€” they should land on the returned
+ // Settings unchanged.
setRegisteredBackends([cloudBackend]);
setActiveSelection({ backendId: cloudBackend.id });
- window.localStorage.setItem(
- APP_PREFERENCES_STORAGE_KEY,
- JSON.stringify({ language: "fr" }),
- );
mockFetchCloudSettings.mockResolvedValue({
language: "ja",
} as Partial<Settings>);
- // Act
const settings = await SettingsService.getSettings();
- // Assert: the server wins.
expect(settings.language).toBe("ja");
});
});
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 5d52723348..9bfc8e8638 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -389,16 +389,16 @@ describe("buildAgentServerCommand", () => {
// Defaults to the released PyPI version with all SDK packages pinned to same version
expect(cmd.args).toEqual([
"--from",
- "openhands-agent-server==1.26.0",
+ "openhands-agent-server==1.27.0",
"--with",
- "openhands-sdk==1.26.0",
+ "openhands-sdk==1.27.0",
"--with",
- "openhands-tools==1.26.0",
+ "openhands-tools==1.27.0",
"--with",
- "openhands-workspace==1.26.0",
+ "openhands-workspace==1.27.0",
"agent-server",
]);
- expect(cmd.source).toBe("PyPI (1.26.0, default)");
+ expect(cmd.source).toBe("PyPI (1.27.0, default)");
});
it("uses specific PyPI version when OH_AGENT_SERVER_VERSION is set with all packages pinned", () => {
diff --git a/config/defaults.json b/config/defaults.json
index f787546f8a..d8fc0c0939 100644
--- a/config/defaults.json
+++ b/config/defaults.json
@@ -2,7 +2,7 @@
"_comment": "Single source of truth for version pins, ports, paths, and defaults shared across the npm and Docker install paths. Read by scripts/dev-safe.mjs, scripts/dev-with-automation.mjs, docker/entrypoint.sh (via generated defaults.env), and .github/workflows/docker.yml.",
"versions": {
- "agentServer": "1.26.0",
+ "agentServer": "1.27.0",
"agentCanvas": "1.0.0-rc.3",
"automation": "1.0.0a6",
"automationSdk": "1.22.1",
diff --git a/scripts/check-sdk-version-sync.mjs b/scripts/check-sdk-version-sync.mjs
index 317b25d75f..582ef0c9aa 100644
--- a/scripts/check-sdk-version-sync.mjs
+++ b/scripts/check-sdk-version-sync.mjs
@@ -19,7 +19,7 @@
*
* Usage:
* node scripts/check-sdk-version-sync.mjs
- * EXPECTED_SDK_VERSION=1.26.0 node scripts/check-sdk-version-sync.mjs
+ * EXPECTED_SDK_VERSION=1.27.0 node scripts/check-sdk-version-sync.mjs
* node scripts/check-sdk-version-sync.mjs --check-pypi
*
* Environment variables:
@@ -79,7 +79,7 @@ Triggering from other repos:
-H "Authorization: token \$GITHUB_TOKEN" \\
-H "Accept: application/vnd.github.v3+json" \\
https://api.github.com/repos/OpenHands/agent-canvas/dispatches \\
- -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.26.0"}}'
+ -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.27.0"}}'
`);
process.exit(0);
}
@@ -268,9 +268,9 @@ async function fetchPyPIDependencies(packageName, version) {
* Parse PyPI requires_dist array and extract SDK package versions
*
* PyPI returns dependencies in PEP 508 format like:
- * "openhands-sdk>=1.26.0,<2.0.0"
- * "openhands-tools==1.26.0"
- * "openhands-workspace (>=1.26.0)"
+ * "openhands-sdk>=1.27.0,<2.0.0"
+ * "openhands-tools==1.27.0"
+ * "openhands-workspace (>=1.27.0)"
*/
function parseSdkVersionsFromRequiresDist(requiresDist) {
const versions = {};
@@ -284,7 +284,7 @@ function parseSdkVersionsFromRequiresDist(requiresDist) {
}
// Extract the version number - look for patterns like:
- // ">=1.26.0", "==1.26.0", "(>=1.26.0)", "~=1.26.0"
+ // ">=1.27.0", "==1.27.0", "(>=1.27.0)", "~=1.27.0"
// After the package name and before any comma or closing paren
const versionPattern = /[><=~!]+\s*([0-9]+(?:\.[0-9]+)*)/;
const match = dep.match(versionPattern);
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 910dafe3f5..cac5b7ebc8 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -394,7 +394,7 @@ export function validateFrontendDependencies(
* edits are picked up without a manual reinstall. The agent-server itself
* is rebuilt from local source on each invocation (--reinstall).
* - OH_AGENT_SERVER_GIT_REF: Git commit SHA or branch name
- * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.26.0")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.27.0")
*
* If none are set, defaults to the released version specified by
* DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a
diff --git a/src/api/app-preferences-store.ts b/src/api/app-preferences-store.ts
deleted file mode 100644
index 3781b01e60..0000000000
--- a/src/api/app-preferences-store.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-import { Settings } from "#/types/settings";
-
-/**
- * The local agent-server's PATCH /api/settings only persists
- * `agent_settings_diff` and `conversation_settings_diff`. App-level user
- * preferences (language, sound notifications, analytics consent, git
- * identity) have no native home in that schema, so we persist them in
- * localStorage as a workaround. This is the same fallback pattern used
- * by `DISABLED_SKILLS_STORAGE_KEY` in `settings-service.api.ts`.
- *
- * In cloud mode the cloud backend accepts these fields as flat top-level
- * keys at POST /api/v1/settings, and the cloud fetch returns them. We
- * still write through to localStorage so the values survive momentary
- * fetch failures and so the merge logic in `syncDerivedSettings` has a
- * single source for both modes.
- *
- * Long-term goal: extend the local agent-server settings schema to cover
- * these fields and delete this module entirely.
- */
-export const APP_PREFERENCES_STORAGE_KEY =
- "openhands-agent-server-app-preferences";
-
-export const APP_PREFERENCE_FIELDS = [
- "language",
- "user_consents_to_analytics",
- "enable_sound_notifications",
- "git_user_name",
- "git_user_email",
-] as const;
-
-export type AppPreferenceField = (typeof APP_PREFERENCE_FIELDS)[number];
-
-export type StoredAppPreferences = Partial<Pick<Settings, AppPreferenceField>>;
-
-const APP_PREFERENCE_FIELD_SET: ReadonlySet<string> = new Set(
- APP_PREFERENCE_FIELDS,
-);
-
-const isAppPreferenceField = (key: string): key is AppPreferenceField =>
- APP_PREFERENCE_FIELD_SET.has(key);
-
-const coerceValue = (
- key: AppPreferenceField,
- value: unknown,
-): StoredAppPreferences[AppPreferenceField] | undefined => {
- switch (key) {
- case "language":
- case "git_user_name":
- case "git_user_email":
- return typeof value === "string" ? value : undefined;
- case "enable_sound_notifications":
- return typeof value === "boolean" ? value : undefined;
- case "user_consents_to_analytics":
- if (value === null) return null;
- return typeof value === "boolean" ? value : undefined;
- default:
- return undefined;
- }
-};
-
-const sanitize = (input: Record<string, unknown>): StoredAppPreferences => {
- const out: StoredAppPreferences = {};
- for (const key of APP_PREFERENCE_FIELDS) {
- if (key in input) {
- const coerced = coerceValue(key, input[key]);
- if (coerced !== undefined) {
- // TS can't narrow per-key writes through a discriminated assignment,
- // so funnel through a single record write.
- (out as Record<string, unknown>)[key] = coerced;
- }
- }
- }
- return out;
-};
-
-export const readStoredAppPreferences = (): StoredAppPreferences => {
- if (typeof window === "undefined") {
- return {};
- }
-
- try {
- const raw = window.localStorage.getItem(APP_PREFERENCES_STORAGE_KEY);
- if (!raw) return {};
- const parsed = JSON.parse(raw) as unknown;
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
- return {};
- }
- return sanitize(parsed as Record<string, unknown>);
- } catch {
- return {};
- }
-};
-
-export const writeStoredAppPreferences = (
- partial: StoredAppPreferences,
-): void => {
- if (typeof window === "undefined") return;
-
- const sanitized = sanitize(partial as Record<string, unknown>);
- const existing = readStoredAppPreferences();
- const merged: StoredAppPreferences = { ...existing, ...sanitized };
-
- if (Object.keys(merged).length === 0) {
- window.localStorage.removeItem(APP_PREFERENCES_STORAGE_KEY);
- return;
- }
-
- window.localStorage.setItem(
- APP_PREFERENCES_STORAGE_KEY,
- JSON.stringify(merged),
- );
-};
-
-export const clearStoredAppPreferences = (): void => {
- if (typeof window === "undefined") return;
- window.localStorage.removeItem(APP_PREFERENCES_STORAGE_KEY);
-};
-
-/**
- * Split known app-preference keys out of a save payload. Used by
- * `SettingsService.saveSettings` so the local PATCH only ever sees the
- * diff fields the agent-server accepts.
- */
-export const extractAppPreferences = (
- input: Record<string, unknown>,
-): { extracted: StoredAppPreferences; rest: Record<string, unknown> } => {
- const extracted: StoredAppPreferences = {};
- const rest: Record<string, unknown> = {};
-
- for (const [key, value] of Object.entries(input)) {
- if (isAppPreferenceField(key)) {
- const coerced = coerceValue(key, value);
- if (coerced !== undefined) {
- (extracted as Record<string, unknown>)[key] = coerced;
- }
- } else {
- rest[key] = value;
- }
- }
-
- return { extracted, rest };
-};
diff --git a/src/api/cloud/settings-service.api.ts b/src/api/cloud/settings-service.api.ts
index 5e3bb80e4a..8059a8f587 100644
--- a/src/api/cloud/settings-service.api.ts
+++ b/src/api/cloud/settings-service.api.ts
@@ -4,7 +4,7 @@ import {
type Settings,
type SettingsValue,
} from "#/types/settings";
-import { type StoredAppPreferences } from "../app-preferences-store";
+import { type AppPreferences } from "../settings-service/settings-service.api";
import { getActiveBackend } from "../backend-registry/active-store";
import type { Backend } from "../backend-registry/types";
import { callCloudProxy } from "./proxy";
@@ -149,8 +149,18 @@ export async function fetchCloudSettings(): Promise<Partial<Settings>> {
export async function saveCloudSettings(diff: {
agent_settings_diff?: Record<string, SettingsValue>;
conversation_settings_diff?: Record<string, SettingsValue>;
- disabled_skills?: string[];
- app_preferences?: StoredAppPreferences;
+ /**
+ * App-level user preferences (language, sound notifications, disabled
+ * skills, …). The cloud `POST /api/v1/settings` consumes these as flat
+ * top-level fields, so this helper iterates the object and assigns each
+ * key onto the request body.
+ *
+ * Note: `app_preferences.disabled_skills` is the canonical source for the
+ * skill list since `AppPreferences` was unified in agent-server 1.27.
+ * Callers that still pass `disabled_skills` separately should migrate to
+ * setting it under `app_preferences` instead.
+ */
+ app_preferences?: AppPreferences;
}): Promise<void> {
const backend = getActiveCloudBackend();
const body: Record<string, unknown> = {};
@@ -176,17 +186,18 @@ export async function saveCloudSettings(diff: {
) {
body.conversation_settings_diff = diff.conversation_settings_diff;
}
- // Use !== undefined so re-enabling every skill (empty array) round-trips.
- if (diff.disabled_skills !== undefined) {
- body.disabled_skills = diff.disabled_skills;
- }
- // Flat top-level app-preference fields (language, git_user_name, …).
- // The cloud POST /api/v1/settings stores these directly; see
- // `CloudSettingsResponse` and the MSW handler in
- // `src/mocks/settings-handlers.ts` for the accepted shape.
+ // Flat top-level app-preference fields (language, git_user_name,
+ // disabled_skills, …). The cloud POST /api/v1/settings stores these
+ // directly; see `CloudSettingsResponse` and the MSW handler in
+ // `src/mocks/settings-handlers.ts` for the accepted shape. `undefined`
+ // values are skipped so the cloud server keeps the prior value; `null`
+ // and empty arrays (e.g. re-enabling every skill) round-trip as
+ // explicit clears.
if (diff.app_preferences) {
for (const [key, value] of Object.entries(diff.app_preferences)) {
- body[key] = value;
+ if (value !== undefined) {
+ body[key] = value;
+ }
}
}
await callCloudProxy<unknown>({
diff --git a/src/api/settings-service/legacy-app-preferences-migration.ts b/src/api/settings-service/legacy-app-preferences-migration.ts
new file mode 100644
index 0000000000..fe68d05ded
--- /dev/null
+++ b/src/api/settings-service/legacy-app-preferences-migration.ts
@@ -0,0 +1,136 @@
+/**
+ * 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 f2e60b23b4..fa4582bd8f 100644
--- a/src/api/settings-service/settings-service.api.ts
+++ b/src/api/settings-service/settings-service.api.ts
@@ -1,11 +1,6 @@
import { SettingsClient } from "@openhands/typescript-client/clients";
import { DEFAULT_SETTINGS } from "#/services/settings";
import { Settings, SettingsSchema, SettingsValue } from "#/types/settings";
-import {
- extractAppPreferences,
- readStoredAppPreferences,
- writeStoredAppPreferences,
-} from "../app-preferences-store";
import { getActiveBackend } from "../backend-registry/active-store";
import {
fetchCloudConversationSettingsSchema,
@@ -14,26 +9,103 @@ 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
+ * SDK `openhands.sdk.settings.AppPreferences`). Mirrored here as a flat
+ * partial of Settings so the rest of the frontend can keep treating them as
+ * top-level keys (`settings.language`, `settings.disabled_skills`, …).
+ */
+export const APP_PREFERENCE_FIELDS = [
+ "language",
+ "user_consents_to_analytics",
+ "enable_sound_notifications",
+ "git_user_name",
+ "git_user_email",
+ "disabled_skills",
+] as const;
+
+export type AppPreferenceField = (typeof APP_PREFERENCE_FIELDS)[number];
+
+export type AppPreferences = Partial<Pick<Settings, AppPreferenceField>>;
+
+/**
+ * Container for frontend-owned settings the agent doesn't interpret.
+ * Mirrors the SDK `MiscSettings` model introduced in agent-server 1.27.
+ *
+ * Single nested category today (`app_preferences`). Adding a future
+ * category (e.g. `ui_preferences`) is a non-breaking change for the wire
+ * shape β€” it just adds another optional sibling here.
+ */
+export interface MiscSettings {
+ app_preferences?: AppPreferences;
+}
/**
* Response from GET /api/settings
- * Mirrors the SettingsResponse model in the agent server
+ * Mirrors the SettingsResponse model in the agent server.
*/
export interface SettingsApiResponse {
agent_settings: Record<string, SettingsValue>;
conversation_settings: Record<string, SettingsValue>;
llm_api_key_is_set: boolean;
+ /**
+ * Frontend-owned settings the agent does not interpret (currently just
+ * `app_preferences`). Added in agent-server 1.27; earlier servers omit
+ * the field entirely, in which case the frontend falls back to defaults.
+ */
+ misc_settings?: MiscSettings;
}
/**
- * Request payload for PATCH /api/settings
+ * Request payload for PATCH /api/settings.
+ *
+ * `misc_settings_diff` is deep-merged into the persisted `misc_settings`
+ * block, matching the semantics of `agent_settings_diff` /
+ * `conversation_settings_diff`. A partial diff like
+ * `{ app_preferences: { language: "fr" } }` updates only `language` and
+ * leaves every other `app_preferences` field alone. Lists
+ * (`disabled_skills`) are replaced wholesale rather than merged.
*/
export interface SettingsUpdateRequest {
agent_settings_diff?: Record<string, SettingsValue>;
conversation_settings_diff?: Record<string, SettingsValue>;
- disabled_skills?: string[];
+ misc_settings_diff?: MiscSettings;
+ // Permit additional keys so this stays assignable to the underlying
+ // typescript-client SDK type, which uses `[key: string]: unknown` for
+ // forward compatibility.
+ [key: string]: unknown;
}
+const APP_PREFERENCE_FIELD_SET: ReadonlySet<string> = new Set(
+ APP_PREFERENCE_FIELDS,
+);
+
+const isAppPreferenceField = (key: string): key is AppPreferenceField =>
+ APP_PREFERENCE_FIELD_SET.has(key);
+
+/**
+ * Split known app-preference keys out of a save payload so callers can
+ * route them through `misc_settings_diff.app_preferences` (local) or as
+ * flat top-level keys (cloud), while the remaining fields flow into the
+ * `agent_settings_diff` / `conversation_settings_diff` branches.
+ */
+const extractAppPreferences = (
+ input: Record<string, unknown>,
+): { extracted: AppPreferences; rest: Record<string, unknown> } => {
+ const extracted: AppPreferences = {};
+ const rest: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(input)) {
+ if (isAppPreferenceField(key)) {
+ (extracted as Record<string, unknown>)[key] = value;
+ } else {
+ rest[key] = value;
+ }
+ }
+ return { extracted, rest };
+};
+
/**
* Secret exposure mode for X-Expose-Secrets header.
*
@@ -45,36 +117,6 @@ export type ExposeSecretsMode = "encrypted" | "plaintext" | undefined;
const deepClone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
-// disabled_skills is not persisted by the local agent-server, so we mirror
-// the app-preferences pattern: write to localStorage on save, read back on fetch.
-export const DISABLED_SKILLS_STORAGE_KEY =
- "openhands-agent-server-disabled-skills";
-
-const readStoredDisabledSkills = (): string[] | null => {
- if (typeof window === "undefined") return null;
- try {
- const raw = window.localStorage.getItem(DISABLED_SKILLS_STORAGE_KEY);
- if (!raw) return null;
- const parsed: unknown = JSON.parse(raw);
- if (!Array.isArray(parsed)) return null;
- return parsed.filter((v): v is string => typeof v === "string");
- } catch {
- return null;
- }
-};
-
-const writeStoredDisabledSkills = (skills: string[]): void => {
- if (typeof window === "undefined") return;
- try {
- window.localStorage.setItem(
- DISABLED_SKILLS_STORAGE_KEY,
- JSON.stringify(skills),
- );
- } catch {
- // ignore write failures (e.g. private-browsing quota exceeded)
- }
-};
-
const mergeRecords = (
base: Record<string, SettingsValue> | null | undefined,
next: Record<string, SettingsValue> | null | undefined,
@@ -147,11 +189,22 @@ const transformApiResponse = (
llm_api_key_set: response.llm_api_key_is_set,
};
- // The local agent-server never returns disabled_skills; read it from
- // localStorage where saveSettings writes it for local-mode clients.
- const stored = readStoredDisabledSkills();
- if (stored !== null) {
- partial.disabled_skills = stored;
+ // App-level user preferences come back nested under
+ // `misc_settings.app_preferences` from the local agent-server (added in
+ // 1.27, restructured into the `misc_settings` container in the follow-up
+ // refactor). Hoist them onto the flat Settings shape the rest of the
+ // frontend already speaks. Older servers omit the `misc_settings` field
+ // entirely; the migration helper invoked from `getSettings` promotes any
+ // leftover localStorage values to the server on first run, so the omitted
+ // case just falls back to defaults.
+ const prefs = response.misc_settings?.app_preferences;
+ if (prefs) {
+ for (const key of APP_PREFERENCE_FIELDS) {
+ const value = prefs[key];
+ if (value !== undefined) {
+ (partial as Record<string, unknown>)[key] = value;
+ }
+ }
}
return partial;
@@ -171,14 +224,8 @@ const syncDerivedSettings = (settings: Partial<Settings>): Settings => {
settings.conversation_settings ?? {},
);
- // App-level user preferences (language, git identity, sound notifications,
- // analytics consent) live in localStorage in local mode. In cloud mode the
- // server response carries them and overrides the local cache.
- const storedAppPrefs = readStoredAppPreferences();
-
const merged = {
...deepClone(DEFAULT_SETTINGS),
- ...storedAppPrefs,
...settings,
provider_tokens_set: {
...(DEFAULT_SETTINGS.provider_tokens_set ?? {}),
@@ -280,7 +327,23 @@ class SettingsService {
}
try {
- const response = await this.fetchSettingsFromApi();
+ 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();
+ }
settingsCache.redacted = response;
settingsCache.timestamp = Date.now();
return syncDerivedSettings(transformApiResponse(response));
@@ -353,17 +416,15 @@ class SettingsService {
settings: Partial<Settings> & Record<string, unknown>,
): Promise<boolean> {
// Split app-level user-preference fields (language, git identity, sound
- // notifications, analytics consent) off before building the diff payload.
- // The local agent-server's PATCH /api/settings has no schema for these
- // and Pydantic would drop them silently; persist them in localStorage
- // instead, and forward them as flat top-level keys to the cloud POST.
+ // notifications, analytics consent, disabled_skills) off and route them
+ // through `misc_settings_diff.app_preferences` (local) or as flat
+ // top-level keys (cloud). The local agent-server stores them under
+ // `PersistedSettings.misc_settings.app_preferences`; the cloud accepts
+ // them as flat keys on `POST /api/v1/settings`.
const { extracted: appPreferences, rest } = extractAppPreferences(
settings as Record<string, unknown>,
);
const hasAppPreferences = Object.keys(appPreferences).length > 0;
- if (hasAppPreferences) {
- writeStoredAppPreferences(appPreferences);
- }
const payload: SettingsUpdateRequest = {};
@@ -386,10 +447,8 @@ class SettingsService {
payload.conversation_settings_diff = conversationSettingsDiff;
}
- // Extract disabled_skills (cloud-only β€” local agent-server has no skills concept)
- const disabledSkills = rest.disabled_skills as string[] | undefined;
- if (Array.isArray(disabledSkills)) {
- payload.disabled_skills = disabledSkills;
+ if (hasAppPreferences) {
+ payload.misc_settings_diff = { app_preferences: appPreferences };
}
const isCloud = getActiveBackend().backend.kind === "cloud";
@@ -455,7 +514,6 @@ class SettingsService {
const hasCloudWork =
!!payload.agent_settings_diff ||
!!payload.conversation_settings_diff ||
- payload.disabled_skills !== undefined ||
hasAppPreferences;
if (!hasCloudWork) {
return true;
@@ -467,13 +525,25 @@ class SettingsService {
}),
);
}
+ // Build the cloud payload from the same diffs, but as a separate
+ // object so undefined keys don't appear in the call (saveCloudSettings
+ // is called from tests with an exact-shape assertion).
+ const cloudPayload: Parameters<typeof saveCloudSettings>[0] = {};
+ if (payload.agent_settings_diff) {
+ cloudPayload.agent_settings_diff = payload.agent_settings_diff;
+ }
+ if (payload.conversation_settings_diff) {
+ cloudPayload.conversation_settings_diff =
+ payload.conversation_settings_diff;
+ }
+ if (hasAppPreferences) {
+ // The cloud `POST /api/v1/settings` takes app-preference fields as
+ // flat top-level keys (not under `app_preferences_diff`).
+ // `saveCloudSettings` re-flattens them onto the request body.
+ cloudPayload.app_preferences = appPreferences;
+ }
try {
- await withRetry(() =>
- saveCloudSettings({
- ...payload,
- ...(hasAppPreferences ? { app_preferences: appPreferences } : {}),
- }),
- );
+ await withRetry(() => saveCloudSettings(cloudPayload));
} catch (err) {
if (needsMcpPreClear && mcpConfigSnapshot) {
// Best-effort rollback. We deliberately do not wrap in withRetry:
@@ -493,24 +563,13 @@ class SettingsService {
throw err;
}
} else {
- // The local agent-server PATCH /api/settings rejects unknown fields and
- // requires at least one of the two diff fields. Strip disabled_skills
- // and skip the request entirely if no diffs remain. App preferences
- // are persisted to localStorage above and never sent to this endpoint.
- if (Array.isArray(disabledSkills)) {
- writeStoredDisabledSkills(disabledSkills);
- }
- const localPayload = { ...payload };
- delete localPayload.disabled_skills;
+ // The local agent-server PATCH /api/settings requires at least one of
+ // the three diff fields. Skip the request entirely if nothing changed.
const hasLocalDiffs =
- !!localPayload.agent_settings_diff ||
- !!localPayload.conversation_settings_diff;
+ !!payload.agent_settings_diff ||
+ !!payload.conversation_settings_diff ||
+ !!payload.misc_settings_diff;
if (!hasLocalDiffs) {
- if (hasAppPreferences) {
- // The localStorage write changed user-visible settings; clear the
- // in-memory cache so the next getSettings() re-derives from disk.
- clearCache();
- }
return true;
}
if (needsMcpPreClear) {
@@ -523,7 +582,7 @@ class SettingsService {
try {
await withRetry(() =>
new SettingsClient(getAgentServerClientOptions()).updateSettings(
- localPayload,
+ payload,
),
);
} catch (err) {
diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.ts
index f1a3491ff2..67d01c0984 100644
--- a/src/mocks/settings-handlers.ts
+++ b/src/mocks/settings-handlers.ts
@@ -878,11 +878,21 @@ export const SETTINGS_HANDLERS = [
await delay();
const { settings } = MOCK_USER_PREFERENCES;
+ const DEFAULT_APP_PREFERENCES = {
+ language: null,
+ user_consents_to_analytics: null,
+ enable_sound_notifications: null,
+ git_user_name: null,
+ git_user_email: null,
+ disabled_skills: [],
+ };
+
if (!settings) {
return HttpResponse.json({
agent_settings: {},
conversation_settings: {},
llm_api_key_is_set: false,
+ misc_settings: { app_preferences: DEFAULT_APP_PREFERENCES },
});
}
@@ -916,10 +926,22 @@ export const SETTINGS_HANDLERS = [
>
)?.api_key);
+ // Reuse the persisted misc_settings.app_preferences for repeat fetches,
+ // but always fall back to the default-empty block so the GUI sees a
+ // deterministic shape on first read.
+ const storedMisc = (settings as Record<string, unknown>).misc_settings as
+ | { app_preferences?: Record<string, unknown> }
+ | undefined;
+ const appPreferences = {
+ ...DEFAULT_APP_PREFERENCES,
+ ...(storedMisc?.app_preferences ?? {}),
+ };
+
return HttpResponse.json({
agent_settings: agentSettings,
conversation_settings: settings.conversation_settings ?? {},
llm_api_key_is_set: llmApiKeySet,
+ misc_settings: { app_preferences: appPreferences },
});
}),
@@ -929,17 +951,24 @@ export const SETTINGS_HANDLERS = [
const body = (await request.json()) as {
agent_settings_diff?: Record<string, unknown>;
conversation_settings_diff?: Record<string, SettingsValue>;
+ misc_settings_diff?: {
+ app_preferences?: Record<string, unknown>;
+ };
} | null;
if (!body) {
return HttpResponse.json({ error: "Empty body" }, { status: 400 });
}
- if (!body.agent_settings_diff && !body.conversation_settings_diff) {
+ if (
+ !body.agent_settings_diff &&
+ !body.conversation_settings_diff &&
+ !body.misc_settings_diff
+ ) {
return HttpResponse.json(
{
error:
- "At least one of agent_settings_diff or conversation_settings_diff must be provided",
+ "At least one of agent_settings_diff, conversation_settings_diff, or misc_settings_diff must be provided",
},
{ status: 400 },
);
@@ -975,6 +1004,27 @@ export const SETTINGS_HANDLERS = [
};
}
+ if (body.misc_settings_diff) {
+ const existingMisc = (current as Record<string, unknown>)
+ .misc_settings as
+ | { app_preferences?: Record<string, unknown> }
+ | undefined;
+ // Deep-merge: nested `app_preferences` overlays field-by-field;
+ // `disabled_skills` lists are replaced wholesale. This mirrors the
+ // SDK's `_deep_merge` behaviour for the two-level shape currently
+ // stored in `misc_settings`.
+ const nextMisc: { app_preferences?: Record<string, unknown> } = {
+ ...(existingMisc ?? {}),
+ };
+ if (body.misc_settings_diff.app_preferences) {
+ nextMisc.app_preferences = {
+ ...(existingMisc?.app_preferences ?? {}),
+ ...body.misc_settings_diff.app_preferences,
+ };
+ }
+ (nextSettings as Record<string, unknown>).misc_settings = nextMisc;
+ }
+
MOCK_USER_PREFERENCES.settings = nextSettings;
// Return the updated settings (without secrets exposed)
@@ -982,6 +1032,10 @@ export const SETTINGS_HANDLERS = [
agent_settings: nextSettings.agent_settings ?? {},
conversation_settings: nextSettings.conversation_settings ?? {},
llm_api_key_is_set: nextSettings.llm_api_key_set ?? false,
+ misc_settings: ((nextSettings as Record<string, unknown>)
+ .misc_settings as
+ | { app_preferences?: Record<string, unknown> }
+ | undefined) ?? { app_preferences: {} },
});
}),
diff --git a/tests/e2e/mock-llm/mock-llm-folder-workspace.spec.ts b/tests/e2e/mock-llm/mock-llm-folder-workspace.spec.ts
index b8a594d79d..e7ab7cd5e7 100644
--- a/tests/e2e/mock-llm/mock-llm-folder-workspace.spec.ts
+++ b/tests/e2e/mock-llm/mock-llm-folder-workspace.spec.ts
@@ -160,6 +160,14 @@ test.describe("mock-LLM folder browser β†’ workspace β†’ conversation", () => {
const upBtn = page.getByTestId("folder-browser-up");
const currentPathEl = page.getByTestId("folder-browser-current-path");
+ // Wait for the modal to finish initializing. `currentPath` starts as
+ // null (rendering an empty path and a disabled up button) until
+ // useHomeDirectory resolves and seeds the home path via useEffect.
+ // Without this wait the while-loop below can see the briefly-disabled
+ // up button and exit immediately, leaving us stuck at home instead of
+ // navigating to root.
+ await expect(currentPathEl).not.toHaveText("", { timeout: 10_000 });
+
// Keep clicking up until the button becomes disabled (at root).
while (!(await upBtn.isDisabled())) {
await upBtn.click();