The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Live skin sync from the Hermes backend.
*
* The backend resolves the active skin (built-in or `$HERMES_HOME/skins/*.yaml`)
* and announces it on `gateway.ready` / `skin.changed`, and answers `config.get
* skin` with the same payload. `ingestBackendSkin` folds that into the desktop:
*
* 1. Registers the converted theme in `$backendThemes` so it appears wherever a
* built-in does — Appearance, Cmd-K, `/skin` — with no per-surface wiring
* (`listAllThemes` merges this store).
* 2. When asked to apply (an explicit change), requests the switch via
* `$pendingSkinApply`, which the ThemeProvider drains through `setTheme`.
*
* `gateway.ready` seeds the baseline WITHOUT applying, so a fresh connect never
* stomps the user's persisted desktop theme; only a genuine name change (Hermes
* authoring/activating a skin from a prompt, or `/skin` elsewhere) repaints.
*/
import type { HermesSkin } from '@hermes/shared/skin'
import { atom } from 'nanostores'
import { readJson, writeJson } from '@/lib/storage'
import { BUILTIN_THEMES, DEFAULT_SKIN_NAME, RETIRED_SKINS } from './presets'
import { skinToDesktopTheme } from './skin'
import { type DesktopTheme, isValidTheme } from './types'
// Cached so the boot-time paint (which runs before the gateway connects) can
// resolve a persisted skin pick synchronously, like a built-in or a user
// install. Without it the stored name failed `resolveTheme` on every launch
// and the app silently painted the default until the next `skin.changed`.
const BACKEND_THEMES_KEY = 'hermes-desktop-backend-themes-v1'
// Electron reads the active local `display.skin` before it creates the
// renderer. Seed it alongside the existing cache so an unreachable primary
// gateway cannot leave a first-time custom skin unknown to the theme registry.
const localSkinPayload = typeof window === 'undefined' ? null : (window.hermesDesktop?.localSkin ?? null)
const localSkin = localSkinPayload?.skin ?? null
export const localDisplaySkinName = (localSkin?.name ?? '').trim() || null
export const localDisplaySkinProfile = localDisplaySkinName
? (localSkinPayload?.profile ?? '').trim() || 'default'
: null
// Built-in names keep their desktop palette and retired names resolve to the
// default skin, so a cached theme under either is a shadow nothing should list.
const cacheable = (name: string) => !BUILTIN_THEMES[name] && !RETIRED_SKINS.has(name)
// Dropped entries are written back out, so a stale shadow (the reverted #130015
// build cached the CLI `default` skin as a second "Classic Hermes") is gone from
// disk on the first launch, not only hidden until the next registry change.
const readCached = (): Record<string, DesktopTheme> => {
const stored = Object.entries(readJson<Record<string, unknown>>(BACKEND_THEMES_KEY) ?? {})
const kept = Object.fromEntries(
stored.filter((entry): entry is [string, DesktopTheme] => cacheable(entry[0]) && isValidTheme(entry[1]))
)
if (Object.keys(kept).length !== stored.length) {
writeJson(BACKEND_THEMES_KEY, kept)
}
return kept
}
/** Skins pushed by the backend, keyed by name. Merged by `listAllThemes`. */
export const $backendThemes = atom<Record<string, DesktopTheme>>(typeof window === 'undefined' ? {} : readCached())
$backendThemes.listen(themes => writeJson(BACKEND_THEMES_KEY, themes))
/** Custom CSS carried by a user skin whose name is `default` or a desktop
* built-in. The palette policy keeps built-in palettes (a user `mono.yaml`
* must not shadow the desktop's hand-tuned mono), but the user's CSS is still
* the skin file's truth — keyed by the name the desktop resolves the skin
* under (`default` → `nous`). Merged into the active theme in context.tsx. */
export const $backendCustomCSS = atom<Record<string, string>>({})
/** One-shot skin name the ThemeProvider should switch to (it clears this). */
export const $pendingSkinApply = atom<string | null>(null)
// Last skin name synced from the backend + whether it was ever APPLIED (vs
// merely seeded at connect). Once applied, only a name change applies again —
// no re-apply on repeat events, no snap-back after a manual desktop switch.
// A `skin.changed` matching a seed-only baseline still applies: the seed
// records without painting, so if the activation event was missed (backend
// restart / disconnected), an explicit re-affirm must repaint, not no-op.
let lastSynced: { applied: boolean; name: string } | null = null
/** Test-only: reset the module's apply guard + registry between cases. */
export function __resetBackendSkinSync(): void {
lastSynced = null
$backendThemes.set({})
$pendingSkinApply.set(null)
$backendCustomCSS.set({})
}
/**
* Fold a resolved skin into the desktop. `apply: false` (connect-time seed) only
* records the baseline; `apply: true` (runtime change / poll) repaints on a name
* change. Built-in names keep the desktop's own palette but can still be applied.
*/
export function ingestBackendSkin(skin: HermesSkin | undefined | null, { apply }: { apply: boolean }): void {
const name = (skin && typeof skin === 'object' ? (skin.name ?? '') : '').trim()
if (!name) {
return
}
// `default` (like every retired name) is "no opinion" on the PALETTE — the
// desktop keeps its own default (nous), so we never register a converted theme
// under `default`. It is still a
// valid apply TARGET though: a runtime switch back to `default` must repaint the
// desktop to its own default (setTheme normalizes `default` → nous). So we only
// skip the registry step here and let it flow through the apply logic below.
// Built-in names (mono/slate/…) already have a hand-tuned desktop palette — we
// never shadow it, but the name is still a valid apply target.
if (cacheable(name)) {
const theme = skinToDesktopTheme(skin as HermesSkin)
if (!theme) {
return
}
const current = $backendThemes.get()
if (JSON.stringify(current[name]) !== JSON.stringify(theme)) {
$backendThemes.set({ ...current, [name]: theme })
}
} else {
// Built-in/default-named user skins never shadow the desktop palette, but
// their customCSS still belongs to the user's skin file (user skins take
// precedence over built-ins with the same name). Carry it separately so
// applyTheme can inject it on top of the built-in palette; dropping the
// field from the YAML clears the entry so stale rules don't linger.
const css = skin?.customCSS?.trim() ?? ''
const cssKey = name === 'default' ? DEFAULT_SKIN_NAME : name
const current = $backendCustomCSS.get()
if (css) {
if (current[cssKey] !== css) {
$backendCustomCSS.set({ ...current, [cssKey]: css })
}
} else if (current[cssKey]) {
const next = { ...current }
delete next[cssKey]
$backendCustomCSS.set(next)
}
}
if (!apply) {
// Connect-time seed: record without painting. A reconnect re-seed keeps an
// earlier real apply's flag so repeat events can't override a manual switch.
if (lastSynced?.name !== name || !lastSynced.applied) {
lastSynced = { applied: false, name }
}
return
}
if (name !== lastSynced?.name || !lastSynced.applied) {
lastSynced = { applied: true, name }
$pendingSkinApply.set(name)
}
}
// This is a boot fallback, not a remote activation. ThemeProvider uses the
// name only when the desktop has no saved appearance of its own, while this
// registers the custom palette early enough for that first paint to resolve.
if (localSkin) {
ingestBackendSkin(localSkin, { apply: false })
}