web_server_chat.py 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682
  1. """Chat/terminal WebSocket plumbing: PTY bridge selection and registry, WS
  2. client/origin/auth gates, chat argv resolution, gateway/sidecar URL building.
  3. """
  4. import logging
  5. import asyncio
  6. import atexit
  7. import concurrent.futures
  8. import contextlib
  9. import functools
  10. import hmac
  11. import os
  12. import re
  13. import sys
  14. import tempfile
  15. import threading
  16. import urllib.request
  17. from typing import Optional
  18. from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
  19. from pathlib import Path
  20. from typing import Optional
  21. from hermes_cli.pty_session import PtySessionRegistry
  22. # Same logger the code used before extraction (record parity).
  23. _log = logging.getLogger("hermes_cli.web_server")
  24. # /api/pty spawns ``hermes --tui`` behind a pseudo-terminal and forwards bytes +
  25. # resize escapes to xterm.js. POSIX uses pty_bridge (fcntl/termios); native
  26. # Windows uses win_pty_bridge (pywinpty/ConPTY); same surface, no handler guards.
  27. try:
  28. if sys.platform.startswith("win"):
  29. from hermes_cli.win_pty_bridge import WinPtyBridge as PtyBridge, PtyUnavailableError
  30. else:
  31. from hermes_cli.pty_bridge import PtyBridge, PtyUnavailableError
  32. _PTY_BRIDGE_AVAILABLE = True
  33. except ImportError: # pragma: no cover - pywinpty / ptyprocess missing
  34. PtyBridge = None # type: ignore[assignment]
  35. _PTY_BRIDGE_AVAILABLE = False
  36. class PtyUnavailableError(RuntimeError): # type: ignore[no-redef]
  37. """Stub when the platform PTY bridge cannot be imported."""
  38. _RESIZE_RE = re.compile(rb"\x1b\[RESIZE:(\d+);(\d+)\]")
  39. _PTY_READ_CHUNK_TIMEOUT = 0.2
  40. # Back-off between idle PTY reads so a quiet terminal does not spin the event
  41. # loop (keeps dashboard idle CPU low).
  42. # A positive sleep lets other coroutines run and keeps dashboard idle CPU low (#42627).
  43. _PTY_IDLE_BACKOFF = 0.05
  44. PTY_REGISTRY = PtySessionRegistry(
  45. ttl=30 * 60, max_sessions=16, buffer_cap=1 * 1024 * 1024, read_timeout=_PTY_READ_CHUNK_TIMEOUT)
  46. async def _close_stalled_pty_input(ws: WebSocket, *, path: str) -> None:
  47. """Close only the terminal socket when its child stops accepting input."""
  48. _log.warning("pty input stalled path=%s; recycling terminal session", path)
  49. try:
  50. await ws.close(code=1013, reason="PTY input stalled")
  51. except Exception:
  52. pass
  53. async def _legacy_pump(ws: WebSocket, bridge) -> None:
  54. """Original 1:1 socket<->PTY pump: stream until disconnect, then close the
  55. bridge. Used when no ``?attach=`` token is supplied (keep-alive opt-in).
  56. Behavior is identical to the pre-keep-alive ``pty_ws`` body, including the 54028 half-open-socket
  57. protection (reader EOF → close the WS so the writer's ``ws.receive()`` unparks) and the #53227
  58. ``to_thread`` offloads for the blocking ``bridge.close()``.
  59. """
  60. loop = asyncio.get_running_loop()
  61. async def pump_pty_to_ws() -> None:
  62. try:
  63. while True:
  64. chunk = await loop.run_in_executor(None, bridge.read, _PTY_READ_CHUNK_TIMEOUT)
  65. if chunk is None: # EOF
  66. return
  67. if not chunk: # no data this tick; yield control and retry
  68. await asyncio.sleep(_PTY_IDLE_BACKOFF)
  69. continue
  70. try:
  71. await ws.send_bytes(chunk)
  72. except Exception:
  73. return
  74. finally:
  75. # Close the WS so the writer's ``ws.receive()`` returns instead of
  76. # blocking forever on a half-open browser socket (fds would leak and
  77. # auto-reconnect stacks a fresh PTY on each orphan). Reap the bridge
  78. # here too (idempotent): cancelling the handler the instant the WS
  79. # closes can skip the writer's ``finally``.
  80. with contextlib.suppress(Exception):
  81. # The child has exited (EOF) or the send side broke. Closing from the EOF path makes the
  82. # reap independent of that cancellation race (#54028).
  83. await asyncio.to_thread(bridge.close)
  84. with contextlib.suppress(Exception):
  85. await ws.close()
  86. reader_task = asyncio.create_task(pump_pty_to_ws())
  87. try:
  88. while True:
  89. try:
  90. msg = await ws.receive()
  91. except RuntimeError:
  92. # ws.receive() after the socket is already disconnected
  93. # (e.g. closed by the reader task above).
  94. break
  95. if msg.get("type") == "websocket.disconnect":
  96. break
  97. raw = msg.get("bytes")
  98. if raw is None:
  99. text = msg.get("text")
  100. raw = text.encode("utf-8") if isinstance(text, str) else b""
  101. if not raw:
  102. continue
  103. # Resize escape is consumed locally, never written to the PTY.
  104. match = _RESIZE_RE.match(raw)
  105. if match and match.end() == len(raw):
  106. bridge.resize(cols=int(match.group(1)), rows=int(match.group(2)))
  107. continue
  108. if not await bridge.write(raw):
  109. await _close_stalled_pty_input(ws, path="legacy")
  110. break
  111. except WebSocketDisconnect:
  112. pass
  113. finally:
  114. reader_task.cancel()
  115. with contextlib.suppress(asyncio.CancelledError, Exception):
  116. await reader_task
  117. await asyncio.to_thread(bridge.close)
  118. from hermes_cli.web_server_boundary import _LOOPBACK_HOSTS
  119. def _ws_client_reason(ws: WebSocket) -> Optional[str]:
  120. """Return a rejection reason token for the peer IP, or None when allowed
  121. (:func:`hermes_cli.web_server_boundary.ws_client_reason` on the dashboard app state)."""
  122. from hermes_cli.web_server import app
  123. from hermes_cli.web_server_boundary import ws_client_reason
  124. return ws_client_reason(ws, app.state)
  125. def _ws_client_is_allowed(ws: WebSocket) -> bool:
  126. """True when the peer IP passes :func:`_ws_client_reason`."""
  127. return _ws_client_reason(ws) is None
  128. def _ws_host_origin_reason(ws: WebSocket) -> Optional[str]:
  129. """Return ``host_mismatch …`` / ``origin_mismatch …``, or None when allowed
  130. (:func:`hermes_cli.web_server_boundary.ws_host_origin_reason` on the dashboard app state)."""
  131. from hermes_cli.web_server import app
  132. from hermes_cli.web_server_boundary import ws_host_origin_reason
  133. return ws_host_origin_reason(ws, app.state)
  134. def _ws_host_origin_is_allowed(ws: WebSocket) -> bool:
  135. """True when the upgrade passes the dashboard Host/Origin guard."""
  136. return _ws_host_origin_reason(ws) is None
  137. def _ws_request_is_allowed(ws: WebSocket) -> bool:
  138. """Return True when the WebSocket upgrade matches dashboard boundaries."""
  139. return _ws_host_origin_is_allowed(ws) and _ws_client_is_allowed(ws)
  140. from hermes_cli.web_server_boundary import (
  141. _GATEWAY_WS_PROTOCOL,
  142. _GATEWAY_WS_TICKET_PROTOCOL_PREFIX,
  143. _gateway_ws_ticket_from_subprotocol,
  144. )
  145. def _ws_request_view(ws: WebSocket, app) -> Request:
  146. """A ``Request`` facade over a ``WebSocket`` for the auth helpers.
  147. ``_verify_access_token`` only touches ``request.headers`` (X-Forwarded-For
  148. via ``client_ip``) and ``request.client`` on this path (``audit=False``,
  149. no cookie/redirect work), and ``webapp_sign_in.token_works_alone`` reads
  150. ``request.app.state``, so a lightweight stand-in carrying *app* avoids
  151. constructing a real ASGI request inside the upgrade. ``scan_session_providers``
  152. itself never sees the request — only the provider callbacks do.
  153. ``webapp_sign_in.token_works_alone`` reads the listener's state from *app*.
  154. """
  155. from fastapi import Request
  156. return Request({
  157. "type": "http",
  158. "app": app,
  159. "headers": [(k.lower().encode("latin-1"), v.encode("latin-1"))
  160. for k, v in getattr(ws.headers, "items", dict)()],
  161. "client": (ws.client.host, 0) if ws.client else None,
  162. "server": None,
  163. "scheme": "ws",
  164. "method": "GET",
  165. "path": ws.url.path,
  166. "query_string": b"",
  167. "root_path": "",
  168. })
  169. def _ws_auth_reason(ws: WebSocket, *, allow_internal: bool = False,
  170. socket: Optional[str] = None) -> tuple[Optional[str], str]:
  171. """Validate WS-upgrade auth; return ``(reason, credential)``.
  172. ``reason`` is None when accepted, else a short token (``no_credential``,
  173. ``token_mismatch``, ``ticket_invalid``, ``internal_invalid``);
  174. ``credential`` names what was presented so the accept path can log *how*.
  175. *socket* names the route's socket for its own tickets (``web_session_sockets.GATEWAY_SOCKET``,
  176. ``HOST_TERMINAL_SOCKET`` or one of ``AUDIO_SOCKETS``): a ticket minted for
  177. one socket opens no other, and the host terminal opens only with its own ticket.
  178. Loopback / ``--insecure``: legacy ``?token=`` (constant-time compared); on the
  179. gateway's Webapp a one-use socket ticket first (``/api/webapp/socket-ticket``).
  180. Gated: ``?ticket=`` (browser-minted, single-use, 30s TTL) or ``?internal=``
  181. (process-lifetime, multi-use, only for server-spawned WS clients so the PTY
  182. child can reconnect; never injected into the SPA; on the gateway's Webapp it
  183. opens only the sockets that pass *allow_internal*), or ``?token=`` holding a
  184. user session access token (verified against the dashboard auth session
  185. providers — the same ``verify_session`` seam the native bearer REST leg
  186. uses — e.g. a token-mode Remote desktop connection; on the gateway's Webapp
  187. only a token that listener gave a native app's sign-in, as for the bearer
  188. header, ``webapp_sign_in.token_works_alone``). The legacy in-process
  189. ``_SESSION_TOKEN`` is rejected in gated mode: a leaked ``_SESSION_TOKEN``
  190. must not grant access.
  191. Either mode: a local Desktop (no static token) presents the private one-use
  192. ``X-Hermes-Gateway-Ticket`` grant its REST calls use (``authenticate_native_ws``).
  193. A socket that sends that header is judged by it alone: on a core socket
  194. (``/api/ws``, ``/api/pty``, the audio streams) the grant is refused
  195. (``native_invalid``) even when a valid ``token`` query credential rides along.
  196. That is intended; only the plugin WebSocket gate accepts the grant. The audio
  197. streams instead take the ``interactive`` grant of the Desktop's ``/api/ws`` dial,
  198. in its gateway subprotocol (``redeem_audio_ws``), stamped on ``_hermes_native_grant``.
  199. """
  200. from hermes_cli.dashboard_auth.native_http import HEADER, authenticate_native_ws, redeem_audio_ws
  201. from hermes_cli.web_server import _SESSION_TOKEN, app
  202. from hermes_cli.browser_credential import generation_of
  203. from hermes_cli.web_session_sockets import OWN_TICKET_SOCKETS, track
  204. auth_required = bool(getattr(app.state, "auth_required", False))
  205. # The Webapp's own rules (socket tickets on the loopback gate, the server's credential only where
  206. # its spawned clients dial) apply on its listener; the standalone dashboard and serve keep main's.
  207. webapp = getattr(app.state, "ui_surface", None) == "webapp"
  208. if socket in OWN_TICKET_SOCKETS:
  209. # No standing credential (the session token, a native grant, a login's access token) opens it.
  210. reject = functools.partial(_audit_ws_rejection, ws) if auth_required else _ignore_rejection
  211. return _consume_ws_ticket(ws, reject, socket, auth_required=auth_required) or ("no_credential", "none")
  212. if HEADER in ws.headers:
  213. grant = authenticate_native_ws(ws)
  214. if grant is None:
  215. return "native_invalid", "native"
  216. ws._hermes_auth_identity = {"user_id": grant["subject"], "provider": "local"}
  217. return None, "native"
  218. grant = redeem_audio_ws(ws)
  219. if grant is not None:
  220. ws._hermes_auth_identity = {"user_id": grant["subject"], "provider": "local"}
  221. ws._hermes_native_grant = grant
  222. ws._hermes_ws_subprotocol = _GATEWAY_WS_PROTOCOL
  223. return None, "native"
  224. if auth_required:
  225. # Lazy import — keeps this function importable in test harnesses
  226. # that don't bring in the dashboard_auth layer.
  227. from hermes_cli.dashboard_auth.audit import AuditEvent, audit_log
  228. from hermes_cli.dashboard_auth.ws_tickets import TicketInvalid, consume_internal_credential
  229. _reject = functools.partial(_audit_ws_rejection, ws)
  230. def _stamp_identity(info) -> None:
  231. # Server-minted {user_id, provider} stamped onto the WS object is the
  232. # sole identity authority downstream (gateway transport / controller
  233. # registration); a client can never supply it through RPC params.
  234. # Only identity fields are carried — bookkeeping such as
  235. # ``minted_at`` is not part of the identity contract.
  236. ws._hermes_auth_identity = {
  237. "user_id": info.get("user_id"), "provider": info.get("provider")}
  238. if info.get("issuer"):
  239. ws._hermes_auth_identity["issuer"] = info["issuer"]
  240. internal = ws.query_params.get("internal", "")
  241. if internal:
  242. if webapp and not allow_internal:
  243. _reject("internal: endpoint not allowed")
  244. return "internal_not_allowed", "internal"
  245. try:
  246. _stamp_identity(consume_internal_credential(internal))
  247. return None, "internal"
  248. except TicketInvalid as exc:
  249. _reject(f"internal: {exc}")
  250. return "internal_invalid", "internal"
  251. consumed = _consume_ws_ticket(ws, _reject, socket, auth_required=True)
  252. if consumed is not None:
  253. return consumed
  254. # A user session access token (``?token=``) is verified against the
  255. # dashboard auth session providers — the SAME ``verify_session`` seam
  256. # the native bearer REST leg uses (``_verify_access_token``). A
  257. # token-mode Remote desktop connection bakes its stored session token
  258. # into the WS URL (buildGatewayWsUrl), so before this leg existed the
  259. # only credentials gated mode accepted were browser-minted tickets and
  260. # the WS upgrade 403'd forever. The legacy in-process
  261. # ``_SESSION_TOKEN`` never reaches this check: gated mode falls
  262. # through to the explicit rejection below (leaked-constant safety),
  263. # and a provider-verified token is accepted on identity merit. On the
  264. # gateway's Webapp it follows the bearer header's rule: only a token this
  265. # listener gave a native app's sign-in works on its own, so a browser
  266. # login's tokens work only as its cookies, which sign-out ends.
  267. token = ws.query_params.get("token", "")
  268. if token:
  269. from hermes_cli import webapp_sign_in
  270. from hermes_cli.dashboard_auth.base import ProviderError
  271. from hermes_cli.dashboard_auth.middleware import _verify_access_token
  272. view = _ws_request_view(ws, app)
  273. try:
  274. # On the gateway's Webapp a browser login's tokens work only as its cookies, which
  275. # sign-out ends; only a token this listener gave a native app's sign-in works alone.
  276. session = (_verify_access_token(view, access_token=token, audit=False)
  277. if webapp_sign_in.token_works_alone(view, token) else None)
  278. except ProviderError as exc:
  279. # All providers unreachable (IDP outage) — reject without
  280. # crashing the upgrade; the REST bearer leg answers 503, and
  281. # the WS accept path has no status channel, only close codes.
  282. _reject(f"session token verify unavailable: {exc}")
  283. return "token_unavailable", "token"
  284. if session is not None:
  285. _stamp_identity({
  286. "user_id": getattr(session, "user_id", None),
  287. "provider": getattr(session, "provider", None),
  288. })
  289. audit_log(
  290. AuditEvent.TOKEN_AUTH_SUCCESS,
  291. provider=getattr(session, "provider", None),
  292. user_id=getattr(session, "user_id", None),
  293. ip=(ws.client.host if ws.client else ""),
  294. path=ws.url.path,
  295. )
  296. return None, "token"
  297. audit_log(
  298. AuditEvent.TOKEN_AUTH_FAILURE,
  299. reason="session_token_invalid",
  300. ip=(ws.client.host if ws.client else ""),
  301. path=ws.url.path,
  302. )
  303. return "token_invalid", "token"
  304. return "no_credential", "none"
  305. # Loopback: on the Webapp a one-use ticket ``/api/webapp/socket-ticket`` minted for the
  306. # session-token owner (its sockets on this same origin), else the legacy ``?token=``.
  307. consumed = _consume_ws_ticket(ws, _ignore_rejection, socket) if webapp else None
  308. if consumed is not None:
  309. return consumed
  310. token = ws.query_params.get("token", "")
  311. if not token:
  312. return "no_credential", "none"
  313. if hmac.compare_digest(token.encode(), _SESSION_TOKEN.encode()):
  314. track(ws, generation_of(token))
  315. return None, "token"
  316. return "token_mismatch", "token"
  317. def _ignore_rejection(reason: str) -> None:
  318. """The loopback gate keeps no audit record of a refused credential."""
  319. def _audit_ws_rejection(ws: WebSocket, reason: str) -> None:
  320. """The gated gate's audit record of a refused upgrade credential."""
  321. from hermes_cli.dashboard_auth.audit import AuditEvent, audit_log
  322. audit_log(AuditEvent.WS_TICKET_REJECTED, reason=reason, ip=(ws.client.host if ws.client else ""),
  323. path=ws.url.path)
  324. def _consume_ws_ticket(ws: WebSocket, reject, socket: Optional[str] = None, *,
  325. auth_required: bool = False) -> Optional[tuple[Optional[str], str]]:
  326. """A one-use ticket offered as the ``hermes-gateway-ticket.`` subprotocol or ``?ticket=``:
  327. ``(reason, credential)`` once judged, or None when the upgrade presents none. An accepted ticket
  328. stamps the server-minted identity onto the socket; the client never supplies it through RPC
  329. params. *socket* is the route's socket (``web_session_sockets.ticket_refusal``); a socket a
  330. session-token ticket, or a Webapp login's ticket, opens is tracked so signing out closes it."""
  331. from hermes_cli.dashboard_auth.ws_tickets import TicketInvalid, consume_ticket
  332. from hermes_cli.web_session_sockets import admitted_with, ticket_refusal, track
  333. protocol_ticket, protocol_reason = _gateway_ws_ticket_from_subprotocol(ws)
  334. if protocol_reason == "invalid":
  335. return "ticket_invalid", "ticket-subprotocol"
  336. ticket = protocol_ticket or ws.query_params.get("ticket", "")
  337. if not ticket:
  338. return None
  339. try:
  340. info = consume_ticket(ticket)
  341. except TicketInvalid as exc:
  342. reject(str(exc))
  343. return "ticket_invalid", "ticket"
  344. refusal = ticket_refusal(info, socket, auth_required=auth_required)
  345. if refusal is not None:
  346. reject(refusal)
  347. return "ticket_invalid", "ticket"
  348. if info.get("provider") == "bot-desktop":
  349. # A display ticket admits one RFB bridge on /api/display/ws (a watch-only capability handed
  350. # to a screen viewer); it must not double as a login here.
  351. reject("display ticket presented as a gateway login")
  352. return "ticket_invalid", "ticket"
  353. # Only identity fields are carried; bookkeeping such as ``minted_at`` is not part of it.
  354. ws._hermes_auth_identity = {"user_id": info.get("user_id"), "provider": info.get("provider")}
  355. if info.get("issuer"):
  356. ws._hermes_auth_identity["issuer"] = info["issuer"]
  357. if info.get("profile_home"):
  358. ws._hermes_ticket_profile_home = info["profile_home"]
  359. if (admitted := admitted_with(info)) is not None:
  360. track(ws, admitted)
  361. if not protocol_ticket:
  362. return None, "ticket"
  363. # Select only the stable public protocol during accept. The ticket-bearing protocol is a
  364. # credential and must never be reflected back to the browser or retained after admission.
  365. ws._hermes_ws_subprotocol = _GATEWAY_WS_PROTOCOL
  366. return None, "ticket-subprotocol"
  367. def _ws_auth_ok(ws: WebSocket, *, allow_internal: bool = False, socket: Optional[str] = None) -> bool:
  368. """True when the WS-upgrade credential is accepted. See _ws_auth_reason."""
  369. return _ws_auth_reason(ws, allow_internal=allow_internal, socket=socket)[0] is None
  370. def _ws_auth_mode() -> str:
  371. """Short label for the active WS auth mode — logged on every connection."""
  372. from hermes_cli.web_server import app
  373. if getattr(app.state, "auth_required", False):
  374. return "gated"
  375. bound_host = (getattr(app.state, "bound_host", "") or "").strip().lower()
  376. if bound_host and bound_host not in _LOOPBACK_HOSTS:
  377. return "insecure"
  378. return "loopback"
  379. def _ws_close_reason(text: str) -> str:
  380. """Clamp to RFC 6455's 123-byte close-reason limit (uvicorn raises past it);
  381. reasons embed an attacker-controlled origin, so truncate rather than crash."""
  382. encoded = text.encode("utf-8", "replace")
  383. if len(encoded) <= 123:
  384. return text
  385. return encoded[:120].decode("utf-8", "ignore") + "..."
  386. async def _ws_gate(ws: WebSocket, kind: str) -> Optional[tuple[str, str, str]]:
  387. """Run the pre-accept gates for /api/console, /api/pty and /api/host-terminal.
  388. Each gate maps to a distinct close code so the log and the browser banner
  389. agree on the cause: 4404 chat disabled, 4401 bad credential, 4403 host/origin
  390. mismatch, 4408 peer not allowed. Returns ``(peer, mode, cred)``
  391. once every gate passes, or None after closing the socket.
  392. """
  393. from hermes_cli.web_server import _DASHBOARD_EMBEDDED_CHAT_ENABLED
  394. peer = ws.client.host if ws.client else "?"
  395. if not _DASHBOARD_EMBEDDED_CHAT_ENABLED:
  396. _log.info("%s refused: embedded chat disabled peer=%s", kind, peer)
  397. await ws.close(code=4404, reason="embedded chat disabled")
  398. return None
  399. auth_reason, cred = _ws_auth_reason(ws, socket=kind)
  400. mode = _ws_auth_mode()
  401. if auth_reason is not None:
  402. _log.warning("%s auth rejected reason=%s mode=%s cred=%s peer=%s", kind, auth_reason, mode, cred, peer)
  403. await ws.close(code=4401, reason=_ws_close_reason(f"auth: {auth_reason}"))
  404. return None
  405. host_origin_reason = _ws_host_origin_reason(ws)
  406. if host_origin_reason is not None:
  407. _log.warning("%s refused: %s peer=%s", kind, host_origin_reason, peer)
  408. await ws.close(code=4403, reason=_ws_close_reason(host_origin_reason))
  409. return None
  410. client_reason = _ws_client_reason(ws)
  411. if client_reason is not None:
  412. _log.warning("%s refused: %s", kind, client_reason)
  413. await ws.close(code=4408, reason=_ws_close_reason(client_reason))
  414. return None
  415. return peer, mode, cred
  416. async def _pty_fail(ws: WebSocket, exc: BaseException, *, surface: str = "Chat") -> None:
  417. """Tell the user why chat could not start, then close 1011 so the SPA renders
  418. "Start new session". The raw exception goes to the server log only."""
  419. from hermes_cli.web_routers.chat_ws_errors import chat_start_failure_message
  420. _log.warning("pty start failed: %s: %s", type(exc).__name__, exc)
  421. await ws.send_text(f"\r\n\x1b[31m{chat_start_failure_message(exc, surface=surface)}\x1b[0m\r\n")
  422. await ws.close(code=1011)
  423. def _resolve_chat_argv(
  424. resume: Optional[str] = None, sidecar_url: Optional[str] = None, profile: Optional[str] = None,
  425. active_session_file: Optional[str] = None,
  426. workspace_cwd: Optional[str] = None) -> tuple[list[str], Optional[str], Optional[dict]]:
  427. """Resolve the argv + cwd + env for the chat PTY (what ``hermes --tui`` runs).
  428. Tests monkeypatch this with a tiny fake command. Env contract: resume goes
  429. through ``HERMES_TUI_RESUME`` (``ui-tui`` does not parse argv), resolved to
  430. the newest descendant; ``HERMES_TUI_GATEWAY_URL`` attaches to this process's
  431. in-memory gateway but is SKIPPED for profile-scoped chats (that gateway runs
  432. under the dashboard's own profile, so a scoped chat attaches to its profile's gateway);
  433. ``profile`` scopes the ENTIRE chat by pointing ``HERMES_HOME`` at the profile
  434. dir, the same propagation ``hermes -p <name>`` performs. ``workspace_cwd``
  435. (an already-validated host directory, ``chat_workspaces.resolve_chat_cwd``)
  436. is the workspace the user picked for a FRESH chat: it becomes ``HERMES_CWD``
  437. (where a self-spawned gateway starts) and ``HERMES_TUI_CWD`` (what the TUI
  438. passes as the explicit ``cwd`` of ``session.create`` when attached to the
  439. in-memory gateway, whose own cwd is the dashboard's launch dir).
  440. """
  441. from hermes_cli.web_server_profiles import _config_profile_scope, _resolve_profile_dir
  442. from hermes_cli.web_server_sessions import _open_session_db_for_profile, _session_latest_descendant
  443. from hermes_cli.main import PROJECT_ROOT
  444. from hermes_cli.main_tui_launch import _apply_tui_python_env, _make_tui_argv
  445. profile_dir: Optional[Path] = None
  446. requested = (profile or "").strip()
  447. if requested and requested.lower() != "current":
  448. profile_dir = _resolve_profile_dir(requested)
  449. argv, cwd = _make_tui_argv(PROJECT_ROOT / "ui-tui", tui_dev=False)
  450. # Secrets kept — the spawned agent needs provider creds. An explicit profile
  451. # scope overrides HERMES_HOME before config is bridged into the env.
  452. from tools.environments.local import build_subprocess_env
  453. env = build_subprocess_env(scrub_secrets=False, inherit_profile_home=True)
  454. if profile_dir is not None:
  455. env["HERMES_HOME"] = str(profile_dir)
  456. try:
  457. from hermes_cli.config import (
  458. apply_terminal_config_to_env, read_raw_config, terminal_config_owned_env_vars)
  459. if profile_dir is not None:
  460. # Drop only the terminal keys the launch profile owns before applying
  461. # the selected profile; operator exports for other keys stay valid.
  462. raw_launch_terminal = read_raw_config().get("terminal")
  463. for env_var in terminal_config_owned_env_vars(raw_launch_terminal):
  464. env.pop(env_var, None)
  465. with _config_profile_scope(requested):
  466. apply_terminal_config_to_env(env=env)
  467. else:
  468. apply_terminal_config_to_env(env=env)
  469. except Exception:
  470. _log.warning("Failed to apply terminal config bridge for dashboard chat", exc_info=True)
  471. if workspace_cwd:
  472. env["HERMES_CWD"] = workspace_cwd
  473. env["HERMES_TUI_CWD"] = workspace_cwd
  474. _apply_tui_python_env(env)
  475. env.setdefault("NODE_ENV", "production")
  476. # Mouse tracking would swallow wheel events the browser needs for
  477. # transcript scrolling; disable it for the dashboard PTY only.
  478. env.setdefault("HERMES_TUI_DISABLE_MOUSE", "1")
  479. env.setdefault("HERMES_TUI_INLINE", "1")
  480. # chalk in the child picks its color depth from the SERVER env; hosted
  481. # deploys have no COLORTERM, so hex colors would snap to the 256 palette.
  482. env.setdefault("COLORTERM", "truecolor")
  483. env["HERMES_TUI_DASHBOARD"] = "1"
  484. if resume:
  485. _resume_db = _open_session_db_for_profile(
  486. requested if profile_dir is not None else None, read_only=True)
  487. try:
  488. latest_resume, _latest_path = _session_latest_descendant(resume, _resume_db)
  489. finally:
  490. _resume_db.close()
  491. if latest_resume:
  492. resume = latest_resume
  493. env["HERMES_TUI_RESUME"] = resume
  494. if sidecar_url:
  495. env["HERMES_TUI_SIDECAR_URL"] = sidecar_url
  496. if active_session_file:
  497. env["HERMES_TUI_ACTIVE_SESSION_FILE"] = active_session_file
  498. # Without the attach URL, gatewayClient bootstraps through the profile's own
  499. # gateway (ui-tui/scripts/gateway_bootstrap.py) under the HERMES_HOME set above;
  500. # it never spawns a standalone `tui_gateway.entry` writer.
  501. if profile_dir is None and (gateway_ws_url := _build_gateway_ws_url()):
  502. env["HERMES_TUI_GATEWAY_URL"] = gateway_ws_url
  503. return list(argv), str(cwd) if cwd else None, env
  504. # Wildcard bind hosts an in-container client must NOT dial: behind a forward
  505. # proxy (HTTPS_PROXY without 0.0.0.0 in NO_PROXY) the handshake gets MITM'd.
  506. _WILDCARD_HOSTS = frozenset({"0.0.0.0", "::"})
  507. def _resolve_client_ws_host() -> Optional[str]:
  508. """Host the in-container WS client should dial: ``HERMES_DASHBOARD_WS_HOST``
  509. wins always; a wildcard bind becomes ``127.0.0.1``; others verbatim."""
  510. from hermes_cli.web_server import app
  511. explicit = os.environ.get("HERMES_DASHBOARD_WS_HOST", "").strip()
  512. if explicit:
  513. return explicit
  514. host = getattr(app.state, "bound_host", None)
  515. if not host:
  516. return None
  517. return "127.0.0.1" if host in _WILDCARD_HOSTS else host
  518. def _server_internal_ws_url(path: str, **extra_qs) -> Optional[str]:
  519. """``ws://<host>:<port><path>?<auth>&<extra>`` for server-spawned WS clients,
  520. or None when unbound.
  521. Gated mode uses the process-lifetime internal credential, NOT a single-use
  522. browser ticket: the child reads the URL once and reuses it on every
  523. reconnect, and a 30s-TTL ticket can expire before a slow cold boot dials.
  524. """
  525. from hermes_cli.web_server import _SESSION_TOKEN, app
  526. host = _resolve_client_ws_host()
  527. port = getattr(app.state, "bound_port", None)
  528. if not host or not port:
  529. return None
  530. netloc = f"[{host}]:{port}" if ":" in host and not host.startswith("[") else f"{host}:{port}"
  531. if getattr(app.state, "auth_required", False):
  532. from hermes_cli.dashboard_auth.ws_tickets import internal_ws_credential
  533. auth = {"internal": internal_ws_credential()}
  534. else:
  535. auth = {"token": _SESSION_TOKEN}
  536. return f"ws://{netloc}{path}?{urllib.parse.urlencode({**auth, **extra_qs})}"
  537. def _build_gateway_ws_url() -> Optional[str]:
  538. """ws:// URL the PTY child attaches to for JSON-RPC gateway traffic."""
  539. return _server_internal_ws_url("/api/ws")
  540. def _build_sidecar_url(channel: str) -> Optional[str]:
  541. """ws:// URL the PTY child publishes events to, or None when unbound."""
  542. return _server_internal_ws_url("/api/pub", channel=channel)
  543. async def _resolve_chat_argv_async(
  544. resume: Optional[str] = None, sidecar_url: Optional[str] = None, profile: Optional[str] = None,
  545. active_session_file: Optional[str] = None,
  546. workspace_cwd: Optional[str] = None) -> tuple[list[str], Optional[str], Optional[dict]]:
  547. """Resolve chat argv off the event loop (it may run ``npm run build``); the
  548. async lock keeps one-build-at-a-time without parking worker threads."""
  549. from hermes_cli.web_server import _get_chat_argv_lock, app
  550. kwargs = {"resume": resume, "sidecar_url": sidecar_url, "profile": profile}
  551. if active_session_file is not None:
  552. kwargs["active_session_file"] = active_session_file
  553. if workspace_cwd is not None:
  554. kwargs["workspace_cwd"] = workspace_cwd
  555. async with _get_chat_argv_lock(app):
  556. return await asyncio.to_thread(_resolve_chat_argv, **kwargs)
  557. def _active_session_file_for_channel(app: FastAPI, channel: str) -> Path:
  558. """Return the per-channel file where a dashboard TUI writes its active sid."""
  559. from hermes_cli.web_server import _get_pty_active_session_files
  560. files = _get_pty_active_session_files(app)
  561. if files.get(channel) is None:
  562. fd, raw_path = tempfile.mkstemp(prefix="hermes-pty-active-", suffix=".json")
  563. os.close(fd)
  564. files[channel] = Path(raw_path)
  565. return files[channel]
  566. # On timeout asyncio cancels the awaitable but the console thread keeps running;
  567. # a small dedicated pool caps the leak instead of exhausting the default pool.
  568. _CONSOLE_EXECUTOR_MAX_WORKERS = 4
  569. _console_executor: Optional[concurrent.futures.ThreadPoolExecutor] = None
  570. _console_executor_lock = threading.Lock()
  571. def _get_console_executor() -> concurrent.futures.ThreadPoolExecutor:
  572. """Lazily create the bounded console worker pool (once per process)."""
  573. global _console_executor
  574. if _console_executor is None:
  575. with _console_executor_lock:
  576. if _console_executor is None:
  577. _console_executor = concurrent.futures.ThreadPoolExecutor(
  578. max_workers=_CONSOLE_EXECUTOR_MAX_WORKERS, thread_name_prefix="hermes-console")
  579. # Tear down on interpreter exit without waiting on in-flight
  580. # workers: a stuck 60s console command must not block shutdown.
  581. atexit.register(
  582. lambda: _console_executor
  583. and _console_executor.shutdown(wait=False, cancel_futures=True))
  584. return _console_executor