Skip to content

The agent that grows with you

fix(desktop): skipped onboarding and seen or dismissed tips follow the machine

Teknium6d8a83548521
diff --git a/apps/desktop/electron/ui-preferences.ts b/apps/desktop/electron/ui-preferences.ts
index b0cbe91d542..d95c16b0d80 100644
--- a/apps/desktop/electron/ui-preferences.ts
+++ b/apps/desktop/electron/ui-preferences.ts
@@ -19,7 +19,7 @@ import fs from 'node:fs'
import path from 'node:path'
export const UI_PREFERENCES_FILE = 'ui-preferences.json'
-const KEY_PREFIXES = ['hermes.desktop.', 'hermes-desktop-']
+const KEY_PREFIXES = ['hermes.desktop.', 'hermes-desktop-', 'hermes-onboarding-']
const MAX_KEY_CHARS = 256
const MAX_VALUE_CHARS = 256 * 1024
const MAX_KEYS = 512
diff --git a/apps/desktop/src/lib/ui-preferences/guidance-sync.test.ts b/apps/desktop/src/lib/ui-preferences/guidance-sync.test.ts
new file mode 100644
index 00000000000..e1ee5b41b48
--- /dev/null
+++ b/apps/desktop/src/lib/ui-preferences/guidance-sync.test.ts
@@ -0,0 +1,63 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { afterEach, expect, it, vi } from 'vitest'
+
+import { parseUiPreferencesWrite, readUiPreferences, writeUiPreferences } from '../../../electron/ui-preferences'
+
+const dirs: string[] = []
+const tick = (ms = 400) => new Promise(resolve => setTimeout(resolve, ms))
+
+afterEach(() => {
+ window.localStorage.clear()
+ window.sessionStorage.clear()
+
+ for (const dir of dirs.splice(0)) {
+ fs.rmSync(dir, { force: true, recursive: true })
+ }
+})
+
+/** One page load of an origin against the machine store file, as boot.ts + main.tsx run it. */
+async function load(file: string) {
+ window.localStorage.clear()
+ window.sessionStorage.clear()
+ vi.resetModules()
+ const sync = await import('./sync')
+ sync.captureOwnPreferences()
+ sync.hydrateFromSnapshot(readUiPreferences(file))
+
+ const stop = sync.startUiPreferencesSync({
+ read: async () => readUiPreferences(file),
+ write: payload => writeUiPreferences(file, parseUiPreferencesWrite(payload))
+ })
+
+ return {
+ onboarding: await import('@/store/onboarding'),
+ stop,
+ tips: await import('@/store/tips')
+ }
+}
+
+it('onboarding skipped and tips seen or dismissed in one browser stay so in another (#145600)', async () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-ui-guidance-'))
+ dirs.push(dir)
+ const file = path.join(dir, 'ui-preferences.json')
+
+ const first = await load(file)
+ await tick()
+ first.onboarding.dismissFirstRunOnboarding()
+ first.tips.showTip({ side: 'top', targets: [], text: 'One', tipId: 'catalog:one' })
+ first.tips.retireTips(['catalog:two'])
+ await tick()
+ first.stop()
+
+ // A phone, or the same Webapp on another origin: its own empty localStorage.
+ const second = await load(file)
+ await tick()
+ second.stop()
+
+ expect(second.onboarding.$desktopOnboarding.get().firstRunSkipped).toBe(true)
+ expect(second.tips.$retiredTips.get()).toContain('catalog:two')
+ expect(Object.keys(second.tips.$tipShownAt.get())).toContain('catalog:one')
+})
diff --git a/apps/desktop/src/lib/ui-preferences/keys.ts b/apps/desktop/src/lib/ui-preferences/keys.ts
index 5af90e3c586..f99a4dda5f8 100644
--- a/apps/desktop/src/lib/ui-preferences/keys.ts
+++ b/apps/desktop/src/lib/ui-preferences/keys.ts
@@ -12,8 +12,9 @@
* - per-window or per-device runtime state: layout tree, open tiles and tabs,
* last route/session, scroll, zoom, pet and popout geometry, keep-awake;
* - drafts, queues, journals and caches: composer queue, in-flight turns,
- * pending/prepared submissions, previews, pricing, backend skin cache;
- * - seen/dismissed markers and onboarding progress.
+ * pending/prepared submissions, previews, pricing, backend skin cache, the
+ * "provider configured" onboarding cache (each backend answers that itself);
+ * - one-off notices: butterbar, update and real-profile prompts.
*/
const SHARED_KEYS: ReadonlySet<string> = new Set([
@@ -64,8 +65,15 @@ const SHARED_KEYS: ReadonlySet<string> = new Set([
'hermes.desktop.layoutPresets.v2',
'hermes.desktop.panesFlipped',
'hermes.desktop.tabStripDefault',
- 'hermes.desktop.tips.rotation.v1',
'hermes.desktop.titlebarAppActions',
+ // Guidance: what the user already skipped, saw or dismissed does not come
+ // back in every new browser or origin (#145600).
+ 'hermes-onboarding-skipped-v1',
+ 'hermes.desktop.tips.last.v1',
+ 'hermes.desktop.tips.next.v1',
+ 'hermes.desktop.tips.retired.v1',
+ 'hermes.desktop.tips.rotation.v1',
+ 'hermes.desktop.tips.shownAt.v1',
'hermes.desktop.tours.v1',
// Sound and media.
'hermes.desktop.autoSpeakReplies',
diff --git a/apps/desktop/src/store/onboarding.ts b/apps/desktop/src/store/onboarding.ts
index dade2006e92..9fc6e4e15b7 100644
--- a/apps/desktop/src/store/onboarding.ts
+++ b/apps/desktop/src/store/onboarding.ts
@@ -20,6 +20,7 @@ import { writeClipboardText } from '@/lib/clipboard'
import { restOfLongPollGap } from '@/lib/long-poll'
import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
import { evaluateRuntimeReadiness, type RuntimeReadinessResult } from '@/lib/runtime-readiness'
+import { readKey, writeKey } from '@/lib/storage'
import {
$freeTierStatus,
ackFreeTierNotice,
@@ -155,31 +156,15 @@ function writeCachedConfigured(value: boolean) {
}
}
+// Through the storage choke point: the skip is a machine-level preference,
+// so every browser and origin of this machine honours it (#145600).
function readCachedSkipped(): boolean {
- if (typeof window === 'undefined') {
- return false
- }
-
- try {
- return window.localStorage.getItem(SKIP_CACHE_KEY) === '1'
- } catch {
- return false
- }
+ return typeof window !== 'undefined' && readKey(SKIP_CACHE_KEY) === '1'
}
function writeCachedSkipped(value: boolean) {
- if (typeof window === 'undefined') {
- return
- }
-
- try {
- if (value) {
- window.localStorage.setItem(SKIP_CACHE_KEY, '1')
- } else {
- window.localStorage.removeItem(SKIP_CACHE_KEY)
- }
- } catch {
- // localStorage unavailable — degrade silently.
+ if (typeof window !== 'undefined') {
+ writeKey(SKIP_CACHE_KEY, value ? '1' : null)
}
}
diff --git a/hermes_cli/ui_preferences.py b/hermes_cli/ui_preferences.py
index b412aa9cfef..966a59efac3 100644
--- a/hermes_cli/ui_preferences.py
+++ b/hermes_cli/ui_preferences.py
@@ -39,7 +39,7 @@ from typing import Callable, Iterator, Mapping, Optional
from utils import atomic_json_write
STORE_NAME = "ui-preferences.json"
-KEY_PREFIXES = ("hermes.desktop.", "hermes-desktop-")
+KEY_PREFIXES = ("hermes.desktop.", "hermes-desktop-", "hermes-onboarding-")
MAX_KEY_CHARS = 256
MAX_VALUE_CHARS = 256 * 1024
MAX_KEYS = 512
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index ad3447960b8..b8c2384cfb5 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -408,9 +408,9 @@ First-run onboarding has been redesigned on a unified overlay design system, and
#### Where your display preferences live
-Display preferences (theme and light/dark mode, session-list density and sidebar layout, status-bar readouts, transcript and tool display, sounds, keybinds, saved layouts, and model-picker favourites) are stored once per computer, in `ui-preferences.json` in the root Hermes home (`~/.hermes/ui-preferences.json` by default; with a custom `HERMES_HOME`, the root of that home, never a profile folder). The desktop app on that computer and every browser that opens the [Webapp](#use-the-desktop-workspace-from-a-browser) it serves read and write the same file. A change in one reaches the others: the desktop app's windows get it within a couple of seconds and Webapp tabs when they regain focus or within about ten seconds. Theme, mode, density and the other settings an open window already follows across windows repaint at once; the rest apply the next time a window or tab loads. This includes another device, a private window, and another address for the same Webapp (`127.0.0.1`, the LAN address, `webapp.public_url`).
+Display preferences (theme and light/dark mode, session-list density and sidebar layout, status-bar readouts, transcript and tool display, sounds, keybinds, saved layouts, model-picker favourites, and which tips, tours and first-run onboarding you already saw or skipped) are stored once per computer, in `ui-preferences.json` in the root Hermes home (`~/.hermes/ui-preferences.json` by default; with a custom `HERMES_HOME`, the root of that home, never a profile folder). The desktop app on that computer and every browser that opens the [Webapp](#use-the-desktop-workspace-from-a-browser) it serves read and write the same file. A change in one reaches the others: the desktop app's windows get it within a couple of seconds and Webapp tabs when they regain focus or within about ten seconds. Theme, mode, density and the other settings an open window already follows across windows repaint at once; the rest apply the next time a window or tab loads. This includes another device, a private window, and another address for the same Webapp (`127.0.0.1`, the LAN address, `webapp.public_url`).
-The file belongs to the computer, not to a gateway connection or a profile. A desktop app connected to a remote gateway, or to several gateways, keeps its own computer's preferences. Settings that are already per profile, such as the theme picked for one profile, stay per profile inside the file. Credentials, sign-ins, permission grants, drafts and per-window state (open tabs, pane layout, scroll position, zoom) are never written to it and stay in each window or browser. The first time an app or browser meets the file (or finds none), it copies in the settings it has that the file lacks, and adopts the values already there; it never overwrites them, and nothing it has is removed just because the file lacks it. If the file is ever damaged, it is kept beside the new one as `ui-preferences.json.corrupt-<timestamp>`, and every open window and tab copies its settings back into the new file. If the file exists but cannot be read (for example, its permissions changed), changes wait in each window and are saved once it is readable again.
+The file belongs to the computer, not to a gateway connection or a profile. A desktop app connected to a remote gateway, or to several gateways, keeps its own computer's preferences. Settings that are already per profile, such as the theme picked for one profile, stay per profile inside the file. Credentials, sign-ins, permission grants, drafts and per-window state (open tabs, pane layout, scroll position, zoom) are never written to it and stay in each window or browser. The first time an app or browser meets the file (or finds none), it copies in the settings it has that the file lacks, and adopts the values already there; it never overwrites them, and nothing it has is removed just because the file lacks it. A default an app or browser filled in for itself (for example read-aloud carried over from `voice.auto_tts`) is never copied in, so it cannot replace a setting you chose elsewhere. If the file is ever damaged, it is kept beside the new one as `ui-preferences.json.corrupt-<timestamp>`, and every open window and tab copies its settings back into the new file. If the file exists but cannot be read (for example, its permissions changed), changes wait in each window and are saved once it is readable again.
#### Per-profile settings: the "Applies to" scope