npm - @bitseek/hermes-webui - Versions diffs - 0.1.0-beta.0 - Mend

@bitseek/hermes-webui 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (233) hide show

package/vendor/agent-frontend-shell/THEMES.md ADDED Viewed

@@ -0,0 +1,170 @@
+# Hermes Web UI — Themes
+Hermes Web UI splits **appearance** into two independent pickers:
+- **Theme** — the mode: `System`, `Dark`, or `Light`. Drives the background,
+  text, surface, and chrome colors.
+- **Skin** — the accent palette: built-in skins ship as named keys. Drives only
+  the `--accent` family (active states, links, focus rings, primary actions).
+You pick one of each and they combine, so the look adapts to your environment
+without losing your favorite accent — pure CSS, no Python changes needed.
+---
+## Switching Appearance
+**Settings panel:** Click the gear icon → **Appearance**. The **Theme** card
+toggles Light/Dark/System; the **Skin** grid offers the built-in accent palettes.
+Preview is instant — the UI updates as you click.
+**Slash command:** Type `/theme <name>` in the composer. The command accepts
+both theme names (`system`, `dark`, `light`) and skin names (`default`, `ares`,
+`mono`, `slate`, `poseidon`, `sisyphus`, `charizard`, `sienna`,
+`catppuccin`, `nous`, `geist-contrast`). It updates the matching axis and leaves the other one
+alone.
+**Persistence:** Both choices are stored in `localStorage` for flicker-free
+loading, and saved server-side via `POST /api/settings` (under `theme` and
+`skin` keys in `settings.json`).
+---
+## Built-in Themes
+| Theme | Description |
+|-------|-------------|
+| **System** (default) | Follows the OS `prefers-color-scheme` preference and updates live. |
+| **Dark** | Deep dark surfaces, low-glare for long sessions. |
+| **Light** | Bright surfaces with dark text, high contrast for daylight environments. |
+The theme is applied as a class on `<html>`: `.dark` is present for dark mode,
+absent for light. System mode tracks the OS preference at runtime.
+---
+## Built-in Skins
+| Skin | Description |
+|------|-------------|
+| **Default** | The original Hermes gold accent. Warm and understated. |
+| **Ares** | Fiery red. High-energy and assertive. |
+| **Mono** | Neutral gray. Distraction-free, for deep focus. |
+| **Slate** | Slate blue-gray. Subtle and grown-up. |
+| **Poseidon** | Ocean blue. Calm and focused for long sessions. |
+| **Sisyphus** | Vivid purple. Distinctive without being loud. |
+| **Charizard** | Warm orange. Energetic and easy on the eyes. |
+| **Sienna** | Warm clay and sand earth palette. Soft and natural. |
+| **Catppuccin** | Catppuccin Latte/Mocha palette with Mauve accent. |
+| **Nous** | Steel-blue accent with dashed technical surfaces. |
+| **Geist Contrast** (`geist-contrast`) | Geist-inspired monochrome surfaces with a restrained dark-mode `#FFF175` accent. |
+Each skin defines paired light + dark variants so it reads cleanly on either
+theme. The skin is applied as `data-skin="<name>"` on `<html>` (the default
+skin clears the attribute).
+---
+## Creating a Custom Skin
+A skin is a small CSS block that overrides the accent variables for both the
+light and dark variants:
+```css
+/* Light variant */
+:root[data-skin="my-skin"] {
+  --accent:           #2E7D32;                   /* Active states, links, primary buttons */
+  --accent-hover:     #1B5E20;                   /* Hover */
+  --accent-bg:        rgba(46,125,50,0.08);      /* Soft tinted backgrounds */
+  --accent-bg-strong: rgba(46,125,50,0.15);      /* Highlighted backgrounds */
+  --accent-text:      #1B5E20;                   /* Text on accent bg */
+}
+/* Dark variant — usually lighter or more saturated for contrast */
+:root.dark[data-skin="my-skin"] {
+  --accent:           #66BB6A;
+  --accent-hover:     #43A047;
+  --accent-bg:        rgba(102,187,106,0.08);
+  --accent-bg-strong: rgba(102,187,106,0.15);
+  --accent-text:      #66BB6A;
+}
+```
+Two ways to ship it:
+1. **In the repo (built-in):** add the block to `static/style.css`, register it
+   in the Settings skin picker (`static/index.html`) and in the `/theme` command
+   list (`static/commands.js`), then open a PR.
+2. **Self-hosted (no fork):** use the WebUI extensions surface — see
+   `docs/EXTENSIONS.md`. Drop your CSS in `HERMES_WEBUI_EXTENSION_DIR` and
+   declare it in `HERMES_WEBUI_EXTENSION_STYLESHEET_URLS`. No code changes
+   needed; the skin attribute can be set from your own JS.
+### Tips
+- **Test both themes.** A skin that pops on Dark can be illegible on Light.
+  Always check `:root[data-skin]` (light) *and* `:root.dark[data-skin]` (dark).
+- **Pick contrasting `--accent-text` on `--accent-bg`.** The strong variant
+  appears behind small labels and chips; weak contrast there reads as blur.
+- **The logo gradient uses `--accent` automatically**, so it adapts to your
+  skin without any extra work.
+- **No server changes needed.** The `skin` setting in `settings.json` accepts
+  any string, so your custom skin name persists without code changes once you
+  load the CSS.
+---
+## Creating a Custom Theme
+A full custom *theme* (a different overall mood, not just an accent change) is
+a larger task than a skin: it has to redefine the core palette variables
+(`--bg`, `--surface`, `--text`, `--border`, `--code-bg`, and friends) for one
+or both modes. The contract is defined in the top `:root` and `:root.dark`
+blocks of `static/style.css` — start there.
+Most of the time, a custom **skin** is what you actually want. Reach for a
+custom theme only when the existing Light/Dark modes don't fit (for example,
+a high-contrast accessibility theme or an OLED black variant).
+---
+## Font Size
+Right under Theme/Skin in **Settings → Appearance**: `Small`, `Default`,
+`Large`. Applied as `data-font-size` on `<html>` and scales the WebUI's root
+font size. Persists alongside theme and skin.
+---
+## How It Works Internally
+1. **Theme:** `document.documentElement.classList.toggle('dark', isDark)` —
+   light mode removes the class. System mode tracks
+   `matchMedia('(prefers-color-scheme: dark)')`.
+2. **Skin:** `document.documentElement.dataset.skin = name` (or remove the
+   attribute for `default`).
+3. **Font size:** `document.documentElement.dataset.fontSize = size` (or
+   remove for `default`).
+4. **No flash on load:** a tiny inline `<script>` in `<head>` reads
+   `localStorage` before the stylesheet does, so the right look is applied
+   before paint.
+5. **Server sync:** preferences are saved via `POST /api/settings` and
+   rehydrated on boot via `GET /api/settings`.
+---
+## Contributing a Skin
+Skins are the easiest extension point — pure CSS, no Python, no JS logic. To
+contribute one upstream:
+1. Add your `:root[data-skin="name"]` and `:root.dark[data-skin="name"]`
+   blocks to `static/style.css`.
+2. Register it in the Settings skin picker in `static/index.html` and in the
+   skin list used by `cmdTheme()` in `static/commands.js`.
+3. Test on desktop and mobile across both Light and Dark themes.
+4. Open a PR — skins are pure CSS additions with no backend changes needed.
+For a custom *theme* (overriding the base palette), prefer opening an issue
+first to discuss scope, since it touches many selectors.

