Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(settings): scope local settings cache by backend (#16958)

Engel Nystbe2b0867a744
diff --git a/.pr/settings-verification-2026-10-09/README.md b/.pr/settings-verification-2026-10-09/README.md
new file mode 100644
index 0000000000..fe5620e983
--- /dev/null
+++ b/.pr/settings-verification-2026-10-09/README.md
@@ -0,0 +1,116 @@
+# Settings verification β€” 9 October 2026
+
+Verified executable source: `57530c7664cc02c4715f84610618a1c504ab6082` (#16958).
+Baseline: `95dcdcdf12bd78f02c52b80cccf2f5f4f35242a4` (main).
+Both used isolated production `bin/agent-canvas.mjs` stacks, real Agent Server/SDK
+1.53.0, the pinned Automation service, Node 25.9.0, installed Google Chrome,
+English UI, and 1440Γ—1000 viewports. Doctor confirmed authenticated settings,
+unauthenticated rejection, compatible server versions, build inputs and Automation
+health before driving. No API response or model response was mocked.
+
+## Result
+
+**Independent encrypted expiry: reproduced on main, corrected by the PR.**
+After a newer display-settings read, main reused an expired encrypted entry and
+created a conversation with `max_iterations=1`. The PR fetched encrypted settings
+again and created it with the real server's current `max_iterations=2`. Both
+conversation POSTs returned 201; GET of each created conversation returned the
+persisted limits shown in the original CLI outputs:
+[main](conversation-limit-main.json), [PR](conversation-limit-head.json).
+
+The display-settings expiry and Git identity round-trip passed on both versions.
+The two display screenshots show that common passing step, not a fabricated
+before/after difference.
+
+## TTL reproduction
+
+A controlled browser `Date` was fixed at the times below using the documented
+`browser clock --fixed` command. Server time was unchanged; browser reload was
+used only at initialization, not between cache reads.
+
+| Browser time | Real action |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 00:00:00 | Reload after arranging Git identity `QA cache original` and `max_iterations=1`; open Application settings to populate display settings. |
+| 00:01:00 | New Chat β†’ submit `QA cache verification. Do not run any tools.`; the normal creation path populates encrypted settings. |
+| 00:01:00 | API PATCH changes the server's Git identity to `QA cache updated`, without invalidating the page's caches. |
+| 00:05:01 | Navigate through the sidebar to Settings β†’ Application; display settings refresh and show the updated Git identity on both versions. |
+| 00:05:01 | API PATCH changes the server's conversation limit to 2, without invalidating the page's caches. |
+| 00:06:01 | New Chat β†’ submit `QA independent encrypted expiry. Do not run any tools.`; the encrypted entry is now older than five minutes, while display settings are fresh. |
+| 00:06:01 | Read the created conversation's actual `max_iterations`: main 1, PR 2. |
+
+The profile was named `qa-cache`, with a dummy key, `openai/gpt-4o-mini`, and
+`http://127.0.0.1:9/v1` as its base URL, saved with `llm set --no-validate`.
+It deliberately cannot execute a model. Completion failures are expected and are
+not a test result. This check exercises the real settings/encryption and
+conversation-creation boundary; it makes no LLM, tool-execution, or provider claim.
+
+Use a fresh isolated run on each revision. The relevant reproducible commands are:
+
+```sh
+export PATH="$PWD/.agents/skills/verify-openhands/scripts:$PATH"
+control-openhands launch --new --print-run
+# Export the exact returned path as OH_VERIFY_RUN; run doctor and onboard --skip.
+QA_SETTINGS_DUMMY_KEY=qa-only-not-a-real-credential control-openhands llm set \
+ --profile qa-cache --model openai/gpt-4o-mini \
+ --base-url http://127.0.0.1:9/v1 --api-key-env QA_SETTINGS_DUMMY_KEY --no-validate
+control-openhands api PATCH /api/settings --write --data \
+ '{"misc_settings_diff":{"app_preferences":{"git_user_name":"QA cache original","git_user_email":"[email protected]","user_consents_to_analytics":false}},"conversation_settings_diff":{"max_iterations":1}}'
+control-openhands browser clock --fixed 2026-10-10T00:00:00Z
+control-openhands browser reload
+control-openhands browser click 'testid=backend-selector-settings-link' --expect-url /settings
+control-openhands browser click 'testid=sidebar-settings-/settings/app' --expect-url /settings/app
+control-openhands browser clock --fixed 2026-10-10T00:01:00Z
+control-openhands browser click 'role=link[name="New Chat"]' --expect-url /conversations
+control-openhands browser fill 'testid=chat-input' 'QA cache verification. Do not run any tools.'
+control-openhands browser click 'testid=submit-button' --expect-url '/conversations/[^?]+'
+control-openhands api PATCH /api/settings --write --data \
+ '{"misc_settings_diff":{"app_preferences":{"git_user_name":"QA cache updated"}}}'
+control-openhands browser clock --fixed 2026-10-10T00:05:01Z
+control-openhands browser click 'testid=backend-selector-settings-link' --expect-url /settings
+control-openhands browser click 'testid=sidebar-settings-/settings/app' --expect-url /settings/app
+control-openhands browser value 'testid=git-user-name-input'
+control-openhands api PATCH /api/settings --write --data \
+ '{"conversation_settings_diff":{"max_iterations":2}}'
+control-openhands browser clock --fixed 2026-10-10T00:06:01Z
+control-openhands browser click 'role=link[name="New Chat"]' --expect-url /conversations
+control-openhands browser fill 'testid=chat-input' 'QA independent encrypted expiry. Do not run any tools.'
+control-openhands browser click 'testid=submit-button' --expect-url '/conversations/[^?]+'
+# Read the new ID from browser url, then:
+control-openhands api GET /api/conversations/<id> --pick max_iterations
+```
+
+## Reviewed captures
+
+- Main: [warm/read/refetch video](ttl-main-warm-and-refresh.mp4), [encrypted-expiry video](ttl-main-encrypted-expiry.mp4).
+- PR: [warm/read/refetch video](ttl-head-warm-and-refresh.mp4), [encrypted-expiry video](ttl-head-encrypted-expiry.mp4).
+- [Main display refresh](display-main-refreshed.png), [PR display refresh](display-head-refreshed.png).
+
+Videos show real UI actions; the safe original API outputs establish the persisted
+conversation limit. The clock changes and out-of-band fixture writes are stated
+above rather than disguised as real elapsed time. GIFs are previews of the same
+recordings. Raw logs, downloaded trajectories, storage, and session keys are not
+published.
+
+## Retry protection and other limits
+
+The PR's live outage test stopped only its owned Agent Server, entered Application
+settings, and selected a healthy second real backend during settings retries.
+Its original request still made three attempts to the original origin, including
+two after the new backend's successful settings read. See the actual
+[request timeline](head-pinned-retry-network.json) and [video](head-pinned-retry.mp4).
+The deterministic pinned-retry regression test fails against main and passes with
+this implementation. Baseline UI timing did not reproduce a redirected retry in
+the live attempts, so this remains defensive retry protection, not a claimed
+live before/after retry defect.
+
+Returning A β†’ B β†’ A while leaving the Application form mounted retains the prior
+form's input value on both main and the PR. Navigating to Secrets and back remounts
+the form and shows the correct backend data. This is an existing form-state
+limitation, not evidence that the PR cache mixes backend settings.
+
+Cloud/account flows, live LLM completion and other agent execution were outside
+this settings-cache check. Existing focused and full CI tests cover the shared
+service and its consumers. All owned settings stacks were stopped and their ports
+confirmed closed; private state was purged while these artifacts were retained.
+
+Verification performed by an AI agent for Engel Nyst (@enyst).
diff --git a/.pr/settings-verification-2026-10-09/conversation-limit-head.json b/.pr/settings-verification-2026-10-09/conversation-limit-head.json
new file mode 100644
index 0000000000..0c37b578a1
--- /dev/null
+++ b/.pr/settings-verification-2026-10-09/conversation-limit-head.json
@@ -0,0 +1,6 @@
+{
+ "ok": true,
+ "status": 200,
+ "pick": "max_iterations",
+ "value": 2
+}
diff --git a/.pr/settings-verification-2026-10-09/conversation-limit-main.json b/.pr/settings-verification-2026-10-09/conversation-limit-main.json
new file mode 100644
index 0000000000..0764c29852
--- /dev/null
+++ b/.pr/settings-verification-2026-10-09/conversation-limit-main.json
@@ -0,0 +1,6 @@
+{
+ "ok": true,
+ "status": 200,
+ "pick": "max_iterations",
+ "value": 1
+}
diff --git a/.pr/settings-verification-2026-10-09/display-head-refreshed.png b/.pr/settings-verification-2026-10-09/display-head-refreshed.png
new file mode 100644
index 0000000000..2ec3db046f
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/display-head-refreshed.png differ
diff --git a/.pr/settings-verification-2026-10-09/display-main-refreshed.png b/.pr/settings-verification-2026-10-09/display-main-refreshed.png
new file mode 100644
index 0000000000..d180dd6603
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/display-main-refreshed.png differ
diff --git a/.pr/settings-verification-2026-10-09/head-pinned-retry-network.json b/.pr/settings-verification-2026-10-09/head-pinned-retry-network.json
new file mode 100644
index 0000000000..f324592ad2
--- /dev/null
+++ b/.pr/settings-verification-2026-10-09/head-pinned-retry-network.json
@@ -0,0 +1,73 @@
+{
+ "ok": true,
+ "total": 7,
+ "byOrigin": {
+ "http://127.0.0.1:18900": 6,
+ "http://127.0.0.1:18910": 1
+ },
+ "recent": [
+ {
+ "ts": "2026-10-09T19:36:28.453Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 200
+ },
+ {
+ "ts": "2026-10-09T19:36:28.761Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 502
+ },
+ {
+ "ts": "2026-10-09T19:36:29.062Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 502
+ },
+ {
+ "ts": "2026-10-09T19:36:31.241Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 502
+ },
+ {
+ "ts": "2026-10-09T19:36:31.452Z",
+ "origin": "http://127.0.0.1:18910",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": false,
+ "status": 200
+ },
+ {
+ "ts": "2026-10-09T19:36:31.848Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 502
+ },
+ {
+ "ts": "2026-10-09T19:36:32.770Z",
+ "origin": "http://127.0.0.1:18900",
+ "path": "/api/settings",
+ "method": "GET",
+ "type": "fetch",
+ "app": true,
+ "status": 502
+ }
+ ]
+}
diff --git a/.pr/settings-verification-2026-10-09/head-pinned-retry.gif b/.pr/settings-verification-2026-10-09/head-pinned-retry.gif
new file mode 100644
index 0000000000..96f3dee89f
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/head-pinned-retry.gif differ
diff --git a/.pr/settings-verification-2026-10-09/head-pinned-retry.mp4 b/.pr/settings-verification-2026-10-09/head-pinned-retry.mp4
new file mode 100644
index 0000000000..050005a479
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/head-pinned-retry.mp4 differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.gif b/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.gif
new file mode 100644
index 0000000000..bdb1ac1f9a
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.gif differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.mp4 b/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.mp4
new file mode 100644
index 0000000000..7c58480ec0
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-head-encrypted-expiry.mp4 differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.gif b/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.gif
new file mode 100644
index 0000000000..d8c5881175
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.gif differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.mp4 b/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.mp4
new file mode 100644
index 0000000000..262e59daa9
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-head-warm-and-refresh.mp4 differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.gif b/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.gif
new file mode 100644
index 0000000000..7460f7523d
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.gif differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.mp4 b/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.mp4
new file mode 100644
index 0000000000..05732b9b0b
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-main-encrypted-expiry.mp4 differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.gif b/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.gif
new file mode 100644
index 0000000000..8458d5da27
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.gif differ
diff --git a/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.mp4 b/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.mp4
new file mode 100644
index 0000000000..c2ae5e94e6
Binary files /dev/null and b/.pr/settings-verification-2026-10-09/ttl-main-warm-and-refresh.mp4 differ
diff --git a/__tests__/api/settings-service.test.ts b/__tests__/api/settings-service.test.ts
index 01094c5ca7..eef2f3476e 100644
--- a/__tests__/api/settings-service.test.ts
+++ b/__tests__/api/settings-service.test.ts
@@ -8,6 +8,8 @@ import {
setRegisteredBackends,
} from "#/api/backend-registry/active-store";
import type { Backend } from "#/api/backend-registry/types";
+import { NoBackendAvailableError } from "#/api/agent-server-client-options";
+import { DEFAULT_SETTINGS } from "#/services/settings";
import { server } from "#/mocks/node";
import { resetTestHandlersMockSettings } from "#/mocks/settings-handlers";
import type { Settings } from "#/types/settings";
@@ -32,6 +34,30 @@ const cloudBackend: Backend = {
kind: "cloud",
};
+const localBackendA: Backend = {
+ id: "local-a",
+ name: "Local A",
+ host: "http://local-a.example",
+ apiKey: "local-a-key",
+ kind: "local",
+ connectionRevision: 0,
+};
+
+const localBackendB: Backend = {
+ id: "local-b",
+ name: "Local B",
+ host: "http://local-b.example",
+ apiKey: "local-b-key",
+ kind: "local",
+ connectionRevision: 0,
+};
+
+const settingsResponse = (model: string) => ({
+ agent_settings: { llm: { model } },
+ conversation_settings: {},
+ llm_api_key_is_set: true,
+});
+
describe("SettingsService", () => {
beforeEach(() => {
// Clear localStorage and reset mock settings state
@@ -59,6 +85,19 @@ describe("SettingsService", () => {
expect(settings.security_analyzer).toBe("llm");
});
+ // @spec BM-003 β€” Removing the last backend leaves an explicit empty state
+ it("returns display defaults but refuses conversation settings without a backend", async () => {
+ setRegisteredBackends([]);
+
+ const settings = await SettingsService.getSettings();
+
+ expect(settings.llm_model).toBe(DEFAULT_SETTINGS.llm_model);
+ expect(settings.llm_api_key_set).toBe(false);
+ await expect(
+ SettingsService.getSettingsForConversation(),
+ ).rejects.toBeInstanceOf(NoBackendAvailableError);
+ });
+
it("saves settings via PATCH API and invalidates cache", async () => {
// Save some settings
await SettingsService.saveSettings({
@@ -127,6 +166,136 @@ describe("SettingsService", () => {
fetchSpy.mockRestore();
});
+ it("scopes cached settings by local backend", async () => {
+ const requestCounts = { a: 0, b: 0 };
+ server.use(
+ http.get("http://local-a.example/api/settings", () => {
+ requestCounts.a += 1;
+ return HttpResponse.json(settingsResponse("model-a"));
+ }),
+ http.get("http://local-b.example/api/settings", () => {
+ requestCounts.b += 1;
+ return HttpResponse.json(settingsResponse("model-b"));
+ }),
+ );
+ setRegisteredBackends([localBackendA, localBackendB]);
+
+ setActiveSelection({ backendId: localBackendA.id });
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-a");
+
+ setActiveSelection({ backendId: localBackendB.id });
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-b");
+
+ setActiveSelection({ backendId: localBackendA.id });
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-a");
+ expect(requestCounts).toEqual({ a: 1, b: 1 });
+ });
+
+ it("does not reuse encrypted conversation settings across backends", async () => {
+ server.use(
+ http.get("http://local-a.example/api/settings", () =>
+ HttpResponse.json(settingsResponse("encrypted-model-a")),
+ ),
+ http.get("http://local-b.example/api/settings", () =>
+ HttpResponse.json(settingsResponse("encrypted-model-b")),
+ ),
+ );
+ setRegisteredBackends([localBackendA, localBackendB]);
+
+ setActiveSelection({ backendId: localBackendA.id });
+ const settingsA = await SettingsService.getSettingsForConversation();
+
+ setActiveSelection({ backendId: localBackendB.id });
+ const settingsB = await SettingsService.getSettingsForConversation();
+
+ expect(settingsA.agentSettings.llm).toMatchObject({
+ model: "encrypted-model-a",
+ });
+ expect(settingsB.agentSettings.llm).toMatchObject({
+ model: "encrypted-model-b",
+ });
+ });
+
+ it("invalidates cached settings when the connection revision changes", async () => {
+ let requestCount = 0;
+ server.use(
+ http.get("http://local-a.example/api/settings", () => {
+ requestCount += 1;
+ return HttpResponse.json(settingsResponse(`model-${requestCount}`));
+ }),
+ );
+ setRegisteredBackends([localBackendA]);
+ setActiveSelection({ backendId: localBackendA.id });
+
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-1");
+
+ setRegisteredBackends([
+ { ...localBackendA, connectionRevision: 1, apiKey: "rotated-key" },
+ ]);
+ setActiveSelection({ backendId: localBackendA.id });
+
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-2");
+ expect(requestCount).toBe(2);
+ });
+
+ it("expires redacted and encrypted settings independently", async () => {
+ const requests: Array<string | null> = [];
+ server.use(
+ http.get("http://local-a.example/api/settings", ({ request }) => {
+ const exposure = request.headers.get("X-Expose-Secrets");
+ requests.push(exposure);
+ return HttpResponse.json(
+ settingsResponse(
+ exposure === "encrypted" ? "encrypted-model" : "redacted-model",
+ ),
+ );
+ }),
+ );
+ setRegisteredBackends([localBackendA]);
+ setActiveSelection({ backendId: localBackendA.id });
+ const now = vi.spyOn(Date, "now");
+
+ now.mockReturnValue(1);
+ await SettingsService.getSettingsForConversation();
+
+ now.mockReturnValue(2);
+ await SettingsService.getSettings();
+
+ // The encrypted entry expires one millisecond before the redacted one.
+ now.mockReturnValue(5 * 60 * 1000 + 1);
+ await SettingsService.getSettingsForConversation();
+ await SettingsService.getSettings();
+
+ expect(requests).toEqual(["encrypted", null, "encrypted"]);
+ now.mockRestore();
+ });
+
+ it("pins retries to the backend that started the settings request", async () => {
+ const requestedBackends: string[] = [];
+ server.use(
+ http.get("http://local-a.example/api/settings", () => {
+ requestedBackends.push("a");
+ if (requestedBackends.length === 1) {
+ setActiveSelection({ backendId: localBackendB.id });
+ return new HttpResponse(null, { status: 503 });
+ }
+ return HttpResponse.json(settingsResponse("model-a"));
+ }),
+ http.get("http://local-b.example/api/settings", () => {
+ requestedBackends.push("b");
+ return HttpResponse.json(settingsResponse("model-b"));
+ }),
+ );
+ setRegisteredBackends([localBackendA, localBackendB]);
+ setActiveSelection({ backendId: localBackendA.id });
+
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-a");
+ expect(requestedBackends).toEqual(["a", "a"]);
+
+ expect((await SettingsService.getSettings()).llm_model).toBe("model-b");
+ expect(requestedBackends).toEqual(["a", "a", "b"]);
+ });
+
it("skips API call when no diffs are provided to saveSettings", async () => {
const fetchSpy = vi.spyOn(SettingsService, "fetchSettingsFromApi");
diff --git a/src/api/settings-service/settings-service.api.ts b/src/api/settings-service/settings-service.api.ts
index 388a0e3fb4..e29ab26ddd 100644
--- a/src/api/settings-service/settings-service.api.ts
+++ b/src/api/settings-service/settings-service.api.ts
@@ -19,7 +19,10 @@ import {
fetchCloudSettingsSchema,
saveCloudSettings,
} from "../cloud/settings-service.api";
-import { getAgentServerClientOptions } from "../agent-server-client-options";
+import {
+ getAgentServerClientOptions,
+ type AgentServerClientOptions,
+} from "../agent-server-client-options";
/**
* Fields the agent-server stores under `misc_settings.app_preferences` (see
@@ -164,65 +167,79 @@ async function withRetry<T>(
throw new Error("Retry attempts exhausted");
}
-/**
- * In-memory cache for settings to avoid repeated network calls.
- * The cache is invalidated on save operations.
- */
-let settingsCache: {
- /** Settings with redacted secrets for display */
- redacted: SettingsApiResponse | null;
- /** Settings with encrypted secrets for conversation start */
- encrypted: SettingsApiResponse | null;
- /** Timestamp when the cache was last populated */
- timestamp: number;
- /** Which backend answered. Settings from one are not settings from another. */
- backendKey: string | null;
-} = {
- redacted: null,
- encrypted: null,
- timestamp: 0,
- backendKey: null,
-};
-
const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+type SettingsExposureMode = "redacted" | "encrypted";
+
+interface SettingsCacheEntry {
+ backendId: string;
+ connectionRevision: number;
+ exposureMode: SettingsExposureMode;
+ response: SettingsApiResponse;
+ fetchedAt: number;
+}
+
/**
- * Identity of the backend a cached response came from.
- *
- * `connectionRevision` is part of it because it changes whenever the
- * connection credentials do, which is the same reason the query keys across
- * the app already include it: the host can stay the same while what it
- * answers with does not.
+ * Local settings are owned by a specific backend connection and exposure
+ * mode. Keeping that identity in the cache prevents one backend (or its
+ * encrypted conversation payload) from being reused for another.
*/
-const activeBackendKey = (): string => {
- const { backend } = getActiveBackend();
- return `${backend.id}:${backend.connectionRevision ?? 0}`;
-};
+const settingsCache = new Map<string, SettingsCacheEntry>();
+
+const getSettingsCacheKey = (
+ backendId: string,
+ connectionRevision: number,
+ exposureMode: SettingsExposureMode,
+) => JSON.stringify([backendId, connectionRevision, exposureMode]);
+
+const readCachedSettings = (
+ backendId: string,
+ connectionRevision: number,
+ exposureMode: SettingsExposureMode,
+): SettingsApiResponse | null => {
+ const key = getSettingsCacheKey(backendId, connectionRevision, exposureMode);
+ const entry = settingsCache.get(key);
+ if (!entry) return null;
+
+ if (Date.now() - entry.fetchedAt >= CACHE_TTL_MS) {
+ settingsCache.delete(key);
+ return null;
+ }
-const isCacheValid = () =>
- settingsCache.backendKey === activeBackendKey() &&
- Date.now() - settingsCache.timestamp < CACHE_TTL_MS;
+ return entry.response;
+};
-const clearCache = () => {
- settingsCache = {
- redacted: null,
- encrypted: null,
- timestamp: 0,
- backendKey: null,
- };
+const cacheSettings = (
+ backendId: string,
+ connectionRevision: number,
+ exposureMode: SettingsExposureMode,
+ response: SettingsApiResponse,
+) => {
+ // A connection revision replaces every cached representation for the prior
+ // connection, so repeated host/API-key edits do not retain old revisions.
+ settingsCache.forEach((entry, key) => {
+ if (
+ entry.backendId === backendId &&
+ entry.connectionRevision !== connectionRevision
+ ) {
+ settingsCache.delete(key);
+ }
+ });
+
+ settingsCache.set(
+ getSettingsCacheKey(backendId, connectionRevision, exposureMode),
+ {
+ backendId,
+ connectionRevision,
+ exposureMode,
+ response,
+ fetchedAt: Date.now(),
+ },
+ );
};
-/**
- * Whether a response requested from `requestedKey` may be cached: only while
- * that backend is still the active one, so a switch during the request does
- * not file the old backend's answer under the new one. An entry from another
- * backend is dropped first, so the two are never mixed.
- */
-const prepareCacheFor = (requestedKey: string): boolean => {
- if (activeBackendKey() !== requestedKey) return false;
- if (settingsCache.backendKey !== requestedKey) clearCache();
- settingsCache.backendKey = requestedKey;
- return true;
+const clearCache = () => {
+ settingsCache.clear();
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -592,9 +609,10 @@ class SettingsService {
*/
static async fetchSettingsFromApi(
exposeSecrets?: ExposeSecretsMode,
+ clientOptions: AgentServerClientOptions = getAgentServerClientOptions(),
): Promise<SettingsApiResponse> {
return withRetry(() =>
- new SettingsClient(getAgentServerClientOptions()).getSettings({
+ new SettingsClient(clientOptions).getSettings({
exposeSecrets,
}),
) as Promise<SettingsApiResponse>;
@@ -621,18 +639,24 @@ class SettingsService {
}
}
- // Check cache first
- if (isCacheValid() && settingsCache.redacted) {
- return syncDerivedSettings(transformApiResponse(settingsCache.redacted));
+ const backend = getActiveBackend().backend;
+ const connectionRevision = backend.connectionRevision ?? 0;
+ const cached = readCachedSettings(
+ backend.id,
+ connectionRevision,
+ "redacted",
+ );
+ if (cached) {
+ return syncDerivedSettings(transformApiResponse(cached));
}
- const requestedKey = activeBackendKey();
try {
- const response = await this.fetchSettingsFromApi();
- if (prepareCacheFor(requestedKey)) {
- settingsCache.redacted = response;
- settingsCache.timestamp = Date.now();
- }
+ const clientOptions = getAgentServerClientOptions();
+ const response = await this.fetchSettingsFromApi(
+ undefined,
+ clientOptions,
+ );
+ cacheSettings(backend.id, connectionRevision, "redacted", response);
return syncDerivedSettings(transformApiResponse(response));
} catch (error) {
// If API fails, return defaults
@@ -655,26 +679,30 @@ class SettingsService {
secretsEncrypted: boolean;
skillEnablement: SkillEnablement;
}> {
- // Check cache first
- if (isCacheValid() && settingsCache.encrypted) {
+ const backend = getActiveBackend().backend;
+ const connectionRevision = backend.connectionRevision ?? 0;
+ const clientOptions = getAgentServerClientOptions();
+ const cached = readCachedSettings(
+ backend.id,
+ connectionRevision,
+ "encrypted",
+ );
+ if (cached) {
return {
- agentSettings: settingsCache.encrypted.agent_settings,
- conversationSettings: settingsCache.encrypted.conversation_settings,
+ agentSettings: cached.agent_settings,
+ conversationSettings: cached.conversation_settings,
secretsEncrypted: true,
- skillEnablement: getSkillEnablement(settingsCache.encrypted),
+ skillEnablement: getSkillEnablement(cached),
};
}
// Fetch encrypted settings - this MUST succeed for conversations to work.
// Do not fall back to redacted settings as that would cause auth failures.
- const requestedKey = activeBackendKey();
- const response = await this.fetchSettingsFromApi("encrypted");
- if (prepareCacheFor(requestedKey)) {
- settingsCache.encrypted = response;
- if (!settingsCache.timestamp) {
- settingsCache.timestamp = Date.now();
- }
- }
+ const response = await this.fetchSettingsFromApi(
+ "encrypted",
+ clientOptions,
+ );
+ cacheSettings(backend.id, connectionRevision, "encrypted", response);
return {
agentSettings: response.agent_settings,
conversationSettings: response.conversation_settings,