The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(webapp): give a standalone profile its own Web Access port
unsupportedpastels975446bb88a4
diff --git a/hermes_cli/web_routers/webapp_access.py b/hermes_cli/web_routers/webapp_access.pyindex 81eeeab643e..6fb1a18b179 100644--- a/hermes_cli/web_routers/webapp_access.py+++ b/hermes_cli/web_routers/webapp_access.py@@ -120,12 +120,12 @@ async def webapp_access_status(profile: Optional[str] = None):async def start_webapp_access(body: StartBody, profile: Optional[str] = None):profile = destructive_profile(profile, "POST /api/webapp-access/start")async with _one_change_at_a_time():- gateway, (host, public_url, callback) = await _scoped(+ gateway, (host, port, public_url, callback) = await _scoped(profile, lambda gateway: (gateway, webapp_access.plan(body.mode, body.public_url)))# The bundle before anything lasting: a failed build registers, writes and restarts nothing.await _in_gateway_home(gateway, webapp_access.build_bundle)await _in_gateway_home(gateway, lambda: webapp_access.register(callback))- await _scoped(profile, lambda _gateway: webapp_access.serve(host, public_url), config_write=True)+ await _scoped(profile, lambda _gateway: webapp_access.serve(host, public_url, port), config_write=True)return await _restart(gateway, "turning on Web Access")diff --git a/hermes_cli/webapp_access.py b/hermes_cli/webapp_access.pyindex 733a6c69a0d..910a0d380aa 100644--- a/hermes_cli/webapp_access.py+++ b/hermes_cli/webapp_access.py@@ -152,25 +152,101 @@ def _register_nous_sign_in(callback_url: str) -> None:atomic_write_text(path, json.dumps(record) + "\n", mode=0o600)-def plan(mode: str, public_url: Optional[str] = None) -> tuple[str, str, str]:- """Check that *mode* can be served and signed in to; returns ``(host, public_url, callback)``:- the bind host and the URL to pin for :func:`serve`, and the sign-in callback for- :func:`register`. Changes nothing, so Start runs it before any slow or lasting step."""- from gateway.webapp_listener import webapp_settings-+def plan(mode: str, public_url: Optional[str] = None) -> tuple[str, Optional[int], str, str]:+ """Check that *mode* can be served and signed in to; returns ``(host, port, public_url, callback)``:+ the bind host, the port to write (None to keep the config's, :func:`_port_to_serve`) and the URL to+ pin for :func:`serve`, and the sign-in callback for :func:`register`. Changes nothing, so Start+ runs it before any slow or lasting step."""if mode == "lan":address = lan_address()if address is None:raise WebappAccessError("This machine has no network address other devices can reach.")- host, url, pinned = "0.0.0.0", f"http://{address}:{webapp_settings(gateway_home()).port}", ""+ host, pinned = "0.0.0.0", ""+ serving, port = _port_to_serve(gateway_home(), host)+ url = f"http://{address}:{serving}"elif mode == "public":host, url = "127.0.0.1", _public_url(public_url)pinned = url+ port = _port_to_serve(gateway_home(), host)[1]else:raise WebappAccessError(f"Unknown access mode {mode!r}.")if not nous_signed_in():raise WebappAccessError("Sign in to your Nous account under Providers first.")- return host, pinned, f"{url}/auth/callback"+ return host, port, pinned, f"{url}/auth/callback"+++#: How many ports above the default Start tries for a standalone profile's Webapp.+_PORT_SEARCH = 100+++def _port_to_serve(home: Path, host: str) -> tuple[int, Optional[int]]:+ """``(port, port to write)`` for the Webapp of *home*'s gateway, bound on *host*.++ A ``webapp.port`` in *home*'s config is the user's, and so is the default profile's gateway, which+ serves the documented address (9120 unless set): both keep it, and Start writes no port. A standalone+ profile's gateway with no ``webapp.port`` would find the default port taken by the default gateway's+ Webapp, so it gets the first port above it that no other Hermes home on this machine claims and+ nothing listens on now, and Start writes it to that profile's ``webapp.port``: the profile keeps that+ address across restarts, and the gateway, the launcher and the sign-in callback all use it."""+ from gateway.webapp_listener import DEFAULT_PORT, webapp_settings+ from hermes_constants import named_profile_home++ if _own_port(home) is not None or named_profile_home(home) is None:+ return webapp_settings(home).port, None+ claimed = _claimed_ports(home)+ for port in range(DEFAULT_PORT + 1, DEFAULT_PORT + 1 + _PORT_SEARCH):+ if port not in claimed and _port_free(host, port):+ return port, port+ raise WebappAccessError(f"No free port for the Webapp from {DEFAULT_PORT + 1} to {DEFAULT_PORT + _PORT_SEARCH}. "+ f"Set webapp.port in {home / 'config.yaml'} to a free port, then start again.")+++def _own_port(home: Path) -> Optional[object]:+ """The ``webapp.port`` *home*'s ``config.yaml`` sets, valid or not (the gateway reports an invalid+ one by name), or None when it sets none. The file as written: the defaults name a port for everyone."""+ from ruamel.yaml.error import YAMLError++ from hermes_cli.config import read_user_config_raw++ try:+ document = read_user_config_raw(Path(home) / "config.yaml")+ except (OSError, ValueError, YAMLError): # the gateway reports an unreadable config itself+ return None+ block = document.get("webapp") if isinstance(document, dict) else None+ return block.get("port") if isinstance(block, dict) else None+++def _claimed_ports(home: Path) -> set[int]:+ """The Webapp ports the other Hermes homes beside *home* claim: the default profile's (9120 unless+ set) and every other profile's own ``webapp.port``, whether or not its gateway runs now. Only that+ setting is read from their configs."""+ from gateway.webapp_listener import DEFAULT_PORT+ from hermes_constants import named_profile_home++ profile = named_profile_home(home)+ if profile is None:+ return set()+ root = profile.parent.parent+ root_port = _own_port(root)+ claimed = {root_port if isinstance(root_port, int) else DEFAULT_PORT}+ for other in profile.parent.iterdir() if profile.parent.is_dir() else ():+ port = _own_port(other) if other != profile and other.is_dir() else None+ if isinstance(port, int) and not isinstance(port, bool):+ claimed.add(port)+ return claimed+++def _port_free(host: str, port: int) -> bool:+ """Whether a listener could bind *host*:*port* now, as the gateway's does."""+ family = socket.AF_INET6 if ":" in host else socket.AF_INET+ with socket.socket(family, socket.SOCK_STREAM) as probe:+ if os.name != "nt": # as the gateway's listener; on Windows the option would share a bound port+ probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)+ try:+ probe.bind((host, port))+ except OSError:+ return False+ return Truedef build_bundle() -> None:@@ -193,9 +269,10 @@ def register(callback_url: str) -> None:_register_nous_sign_in(callback_url)-def serve(host: str, public_url: str) -> None:- """Serve the Webapp on *host* from the gateway's next start. Call :func:`register` first."""- _write_config(enabled=True, host=host, public_url=public_url)+def serve(host: str, public_url: str, port: Optional[int] = None) -> None:+ """Serve the Webapp on *host* (and *port* when :func:`plan` chose one) from the gateway's next+ start. Call :func:`register` first."""+ _write_config(enabled=True, host=host, public_url=public_url, port=port)def turn_off() -> None:@@ -203,16 +280,16 @@ def turn_off() -> None:_write_config(enabled=False)-def _write_config(*, enabled: bool, host: str = "", public_url: str = "") -> None:+def _write_config(*, enabled: bool, host: str = "", public_url: str = "", port: Optional[int] = None) -> None:"""The ``webapp:`` block, and nothing outside it. Starting pins ``webapp.public_url`` for theown-URL mode and drops it for LAN, where the callback follows each request; stopping changes- only ``enabled``, so the next start offers the same address. ``webapp.port`` is the user's:- a second gateway on this machine needs a port of its own."""+ only ``enabled``, so the next start offers the same address. ``webapp.port`` is the user's; only a+ standalone profile that has none gets the free one :func:`plan` chose, once."""from hermes_cli.config import load_config, save_configcfg = load_config()webapp = cfg.get("webapp") if isinstance(cfg.get("webapp"), dict) else {}- webapp.update(enabled=enabled, **({"host": host} if enabled else {}))+ webapp.update(enabled=enabled, **({"host": host} if enabled else {}), **({"port": port} if port else {}))if enabled and public_url:webapp["public_url"] = public_urlelif enabled:diff --git a/tests/hermes_cli/test_webapp_access_ports.py b/tests/hermes_cli/test_webapp_access_ports.pynew file mode 100644index 00000000000..f01f7cdbac6--- /dev/null+++ b/tests/hermes_cli/test_webapp_access_ports.py@@ -0,0 +1,130 @@+"""Which port Web Access serves a gateway's Webapp on (``hermes_cli.webapp_access._port_to_serve``).++The default profile's gateway serves the documented address, 9120 unless ``webapp.port`` says otherwise.+A standalone profile has a gateway of its own; turning Web Access on there without a ``webapp.port`` used+to bind 9120 too, which the default gateway's Webapp holds, so nothing was served. Start now gives such a+profile the first port above 9120 that no other Hermes home claims and nothing listens on, and writes it to+that profile's ``webapp.port``, so the gateway binds it, the launcher prints and opens it, the sign-in+callback names it, and it stays the same across restarts. A ``webapp.port`` the user set always stays.+No test binds a real port: what listens is faked, and the probe itself is checked on OS-chosen ports.+"""+import socket+from pathlib import Path++import pytest++from hermes_cli import webapp_access+++def _write(path: Path, text: str) -> Path:+ path.mkdir(parents=True, exist_ok=True)+ (path / "config.yaml").write_text(text, encoding="utf-8")+ return path+++def machine(monkeypatch, tmp_path):+ """A Hermes root with a standalone profile ``solo`` and a sibling ``other`` that claims 9122; 9121 is+ in use by something else. The process runs as ``solo`` (Web Access scopes to its gateway's home)."""+ root = _write(tmp_path / ".hermes", "")+ solo = _write(root / "profiles" / "solo", "gateway:\n standalone: true\n")+ _write(root / "profiles" / "other", "gateway:\n standalone: true\nwebapp:\n port: 9122\n")+ listening = {9121}+ probed: list[tuple[str, int]] = []++ def port_free(host, port):+ probed.append((host, port))+ return port not in listening++ monkeypatch.setattr(webapp_access, "_port_free", port_free, raising=False)+ monkeypatch.setattr(webapp_access, "nous_signed_in", lambda: True)+ monkeypatch.setattr(webapp_access, "lan_address", lambda: "192.168.1.50")+ monkeypatch.setenv("HERMES_HOME", str(solo))+ return {"root": root, "solo": solo, "listening": listening, "probed": probed, "monkeypatch": monkeypatch}+++def _webapp_block(home: Path) -> dict:+ from hermes_cli.config import read_user_config_raw++ return read_user_config_raw(home / "config.yaml").get("webapp") or {}+++def test_a_standalone_profile_without_a_port_gets_a_free_one_that_every_surface_uses(machine):+ from gateway.webapp_listener import dial_origin, listener_plan++ assert webapp_access.gateway_home() == machine["solo"]+ planned = webapp_access.plan("lan")+ # 9120 is the default profile's, 9121 is in use, 9122 is the other profile's.+ assert planned[-1] == "http://192.168.1.50:9123/auth/callback"+ host, port, public_url, _callback = planned+ assert (host, port, public_url) == ("0.0.0.0", 9123, "")+ webapp_access.serve(host, public_url, port)+ assert _webapp_block(machine["solo"]) == {"enabled": True, "host": "0.0.0.0", "port": 9123}+ # The gateway binds that port, and the address the launcher prints and opens is built on it.+ bind_host, bind_port, mount, _reason = listener_plan(machine["solo"])+ assert (bind_host, bind_port) == ("0.0.0.0", 9123) and mount is not None+ assert dial_origin(bind_host, bind_port) == "http://127.0.0.1:9123"+ assert webapp_access.access_status()["port"] == 9123+ assert _webapp_block(machine["root"]) == {}+++def test_the_chosen_port_stays_for_that_profile(machine):+ host, port, public_url, _ = webapp_access.plan("lan")+ webapp_access.serve(host, public_url, port)+ webapp_access.turn_off()+ machine["probed"].clear()+ machine["listening"].add(9123) # its own gateway may hold it now+ for mode, url, expected in (("lan", None, "http://192.168.1.50:9123/auth/callback"),+ ("public", "https://solo.example.test", "https://solo.example.test/auth/callback")):+ host, port, public_url, callback = webapp_access.plan(mode, url)+ assert port is None # nothing to write: the config already has it+ assert callback == expected+ webapp_access.serve(host, public_url, port)+ assert _webapp_block(machine["solo"])["port"] == 9123+ assert machine["probed"] == []+++def test_the_own_url_mode_also_gets_a_free_port(machine):+ host, port, _public_url, callback = webapp_access.plan("public", "https://solo.example.test")+ assert (host, port, callback) == ("127.0.0.1", 9123, "https://solo.example.test/auth/callback")+ assert machine["probed"][-1] == ("127.0.0.1", 9123)+++def test_the_default_profile_keeps_the_documented_port_and_writes_none(machine):+ machine["monkeypatch"].setenv("HERMES_HOME", str(machine["root"]))+ host, port, public_url, callback = webapp_access.plan("lan")+ assert port is None and callback == "http://192.168.1.50:9120/auth/callback"+ webapp_access.serve(host, public_url, port)+ assert "port" not in _webapp_block(machine["root"])+ assert machine["probed"] == []++[email protected]("configured", [9555, 9120, "not-a-port"])+def test_a_port_the_user_set_is_never_replaced(machine, configured):+ """Even one another gateway holds, or an invalid one: the gateway then says why by the setting's name."""+ _write(machine["solo"], f"gateway:\n standalone: true\nwebapp:\n port: {configured}\n")+ host, port, public_url, _callback = webapp_access.plan("lan")+ assert port is None and machine["probed"] == []+ webapp_access.serve(host, public_url, port)+ assert _webapp_block(machine["solo"])["port"] == configured+++def test_with_no_free_port_start_refuses_and_names_the_setting(machine):+ machine["listening"].update(range(9121, 9221))+ with pytest.raises(webapp_access.WebappAccessError) as refused:+ webapp_access.plan("lan")+ assert "webapp.port" in str(refused.value) and str(machine["solo"] / "config.yaml") in str(refused.value)+ assert "port" not in _webapp_block(machine["solo"])+++def test_the_probe_sees_a_port_a_listener_holds():+ """On a port the OS picked, not a real service's."""+ with socket.socket() as held:+ held.bind(("127.0.0.1", 0))+ held.listen()+ port = held.getsockname()[1]+ assert webapp_access._port_free("127.0.0.1", port) is False+ with socket.socket() as probe:+ probe.bind(("127.0.0.1", 0))+ free = probe.getsockname()[1]+ assert webapp_access._port_free("127.0.0.1", free) is Truediff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.mdindex 0b841f59c20..8c64bd991a1 100644--- a/website/docs/user-guide/configuration.md+++ b/website/docs/user-guide/configuration.md@@ -3181,7 +3181,7 @@ webapp:- `enabled` — the gateway reads it at start; restart the gateway after changing it (`hermes gateway restart`).- `host` — `127.0.0.1`, `::1` or `localhost` keeps the Webapp on this machine. `0.0.0.0` or `::` makes it reachable from other machines and requires a [dashboard sign-in provider](./features/web-dashboard.md#authentication-gated-mode); without one the gateway serves native clients only and `hermes webapp --status` says why. Restart the gateway after adding the provider. Any other value, another loopback address such as `127.0.0.2` included, keeps the Webapp off.-- `port` — when the port is taken, the gateway likewise serves native clients only and `hermes webapp --status` reports why. It also replaces the Webapp's browser sign-in, since another program may have received it, so open tabs need `hermes webapp` again once the port is free.+- `port` — a standalone profile's gateway needs a port other than the default gateway's. **Settings → Web Access → Start** picks one for a standalone profile that sets none (the first free port above 9120 no other profile uses) and saves it here; it never replaces a port you set. When the port is taken, the gateway likewise serves native clients only and `hermes webapp --status` reports why. It also replaces the Webapp's browser sign-in, since another program may have received it, so open tabs need `hermes webapp` again once the port is free.- `public_url` — set it when a reverse proxy or tunnel you run serves the Webapp at its own address (forwarding to `host:port`). It turns on dashboard sign-in even on a loopback `host`, it is the one outside hostname the Webapp accepts requests for, and sign-in callbacks are built on it. Without a sign-in provider the gateway serves native clients only, as for `0.0.0.0`. It must be an `http://` or `https://` address with no credentials, query or fragment; anything else keeps the Webapp off. `dashboard.public_url` is for `hermes dashboard` and never applies to the Webapp.Sign-in turns on when `host` is `0.0.0.0` or `::`, or when `public_url` is set, whatever the host. `hermes webapp` then opens the Webapp's address (`public_url` when set, where sign-in returns) for you to sign in with your dashboard account: its one-use links only open a Webapp that needs no sign-in. Native clients (the CLI, TUI and Desktop app) never sign in: the gateway's listener for them never asks for it, whatever the config says.diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.mdindex 30a1f243bcc..4172ae08534 100644--- a/website/docs/user-guide/desktop.md+++ b/website/docs/user-guide/desktop.md@@ -115,8 +115,9 @@ your Nous account (Providers → Accounts). It appears only in the native app onand only that app can change it: a browser signed in over the network cannot.- **This network:** devices on the same Wi-Fi open `http://<this computer's address>:<port>`, where the- port is `webapp.port` (9120 unless you set another). This is plain HTTP: the connection is not- encrypted, so others on the network could read it. Use it only on a network you trust.+ port is `webapp.port` (9120 unless you set another, or Start chose one for a standalone profile).+ This is plain HTTP: the connection is not encrypted, so others on the network could read it. Use it+ only on a network you trust.- **My own URL:** an HTTPS address you already run (Tailscale Serve, a tunnel or a reverse proxy) thatforwards to `http://127.0.0.1:<port>`. It is saved as `webapp.public_url`. Never forward that portfrom your router directly.@@ -134,8 +135,10 @@ Web Access changes only the `webapp:` settings and keeps your `webapp.port`. ItIts Nous sign-in uses a sign-in client of its own, which the first Start registers with your Nousaccount and keeps in the gateway's home (`webapp/sign-in-registration.json`). Start never reads orwrites `HERMES_DASHBOARD_OAUTH_CLIENT_ID` in `.env`, so turning Web Access on never changes the-standalone dashboard's Nous sign-in. A standalone profile with its own gateway needs its own-`webapp.port` to serve a Webapp beside the default gateway's. `hermes update` rebuilds the Webapp+standalone dashboard's Nous sign-in. A standalone profile with its own gateway serves its Webapp on a+port of its own: when its `webapp.port` is unset, the first Start picks the first free port above 9120+that no other profile uses and saves it as that profile's `webapp.port`, so its address stays the same+after restarts. A `webapp.port` you set is always kept. `hermes update` rebuilds the Webappwhenever a profile has it turned on.If that build fails, the gateway reports the Webapp unavailable, and the page says so, until`hermes webapp` rebuilds it.