package/vendor/agent-frontend-shell/api/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ """Hermes Web UI -- API modules."""

package/vendor/agent-frontend-shell/api/agent_health.py ADDED Viewed

@@ -0,0 +1,392 @@
+"""Hermes agent/gateway heartbeat payload helpers (#716, #1879).
+The WebUI process is not always paired with a long-running Hermes gateway. Some
+setups use WebUI only, while self-hosted messaging deployments run a separate
+Hermes gateway daemon that records runtime metadata in the Hermes Agent home.
+This module turns those existing safe runtime signals into a small UI-facing
+heartbeat without shelling out or adding psutil as a hard dependency.
+Cross-container note (#1879): ``gateway.status.get_running_pid()`` uses
+``fcntl.flock`` and ``os.kill(pid, 0)``, both of which require the caller to
+share a PID namespace with the gateway process. In multi-container deployments
+where the WebUI runs separately from ``hermes-agent`` and only a Hermes data
+volume is shared, those checks always return ``None`` and the dashboard
+incorrectly shows "Gateway not running". To stay accurate without forcing a
+``pid: "service:hermes-agent"`` compose workaround, we accept a recent
+``updated_at`` timestamp on ``gateway_state.json`` (combined with
+``gateway_state == "running"``) as an equivalent live-process signal.  Older
+gateway builds do not refresh that file periodically, so a stale
+``gateway_state == "running"`` record is treated as inconclusive rather than a
+confirmed outage.
+"""
+from __future__ import annotations
+import importlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+_GATEWAY_PID_FILE = "gateway.pid"
+_GATEWAY_RUNTIME_STATUS_FILE = "gateway_state.json"
+# Two cron ticks (~60s each). Chosen to avoid false negatives during brief
+# gateway restarts while still surfacing a true outage within a couple of
+# minutes. Override is intentionally not exposed: keep the check deterministic
+# and identical across deployments so support diagnostics are reproducible.
+GATEWAY_FRESHNESS_THRESHOLD_S: float = 120.0
+def _checked_at() -> str:
+    return datetime.now(timezone.utc).isoformat()
+def _runtime_status_is_fresh(
+    runtime_status: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    threshold_s: float = GATEWAY_FRESHNESS_THRESHOLD_S,
+) -> bool:
+    """Return ``True`` when ``gateway_state.json`` looks freshly written.
+    "Fresh" means the gateway self-reported ``running`` and the ``updated_at``
+    ISO-8601 timestamp is no older than ``threshold_s`` seconds. This is the
+    cross-container liveness signal used when ``get_running_pid()`` returns
+    ``None`` purely because of PID-namespace isolation (#1879).
+    Any unparseable input is treated as "not fresh" — a stale or missing
+    timestamp must never report alive.
+    """
+    if not isinstance(runtime_status, dict):
+        return False
+    if runtime_status.get("gateway_state") != "running":
+        return False
+    raw_updated_at = runtime_status.get("updated_at")
+    if not isinstance(raw_updated_at, str) or not raw_updated_at:
+        return False
+    # ``datetime.fromisoformat`` accepts the exact format gateway/status.py
+    # writes (``datetime.now(timezone.utc).isoformat()``). We deliberately
+    # don't pull in dateutil — keeping this stdlib-only matches the rest of
+    # this module.
+    try:
+        updated_at = datetime.fromisoformat(raw_updated_at)
+    except (TypeError, ValueError):
+        return False
+    if updated_at.tzinfo is None:
+        # A naive timestamp could mean anything across containers / hosts.
+        # Refuse to interpret it rather than assume UTC.
+        return False
+    reference = now if now is not None else datetime.now(timezone.utc)
+    age_s = (reference - updated_at).total_seconds()
+    if age_s < 0:
+        # Clock skew between containers can produce small negatives. A future
+        # timestamp is still a "fresh" signal — the gateway clearly wrote it
+        # very recently — so accept it. A wildly-future timestamp (> threshold
+        # in the future) is rejected to avoid trusting a broken clock.
+        return -age_s <= threshold_s
+    return age_s <= threshold_s
+def _runtime_status_is_stale_stopped(
+    runtime_status: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    threshold_s: float = GATEWAY_FRESHNESS_THRESHOLD_S,
+) -> bool:
+    """Return ``True`` for an old clean-stop root gateway state.
+    A user may run only profile-scoped gateways while a root
+    ``gateway_state.json`` from an older, intentionally stopped gateway remains
+    on disk (#1944). Treat that stale stopped file like "no root gateway
+    configured" so the heartbeat banner does not keep warning about a service
+    the user is not running. Fresh stopped state still reports down.
+    """
+    if not isinstance(runtime_status, dict):
+        return False
+    if runtime_status.get("gateway_state") != "stopped":
+        return False
+    raw_updated_at = runtime_status.get("updated_at")
+    if not isinstance(raw_updated_at, str) or not raw_updated_at:
+        return False
+    try:
+        updated_at = datetime.fromisoformat(raw_updated_at)
+    except (TypeError, ValueError):
+        return False
+    if updated_at.tzinfo is None:
+        return False
+    reference = now if now is not None else datetime.now(timezone.utc)
+    age_s = (reference - updated_at).total_seconds()
+    return age_s > threshold_s
+def _runtime_status_is_stale_running(
+    runtime_status: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    threshold_s: float = GATEWAY_FRESHNESS_THRESHOLD_S,
+) -> bool:
+    """Return ``True`` when the gateway last self-reported running, but stale.
+    WebUI often runs in a separate container from the gateway. In that shape PID
+    checks can be impossible, and older gateway versions only update
+    ``gateway_state.json`` on lifecycle/platform changes. A stale ``running``
+    file therefore means "not enough information from WebUI" rather than
+    "gateway is down".
+    """
+    if not isinstance(runtime_status, dict):
+        return False
+    if runtime_status.get("gateway_state") != "running":
+        return False
+    raw_updated_at = runtime_status.get("updated_at")
+    if not isinstance(raw_updated_at, str) or not raw_updated_at:
+        return False
+    try:
+        updated_at = datetime.fromisoformat(raw_updated_at)
+    except (TypeError, ValueError):
+        return False
+    if updated_at.tzinfo is None:
+        return False
+    reference = now if now is not None else datetime.now(timezone.utc)
+    age_s = (reference - updated_at).total_seconds()
+    return age_s > threshold_s
+def _gateway_status_module():
+    """Load gateway.status lazily so tests and WebUI-only installs stay isolated."""
+    return importlib.import_module("gateway.status")
+def _gateway_root_pid_path() -> Path | None:
+    """Return the root Hermes gateway PID path.
+    Gateway runtime files are root-level singletons.  A profile-scoped WebUI
+    process may have HERMES_HOME=<root>/profiles/<name>, but gateway.pid,
+    gateway.lock, and gateway_state.json still live under <root>.
+    When the root-level gateway.pid is absent (profile-scoped gateway
+    deployments write it under <root>/profiles/<name>/), fall back to the
+    active profile's directory so the gateway is detected correctly.
+    """
+    try:
+        from hermes_constants import get_default_hermes_root
+        root_pid = get_default_hermes_root() / _GATEWAY_PID_FILE
+        if root_pid.exists():
+            return root_pid
+        try:
+            from api.profiles import get_active_hermes_home
+            profile_pid = Path(get_active_hermes_home()) / _GATEWAY_PID_FILE
+            if profile_pid.exists():
+                return profile_pid
+        except Exception:
+            pass
+        return root_pid
+    except Exception:
+        return None
+def _read_runtime_status_path(path: Path) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if isinstance(payload, dict):
+        return payload
+    return None
+def _read_gateway_runtime_status(gateway_status: Any, pid_path: Path | None) -> dict[str, Any] | None:
+    read_runtime_status = gateway_status.read_runtime_status
+    if pid_path is not None:
+        try:
+            return read_runtime_status(pid_path=pid_path)
+        except TypeError:
+            try:
+                return read_runtime_status(pid_path)
+            except TypeError:
+                if getattr(gateway_status, "__name__", "") == "gateway.status" or hasattr(
+                    gateway_status,
+                    "_read_json_file",
+                ):
+                    runtime_status_file = str(
+                        getattr(gateway_status, "_RUNTIME_STATUS_FILE", _GATEWAY_RUNTIME_STATUS_FILE)
+                    )
+                    runtime_status = _read_runtime_status_path(pid_path.with_name(runtime_status_file))
+                    if runtime_status is not None:
+                        return runtime_status
+    return read_runtime_status()
+def _gateway_running_pid(gateway_status: Any, pid_path: Path | None) -> int | None:
+    get_running_pid = gateway_status.get_running_pid
+    if pid_path is not None:
+        try:
+            return get_running_pid(pid_path=pid_path, cleanup_stale=False)
+        except TypeError:
+            try:
+                return get_running_pid(pid_path, cleanup_stale=False)
+            except TypeError:
+                pass
+    try:
+        return get_running_pid(cleanup_stale=False)
+    except TypeError:
+        # Older agent versions may not expose cleanup_stale. Keep compatibility.
+        return get_running_pid()
+def _runtime_detail_subset(runtime_status: dict[str, Any] | None) -> dict[str, Any]:
+    """Return only non-sensitive runtime fields for the browser.
+    gateway.status records argv/PID metadata so the CLI can validate process
+    identity. The WebUI alert only needs health semantics, never raw command
+    lines, paths, environment, or tokens.
+    """
+    if not isinstance(runtime_status, dict):
+        return {}
+    details: dict[str, Any] = {}
+    gateway_state = runtime_status.get("gateway_state")
+    if isinstance(gateway_state, str) and gateway_state:
+        details["gateway_state"] = gateway_state
+    updated_at = runtime_status.get("updated_at")
+    if isinstance(updated_at, str) and updated_at:
+        details["updated_at"] = updated_at
+    try:
+        details["active_agents"] = max(0, int(runtime_status.get("active_agents") or 0))
+    except (TypeError, ValueError):
+        pass
+    platforms = runtime_status.get("platforms")
+    if isinstance(platforms, dict):
+        details["platform_count"] = len(platforms)
+        states: dict[str, int] = {}
+        for payload in platforms.values():
+            if not isinstance(payload, dict):
+                continue
+            state = payload.get("state")
+            if isinstance(state, str) and state:
+                states[state] = states.get(state, 0) + 1
+        if states:
+            details["platform_states"] = states
+    return details
+def build_agent_health_payload() -> dict[str, Any]:
+    """Return `{alive, checked_at, details}` for the Hermes gateway/agent.
+    `alive` is intentionally tri-state:
+      * True: a gateway runtime signal says the process is alive.
+      * False: gateway metadata exists, but no live gateway process owns it.
+      * None: no gateway metadata/status is available, so this WebUI setup is
+        probably not configured with a separate gateway process.
+    """
+    checked_at = _checked_at()
+    try:
+        gateway_status = _gateway_status_module()
+    except Exception as exc:
+        return {
+            "alive": None,
+            "checked_at": checked_at,
+            "details": {
+                "state": "unknown",
+                "reason": "gateway_status_unavailable",
+                "error": type(exc).__name__,
+            },
+        }
+    gateway_pid_path = _gateway_root_pid_path()
+    runtime_status = None
+    try:
+        runtime_status = _read_gateway_runtime_status(gateway_status, gateway_pid_path)
+    except Exception:
+        runtime_status = None
+    try:
+        running_pid = _gateway_running_pid(gateway_status, gateway_pid_path)
+    except Exception:
+        running_pid = None
+    safe_details = _runtime_detail_subset(runtime_status)
+    if running_pid is not None:
+        return {
+            "alive": True,
+            "checked_at": checked_at,
+            "details": {
+                "state": "alive",
+                **safe_details,
+            },
+        }
+    # Cross-container fallback (#1879): when ``get_running_pid()`` cannot see
+    # the gateway because we're in a different PID namespace, a recent
+    # ``updated_at`` on ``gateway_state.json`` is a reliable equivalent signal
+    # since the gateway writes it on every tick. We only trust this fallback
+    # when the gateway also self-reports ``gateway_state == "running"`` so
+    # crash-without-cleanup scenarios still surface as "down".
+    if _runtime_status_is_fresh(runtime_status):
+        return {
+            "alive": True,
+            "checked_at": checked_at,
+            "details": {
+                "state": "alive",
+                "reason": "cross_container_freshness",
+                **safe_details,
+            },
+        }
+    if _runtime_status_is_stale_stopped(runtime_status):
+        return {
+            "alive": None,
+            "checked_at": checked_at,
+            "details": {
+                "state": "unknown",
+                "reason": "gateway_stale_stopped_state",
+                **safe_details,
+            },
+        }
+    if _runtime_status_is_stale_running(runtime_status):
+        return {
+            "alive": None,
+            "checked_at": checked_at,
+            "details": {
+                "state": "unknown",
+                "reason": "gateway_stale_running_state",
+                **safe_details,
+            },
+        }
+    if isinstance(runtime_status, dict):
+        return {
+            "alive": False,
+            "checked_at": checked_at,
+            "details": {
+                "state": "down",
+                "reason": "gateway_not_running",
+                **safe_details,
+            },
+        }
+    return {
+        "alive": None,
+        "checked_at": checked_at,
+        "details": {
+            "state": "unknown",
+            "reason": "gateway_not_configured",
+        },
+    }