feat(cli): make hermes serve a real headless backend

`serve` (added in #54568) reused cmd_dashboard wholesale, so it still
behaved like a dashboard: it ran a full vite build every launch, mounted
and served the SPA whenever a stray web_dist/ existed, printed
"Hermes Web UI →", and announced HERMES_DASHBOARD_READY. It's the headless
JSON-RPC/WS backend the desktop app and remote clients run — pure socket
clients that never load the browser SPA.

Mark serve with headless_backend=True (resolved once in cmd_dashboard) and:

- skip _build_web_ui entirely on the serve path
- export HERMES_SERVE_HEADLESS=1 so mount_spa() disables the SPA even when a
  dist is present — only the JSON-RPC/WS/API surface is reachable
- announce the bind ("Hermes backend listening on host:port") instead of a
  browser/auth-gated URL
- print a neutral HERMES_BACKEND_READY sentinel; dashboard keeps the legacy
  one and the desktop port-discovery regex matches either
- preserve serve across the named-profile re-exec so it can't rebuild as
  dashboard

`hermes dashboard` is unchanged (builds + serves the browser UI). Backward
compatible: old apps only ever spawn dashboard (legacy token + UI intact)
and never invoke serve; the ready-file side channel is name-agnostic. The
one behavior change is that a remote `hermes serve` no longer serves the
browser dashboard as a side effect — that's `hermes dashboard`'s job.

Tests: serve headless_backend contract, SPA-disabled-with-dist, the
HERMES_BACKEND_READY desktop parse (17/17 node), and the existing
serve/dashboard/web_server suites. AGENTS.md documents the behavior.
This commit is contained in:
Brooklyn Nicholson 2026-06-30 17:58:47 -05:00
parent 812236bff8
commit f0f8c84d1b
8 changed files with 93 additions and 16 deletions

View file

@ -12837,13 +12837,21 @@ def mount_spa(application: FastAPI):
and the SPA's runtime ``__HERMES_BASE_PATH__`` honour that prefix
without rebuilding the bundle.
"""
if not WEB_DIST.exists():
# `hermes serve` is the headless backend: it must NEVER serve the browser
# SPA, even if a dist is lying around from a prior `dashboard`/build. Take
# the no-frontend path so only the JSON-RPC/WS/API surface is reachable.
_headless = os.environ.get("HERMES_SERVE_HEADLESS") == "1"
if _headless or not WEB_DIST.exists():
_msg = (
"Headless backend (hermes serve): web UI disabled — use "
"`hermes dashboard` for the browser UI."
if _headless
else "Frontend not built. Run: cd web && npm run build"
)
@application.get("/{full_path:path}")
async def no_frontend(full_path: str):
return JSONResponse(
{"error": "Frontend not built. Run: cd web && npm run build"},
status_code=404,
)
return JSONResponse({"error": _msg}, status_code=404)
return
_index_path = WEB_DIST / "index.html"
@ -13998,6 +14006,7 @@ def start_server(
open_browser: bool = True,
allow_public: bool = False,
initial_profile: str = "",
headless: bool = False,
):
"""Start the web UI server.
@ -14005,6 +14014,10 @@ def start_server(
URL as ``?profile=<name>`` so the SPA's profile switcher preselects it
used when a profile alias (``<profile> dashboard``) routes to the
machine dashboard.
``headless`` is the ``serve`` path: the JSON-RPC/WS backend with no UI
build and no SPA mount (mount_spa() honours ``HERMES_SERVE_HEADLESS``), so
the banner announces the bind rather than a browser URL.
"""
import uvicorn
@ -14150,8 +14163,17 @@ def start_server(
app.state.bound_port = actual_port
_write_dashboard_ready_file(actual_port)
print(f"HERMES_DASHBOARD_READY port={actual_port}", flush=True)
print(f" Hermes Web UI → http://{host}:{actual_port}")
# Port-discovery sentinel parsed by the desktop spawn. `serve` is a
# plain backend, not a dashboard, so it announces a neutral token;
# `dashboard` keeps the legacy one. The desktop matches either.
ready_token = "HERMES_BACKEND_READY" if headless else "HERMES_DASHBOARD_READY"
print(f"{ready_token} port={actual_port}", flush=True)
if headless:
# No SPA, and the JSON-RPC/WS endpoints are auth-gated — don't
# advertise a paste-and-connect URL, just announce the bind.
print(f" Hermes backend listening on {host}:{actual_port}")
else:
print(f" Hermes Web UI → http://{host}:{actual_port}")
_maybe_open_browser(host, actual_port, open_browser, initial_profile)
# Collapse the peer-hangup teardown flood (#50005). When the Desktop