The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Flash-free theme boot — the TUI port of the desktop app's
* `hermes-boot-background` / `hermes-boot-color-scheme` localStorage keys.
*
* Theme resolution is asynchronous by nature (gateway skin arrives after
* connect; the OSC-11 background probe answers after the first frame; the
* config mode pin arrives with config sync), so without a cache every launch
* repaints through default-dark → skin → detected-mode. This module persists
* the LAST RESOLVED theme + background to disk and replays them as the very
* first frame, so a stable setup renders correctly from paint one and the
* async signals merely confirm it.
*
* The cache is a hint, never an authority: explicit env pins beat it, and
* every later signal overwrites it (then persists the new answer).
*/
import { readFileSync, renameSync, writeFileSync } from 'fs'
import { homedir } from 'os'
import { join } from 'path'
import type { Theme } from '../theme.js'
interface BootThemeFile {
/** The resolved background hex that detection settled on, if any. */
background?: string
/** The config mode pin (`display.tui_theme`) active when this cache was
* written. Without it a pinned theme caches incoherently — a light
* resolved theme next to the dark PHYSICAL background — and the next
* launch flashes light → dark (skin resolves against the seeded
* background) → light (config pin rehydrates). */
mode?: 'dark' | 'light'
/** The fully-resolved Theme (palette + brand) from the last session. */
theme?: Theme
version: 1
}
// Profile-aware: the Python launcher exports HERMES_HOME (set by
// _apply_profile_override) before spawning the TUI. Falling back to
// ~/.hermes matches get_hermes_home()'s default.
const bootFilePath = () => join(process.env.HERMES_HOME ?? join(homedir(), '.hermes'), 'tui-theme-boot.json')
// Never touch the user's real ~/.hermes from test runs (the TS suite has no
// HERMES_HOME isolation fixture).
const isTestRun = () => !!process.env.VITEST || process.env.NODE_ENV === 'test'
const looksLikeTheme = (value: unknown): value is Theme => {
if (typeof value !== 'object' || value === null) {
return false
}
const theme = value as Partial<Theme>
return (
typeof theme.color === 'object' &&
theme.color !== null &&
typeof theme.color.text === 'string' &&
typeof theme.color.primary === 'string' &&
typeof theme.brand === 'object' &&
theme.brand !== null &&
typeof theme.brand.name === 'string'
)
}
export interface BootTheme {
background?: string
mode?: 'dark' | 'light'
theme: Theme
}
/** Read the cached boot theme. Null on first launch / damage / test runs. */
export function readBootTheme(): BootTheme | null {
if (isTestRun()) {
return null
}
try {
const raw = JSON.parse(readFileSync(bootFilePath(), 'utf8')) as BootThemeFile
if (raw.version !== 1 || !looksLikeTheme(raw.theme)) {
return null
}
return {
background: typeof raw.background === 'string' ? raw.background : undefined,
mode: raw.mode === 'light' || raw.mode === 'dark' ? raw.mode : undefined,
theme: raw.theme
}
} catch {
return null
}
}
let writeTimer: NodeJS.Timeout | null = null
/** Persist the resolved theme (debounced, atomic, fire-and-forget). */
export function writeBootTheme(theme: Theme, background?: string, mode?: 'dark' | 'light'): void {
if (isTestRun()) {
return
}
if (writeTimer) {
clearTimeout(writeTimer)
}
writeTimer = setTimeout(() => {
writeTimer = null
try {
const payload: BootThemeFile = { background, mode, theme, version: 1 }
const path = bootFilePath()
const tmp = `${path}.tmp`
writeFileSync(tmp, JSON.stringify(payload))
renameSync(tmp, path)
} catch {
// Cache write failures are cosmetic — next launch just flashes once.
}
}, 400)
writeTimer.unref?.()
}
// ── Boot-time seeding (with provenance) ──────────────────────────────
//
// The cache seeds env slots so the first skin resolution matches the last
// session — but a previous-session background must NOT occupy the same
// authoritative slot as a current OSC answer forever. Provenance is
// recorded so that once the CURRENT terminal answers with a distrusted
// value (pure-black OSC-11, unusable OSC-10), the stale hint can be
// invalidated and detection falls through to foreground / COLORFGBG /
// macOS appearance / the default — instead of a light cache pinning a now-
// dark terminal to light indefinitely (review on #20379, finding 2).
export interface BootSeedResult {
/** The background hex this boot seeded into env, or null. */
seededBackground: null | string
/** True when the cached config pin was seeded into HERMES_TUI_THEME. */
seededPin: boolean
}
// Provenance of the last seeding pass — read by invalidateBootBackground.
// Module-load seeds process.env; tests re-seed against a fake env.
let seeded: BootSeedResult = { seededBackground: null, seededPin: false }
/** Seeding step (exported for tests — module-load runs it on process.env).
* Explicit user signals always outrank the cache. Records provenance so
* invalidateBootBackground can later demote the hint. */
export function seedBootEnvironment(boot: BootTheme | null, env: NodeJS.ProcessEnv): BootSeedResult {
const result: BootSeedResult = { seededBackground: null, seededPin: false }
seeded = result
if (!boot || env.HERMES_TUI_THEME || env.HERMES_TUI_LIGHT) {
return result
}
// Replay the config mode pin first: a pinned session caches a resolved
// theme whose polarity intentionally disagrees with the physical
// background, and without the pin the first skin resolution flips to the
// physical pole before config hydration flips it back (multi-stage flash).
if (boot.mode) {
env.HERMES_TUI_THEME = boot.mode
result.seededPin = true
}
if (
boot.background &&
// Never seed the untrusted "unset default" fingerprint — a cache written
// before the distrust rule existed must not poison this session's
// detection (it would also suppress the macOS-appearance fallback).
boot.background.toLowerCase() !== '#000000' &&
!env.HERMES_TUI_BACKGROUND
) {
env.HERMES_TUI_BACKGROUND = boot.background
result.seededBackground = boot.background
}
return result
}
/**
* Invalidate the cache-seeded background: called when the CURRENT terminal
* answered the background probe with an untrusted value, meaning the seeded
* hint is from another era and must not outrank the live fallback chain.
* Only clears the slot while it still holds the seeded value — a trusted
* OSC answer or explicit export that overwrote it is left alone.
* Returns true when the slot was cleared.
*/
export function invalidateBootBackground(env: NodeJS.ProcessEnv = process.env): boolean {
if (!seeded.seededBackground || env.HERMES_TUI_BACKGROUND !== seeded.seededBackground) {
return false
}
delete env.HERMES_TUI_BACKGROUND
seeded.seededBackground = null
return true
}
const boot = readBootTheme()
/** True when this boot replayed a cached config pin into HERMES_TUI_THEME.
* applyConfiguredTuiTheme treats it as config-owned so a later 'auto' can
* clear it — otherwise a stale cached pin masquerades as a user shell
* export and becomes unclearable. */
export const bootSeededPin: boolean = seedBootEnvironment(boot, process.env).seededPin
/** The cached theme for the first frame, or null on first launch. */
export const bootTheme: Theme | null = boot?.theme ?? null