diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md index 30c55a9ae6..b5740090e0 100644 --- a/website/docs/user-guide/features/web-dashboard.md +++ b/website/docs/user-guide/features/web-dashboard.md @@ -105,6 +105,26 @@ The landing page shows a live overview of your installation: The status page auto-refreshes every 5 seconds. +#### Resource pressure banner + +When the host is running low on memory or disk, a banner appears at the top of +the dashboard (fed by the same status poll — no extra requests): + +- **"Your agent is almost out of memory and may restart"** — system available + memory has dropped to *elevated* (< 128 MiB or < 15%) or *critical* + (< 64 MiB or < 5%) levels, as sampled by the gateway's 30-second heartbeat. +- **"Your agent restarted unexpectedly, most likely because it ran out of + memory"** — the lifecycle ledger recorded an unclean exit under memory + pressure on the previous boot (a suspected OOM kill). +- **Disk warnings** — the volume holding `~/.hermes` is nearly full + (*elevated* below 512 MB free, *critical* below 256 MB free). + +Only the most severe active warning shows at a time (disk critical > memory +critical > OOM restart > disk elevated > memory elevated). Dismissals are +scoped to the current gateway boot: dismissing a warning surfaces the next +active one, a gateway restart or an escalation (elevated → critical) re-opens +it, and a stale heartbeat renders nothing rather than a spurious alert. + ### Chat The **Chat** tab embeds the full Hermes TUI (the same interface you get from `hermes --tui`) directly in the browser. Everything you can do in the terminal TUI — slash commands, model picker, tool-call cards, markdown streaming, clarify/sudo/approval prompts, skin theming — works identically here, because the dashboard is running the real TUI binary and rendering its ANSI output through [xterm.js](https://xtermjs.org/) with its WebGL renderer for pixel-perfect cell layout. @@ -415,6 +435,29 @@ a chat under the selected profile. Returns agent version, gateway status, platform states, and active session count. +The response also carries two advisory resource blocks (they never affect the +`components`/`overall` health verdict): + +- **`memory`** — distilled from the gateway's 30-second heartbeat and the + lifecycle ledger. Fields: `pressure` (`ok` / `elevated` / `critical` / + `unknown`), `gateway_rss_mb`, `system_total_mb`, `system_available_mb`, + `swap_used_mb`, `sampled_at`, `boot_id`, `last_boot_unclean`, + `last_boot_suspected_oom`. Pressure is `elevated` below 128 MiB (or 15%) of + available system memory and `critical` below 64 MiB (or 5%) — the same + levels at which a subsequent unclean exit would be flagged as a suspected + OOM kill. Heartbeats older than 150 seconds (or future-dated) keep their + numbers but degrade `pressure` to `unknown`, so a dead gateway's last + sample can't masquerade as a live reading. +- **`disk`** — a live `shutil.disk_usage()` sample of the volume holding + `~/.hermes`. Fields: `pressure`, `free_mb`, `total_mb`, `used_percent`, + `sampled_at`. Pressure is `elevated` below 512 MB free (or ≥85% used with + under 4 GB headroom) and `critical` below 256 MB free (or ≥95% used with + under 1 GB headroom). + +Both collectors are fail-safe: any sampling error degrades the block to +`{"pressure": "unknown"}` instead of failing the status endpoint. The numbers +are coarse (whole MB, whole-percent) since `/api/status` is public. + ### GET /api/sessions Returns the 20 most recent sessions with metadata (model, token counts, timestamps, preview).