The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Machine-level Desktop/Webapp UI preferences (#145213).
One JSON document per machine, beside the ROOT Hermes home (``get_default_hermes_root()``, never a
profile's ``HERMES_HOME``): native Desktop writes it through its preload capability
(``apps/desktop/electron/ui-preferences.ts``) and every browser that opens this machine's Webapp
writes it through ``/api/ui-preferences``. It is deliberately neither per profile nor per gateway
connection; a key that is scoped (``….profile.<name>``) carries its scope in its own name.
Both writers share the on-disk contract, so keep the two in lockstep:
* document ``{"version": 1, "revision": <int>, "values": {<key>: <string>}}``;
* a write merges per key under the ``<store>.lock`` directory lock (``mkdir`` is atomic on every
OS and in Node), bumps ``revision`` and lands by temp file + rename; a ``None`` value deletes;
* ``generation`` names one store's lifetime: a write that finds no readable store (missing, or
corrupt and kept aside as ``<store>.corrupt-<ms>``) starts a new one, and every window rejoins it
(re-imports its own values, then follows it) whatever its revision high-water mark was;
* a ``seed`` write (a client's first contact with a generation) only ADDS the keys the store lacks,
so the client that has data fills a store an empty client created, and nothing is overwritten;
* only a missing file reads as "no store": any other read failure refuses the write
(:class:`PreferencesBusy`) instead of merging over nothing.
Values are opaque strings the renderer already kept in localStorage. Only keys under the Desktop
prefixes are accepted; the renderer's allowlist decides which of those are preferences and keeps
credentials, grants and per-window state out.
"""
from __future__ import annotations
import json
import os
import secrets
import shutil
import threading
import time
from contextlib import contextmanager
from pathlib import Path
from typing import Callable, Iterator, Mapping, Optional
from utils import atomic_json_write
STORE_NAME = "ui-preferences.json"
KEY_PREFIXES = ("hermes.desktop.", "hermes-desktop-", "hermes-onboarding-")
MAX_KEY_CHARS = 256
MAX_VALUE_CHARS = 256 * 1024
MAX_KEYS = 512
MAX_TOTAL_CHARS = 2 * 1024 * 1024
_LOCK_WAIT_S = 3.0
_LOCK_STALE_S = 10.0
_LOCK_POLL_S = 0.02
_thread_lock = threading.Lock()
class PreferencesError(ValueError):
"""A write the store refuses (bad key, value or size); the route answers 400."""
class PreferencesBusy(RuntimeError):
"""Another writer held the store lock past the wait; the route answers 503 and the client
keeps the change pending for its next attempt."""
def store_path(root: Optional[Path] = None) -> Path:
"""The machine's preferences file, resolved by the same rule native Desktop applies to its
``HERMES_HOME`` (``resolveDesktopHermesHome`` + ``uiPreferencesRoot``): a profile home
(``<root>/profiles/<name>``, judged on the path as given, so a symlinked profile directory
still names its root) names its root, any other home is its own root, and that root is then
resolved through symlinks on both sides. Every profile one process serves maps to the same
root, so this read is profile-independent by design (not a launch-profile leak)."""
if root is None:
from hermes_constants import get_hermes_home
home = Path(os.path.abspath(get_hermes_home()))
root = (home.parent.parent if home.parent.name.lower() == "profiles" else home).resolve()
return Path(root) / STORE_NAME
def _sanitize(values: object) -> dict[str, str]:
if not isinstance(values, dict):
return {}
return {k: v for k, v in values.items() if isinstance(k, str) and isinstance(v, str)}
_MISSING = {"exists": False, "revision": 0, "values": {}}
def _read(path: Path) -> tuple[dict, bool]:
"""``(snapshot, corrupt)``. A missing file is no store; an unparseable one is no store too
(``corrupt``), so clients re-import into a fresh generation. Any other read failure (EACCES,
EBUSY, EMFILE…) raises :class:`PreferencesBusy`: it says nothing about the content, and
merging over it would drop every key."""
try:
raw = path.read_text(encoding="utf-8-sig")
except FileNotFoundError:
return dict(_MISSING, values={}), False
except OSError as exc:
raise PreferencesBusy(f"preferences store is unreadable: {exc}") from exc
try:
doc = json.loads(raw)
except ValueError:
doc = None
if not isinstance(doc, dict):
return dict(_MISSING, values={}), True
revision = doc.get("revision")
generation = doc.get("generation")
return {
"exists": True,
"revision": revision if isinstance(revision, int) else 0,
"values": _sanitize(doc.get("values")),
"generation": generation if isinstance(generation, str) else "",
}, False
def read_preferences(path: Optional[Path] = None) -> dict:
"""``{"exists", "revision", "values"[, "generation"]}`` for the store at *path* (the
machine's by default). Raises :class:`PreferencesBusy` when the file exists but cannot be read."""
return _read(path or store_path())[0]
def _validate(changes: Mapping[str, Optional[str]]) -> None:
for key, value in changes.items():
if not isinstance(key, str) or not key.startswith(KEY_PREFIXES) or len(key) > MAX_KEY_CHARS:
raise PreferencesError(f"unsupported preference key: {key!r}")
if value is not None and (not isinstance(value, str) or len(value) > MAX_VALUE_CHARS):
raise PreferencesError(f"unsupported value for {key}")
def _owner_file(lock_dir: Path) -> Path:
return lock_dir / "owner"
def _release(lock_dir: Path, token: str) -> None:
"""Remove the lock only while it is still ours: a lock broken as stale and re-taken by another
writer must not be removed by the writer that lost it."""
if not _owns(lock_dir, token):
return
try:
_owner_file(lock_dir).unlink()
os.rmdir(lock_dir)
except OSError:
pass
def _owns(lock_dir: Path, token: str) -> bool:
try:
return _owner_file(lock_dir).read_text(encoding="utf-8-sig") == token
except OSError:
return False
def _break_if_stale(lock_dir: Path) -> None:
try:
stale = time.time() - lock_dir.stat().st_mtime > _LOCK_STALE_S
except FileNotFoundError:
return
if not stale:
return
# A writer that died holding the lock must not wedge every later write. Writes hold it for
# milliseconds, and the data file itself is only ever replaced whole.
try:
_owner_file(lock_dir).unlink(missing_ok=True)
os.rmdir(lock_dir)
except OSError:
pass
@contextmanager
def _store_lock(path: Path) -> Iterator[Callable[[], bool]]:
"""Cross-process lock shared with the Electron writer: the ``<store>.lock`` directory, whose
``owner`` file names the holder."""
lock_dir = path.with_name(path.name + ".lock")
token = f"{os.getpid()}-{secrets.token_hex(8)}"
deadline = time.monotonic() + _LOCK_WAIT_S
with _thread_lock:
while True:
try:
os.mkdir(lock_dir)
break
except FileExistsError:
_break_if_stale(lock_dir)
if time.monotonic() > deadline:
raise PreferencesBusy("preferences store is busy")
time.sleep(_LOCK_POLL_S)
try:
_owner_file(lock_dir).write_text(token, encoding="utf-8")
yield lambda: _owns(lock_dir, token)
finally:
_release(lock_dir, token)
def _merge(current: Mapping[str, str], changes: Mapping[str, Optional[str]], seed: bool) -> dict[str, str]:
values = dict(current)
for key, value in changes.items():
if seed:
# A client's first contact: fill what the store lacks, never overwrite or delete.
if value is not None:
values.setdefault(key, value)
elif value is None:
values.pop(key, None)
else:
values[key] = value
return values
def write_preferences(changes: Mapping[str, Optional[str]], *, seed: bool = False,
path: Optional[Path] = None) -> dict:
"""Merge *changes* per key (``None`` deletes) and return the resulting snapshot.
``seed=True`` is a client's first contact with this store generation: it only adds the keys
the store lacks (and creates no store from nothing), so a client that has data fills a store
an empty client created and no client's values are overwritten or deleted.
"""
_validate(changes)
path = path or store_path()
path.parent.mkdir(parents=True, exist_ok=True)
with _store_lock(path) as still_ours:
current, corrupt = _read(path)
values = _merge(current["values"], changes, seed)
if len(values) > MAX_KEYS or sum(len(k) + len(v) for k, v in values.items()) > MAX_TOTAL_CHARS:
raise PreferencesError("preferences store is full")
if values == current["values"] and (current["exists"] or not values):
return current
revision = current["revision"] + 1
generation = current.get("generation") or secrets.token_hex(8)
if not still_ours():
# Held past the stale limit and broken by another writer: replacing the file now
# could drop the keys that writer merged meanwhile.
raise PreferencesBusy("preferences store lock was taken over")
if corrupt:
# Kept aside, never silently replaced: it may hold preferences worth recovering.
shutil.copy2(path, path.with_name(f"{path.name}.corrupt-{int(time.time() * 1000)}"))
atomic_json_write(path, {"version": 1, "generation": generation, "revision": revision,
"values": values}, mode=0o600)
return {"exists": True, "revision": revision, "values": values, "generation": generation}