chat_ws.py 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760
  1. """Chat-tab WebSocket routes: /api/console, /api/pty, the /api/ws gateway
  2. sidecar and /api/pub + /api/events broadcast.
  3. Helpers/state that tests monkeypatch on ``web_server`` stay there and are
  4. reached through the late-binding seam (cycle-safe).
  5. """
  6. import asyncio
  7. import contextlib
  8. import json
  9. import logging
  10. import re
  11. from pathlib import Path
  12. from typing import Any, Dict, Optional
  13. from fastapi import APIRouter, FastAPI, HTTPException, WebSocket, WebSocketDisconnect
  14. from agent.interrupt_scope import InterruptScope, bind_interrupt_scope
  15. from hermes_cli.active_sessions import ActiveSessionRegistryError, active_session_registry_snapshot
  16. from hermes_cli.pty_session import RegistryFull
  17. from hermes_cli.web_deps import LateState, late
  18. from hermes_cli.web_server_chat import (
  19. _build_sidecar_url, _close_stalled_pty_input, _get_console_executor, _legacy_pump, _pty_fail, _ws_auth_ok,
  20. _ws_close_reason, _ws_gate, _ws_request_is_allowed,
  21. )
  22. from hermes_cli.web_session_sockets import GATEWAY_SOCKET
  23. _log = logging.getLogger("hermes_cli.web_server")
  24. router = APIRouter()
  25. # Late-bound so a test's monkeypatch on the owning module wins at call time.
  26. _active_session_file_for_channel = late("_active_session_file_for_channel", "hermes_cli.web_server_chat")
  27. _profile_scope = late("_profile_scope", "hermes_cli.web_server_profiles")
  28. _resolve_chat_argv_async = late("_resolve_chat_argv_async", "hermes_cli.web_server_chat")
  29. _resolve_profile_dir = late("_resolve_profile_dir", "hermes_cli.web_server_profiles")
  30. _DASHBOARD_EMBEDDED_CHAT_ENABLED = LateState("_DASHBOARD_EMBEDDED_CHAT_ENABLED")
  31. def _get_event_state(app: FastAPI):
  32. """(event_channels, event_lock) from app.state, lazily initialised when the
  33. lifespan hasn't run (TestClient without a ``with`` block). The lifespan path
  34. is preferred because it creates the Lock on the correct event loop."""
  35. try:
  36. return app.state.event_channels, app.state.event_lock
  37. except AttributeError:
  38. app.state.event_channels = {}
  39. app.state.event_lock = asyncio.Lock()
  40. return app.state.event_channels, app.state.event_lock
  41. _VALID_CHANNEL_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
  42. def _unlink_active_session_file(path: Optional[Path]) -> None:
  43. if path is None:
  44. return
  45. try:
  46. path.unlink(missing_ok=True)
  47. except OSError:
  48. pass
  49. def _discard_active_session_file(app: FastAPI, channel: Optional[str], path: Optional[Path]) -> None:
  50. _unlink_active_session_file(path)
  51. if not channel or path is None:
  52. return
  53. try:
  54. from hermes_cli.web_server import _get_pty_active_session_files
  55. files = _get_pty_active_session_files(app)
  56. if files.get(channel) == path:
  57. files.pop(channel, None)
  58. except Exception: # health: allow BLE001 S110 -- marker cleanup must never mask the PTY teardown path it runs inside
  59. pass
  60. async def _broadcast_event(app: Any, channel: str, payload: str) -> None:
  61. """Fan out one publisher frame to every subscriber on `channel`."""
  62. event_channels, event_lock = _get_event_state(app)
  63. async with event_lock:
  64. subs = list(event_channels.get(channel, ()))
  65. for sub in subs:
  66. try:
  67. await sub.send_text(payload)
  68. except Exception:
  69. # Subscriber went away mid-send; /api/events' finally removes it.
  70. _log.warning("broadcast send failed for subscriber on %s", channel, exc_info=True)
  71. def _channel_or_close_code(ws: WebSocket) -> Optional[str]:
  72. """Channel id from the query string, or None if invalid."""
  73. channel = ws.query_params.get("channel", "")
  74. return channel if _VALID_CHANNEL_RE.match(channel) else None
  75. def _read_active_session_file(path: Path) -> Optional[str]:
  76. try:
  77. data = json.loads(path.read_text(encoding="utf-8-sig"))
  78. except (OSError, json.JSONDecodeError):
  79. return None
  80. return str(data.get("session_id") or "").strip() or None
  81. async def _close_unless_sidecar_allowed(ws: WebSocket, *, allow_internal: bool = False,
  82. socket: Optional[str] = None) -> bool:
  83. """Pre-accept gates for the /api/ws, /api/pub and /api/events sidecars:
  84. 4403 when chat is disabled or the request isn't allowed, 4401 on bad auth."""
  85. if not _DASHBOARD_EMBEDDED_CHAT_ENABLED:
  86. await ws.close(code=4403)
  87. return False
  88. if not _ws_auth_ok(ws, allow_internal=allow_internal, socket=socket):
  89. await ws.close(code=4401)
  90. return False
  91. if not _ws_request_is_allowed(ws):
  92. await ws.close(code=4403)
  93. return False
  94. return True
  95. # --- /api/console: the curated console engine, in-process, exchanging JSON
  96. # frames with the dashboard xterm overlay. Never spawns a PTY, shell or CLI.
  97. _CONSOLE_PROMPT = "hermes> "
  98. _CONSOLE_COMMAND_TIMEOUT_SECONDS = 60.0
  99. # Cancel/timeout interrupt the worker cooperatively; this bounds how long the prompt waits for it to exit.
  100. _CONSOLE_UNWIND_TIMEOUT_SECONDS = 10.0
  101. _CONSOLE_OUTPUT_LIMIT = 50000
  102. def _execute_console_line(
  103. engine: Any, line: str, *, confirmed: bool, profile: Optional[str], scope: Optional[InterruptScope] = None,
  104. ) -> Any:
  105. # _profile_scope swaps process-global skill module paths; keep it inside
  106. # the worker thread and never hold it across awaits.
  107. with _profile_scope(profile), bind_interrupt_scope(scope):
  108. return engine.execute(line, confirmed=confirmed)
  109. async def _unwind_console_worker(worker: Any, scope: InterruptScope, reason: str) -> None:
  110. """Stop the command's worker after cancel/timeout: asyncio can only drop the waiter, so interrupt
  111. any agent the command forked (closing its provider request) and wait for the thread to exit.
  112. A user cancel is attributed to the user; only the timeout is a host-issued stop (#112647)."""
  113. if reason == "cancelled":
  114. scope.cancel(f"Console command {reason}", tool_reason=None)
  115. else:
  116. scope.cancel(f"Console command {reason}")
  117. if worker.cancel(): # still queued: never ran
  118. return
  119. exited = asyncio.wrap_future(worker)
  120. done, _ = await asyncio.wait({exited}, timeout=_CONSOLE_UNWIND_TIMEOUT_SECONDS)
  121. if not done:
  122. exited.cancel()
  123. _log.warning("console worker still running %ss after %s", _CONSOLE_UNWIND_TIMEOUT_SECONDS, reason)
  124. async def _wait_for_console_worker(worker: Any) -> Any:
  125. return await asyncio.wait_for(
  126. asyncio.wrap_future(worker), timeout=_CONSOLE_COMMAND_TIMEOUT_SECONDS,
  127. )
  128. class _ConsoleSender:
  129. """Serialises frames onto one console socket and owns the prompt suffix."""
  130. def __init__(self, ws: WebSocket) -> None:
  131. self.ws = ws
  132. self.lock = asyncio.Lock()
  133. async def send(self, payload: dict[str, Any]) -> None:
  134. async with self.lock:
  135. await self.ws.send_json(payload)
  136. async def prompt(self, **payload: Any) -> None:
  137. await self.send({**payload, "prompt": _CONSOLE_PROMPT})
  138. async def error(self, message: str, *, id: Optional[int] = None, command: Optional[str] = None,
  139. prompt: Optional[str] = None) -> None:
  140. # Key order matches the historical frames: type, id, message, command, prompt.
  141. frame: dict[str, Any] = {"type": "error"}
  142. if id is not None:
  143. frame["id"] = id
  144. frame["message"] = message
  145. if command is not None:
  146. frame["command"] = command
  147. if prompt is not None:
  148. frame["prompt"] = prompt
  149. await self.send(frame)
  150. async def complete(self, status: str, command: str, command_id: int, *, prompt: str = _CONSOLE_PROMPT) -> None:
  151. await self.send({"type": "complete", "id": command_id, "status": status, "command": command, "prompt": prompt})
  152. async def error_then_complete(self, message: str, command: str, command_id: int, status: str) -> None:
  153. await self.error(message, id=command_id, command=command)
  154. await self.complete(status, command, command_id)
  155. async def send_result(self, result: Any, *, command_id: int) -> None:
  156. command = result.command or ""
  157. status = result.status
  158. if status == "ok":
  159. if result.output:
  160. await self.send({
  161. "type": "output", "id": command_id, "stream": "stdout",
  162. "data": result.output, "command": command,
  163. })
  164. await self.complete("ok", command, command_id)
  165. elif status == "error":
  166. await self.error_then_complete(result.output or "Command failed.", command, command_id, "error")
  167. elif status == "confirm_required":
  168. await self.prompt(
  169. type="confirm_required", id=command_id, command=command,
  170. message=result.confirmation_message or f"Run `{command}`?",
  171. )
  172. await self.complete("confirm_required", command, command_id)
  173. elif status == "clear":
  174. await self.send({"type": "clear", "id": command_id})
  175. await self.complete("clear", command, command_id)
  176. elif status == "exit":
  177. await self.complete("exit", command, command_id, prompt="")
  178. else:
  179. await self.error(f"Unknown console result status: {status}", id=command_id, command=command)
  180. def _console_json_payload(msg: Any) -> tuple[Optional[dict[str, Any]], Optional[str]]:
  181. raw: str | bytes | None = msg.get("text")
  182. if raw is None:
  183. raw = msg.get("bytes")
  184. if raw is None:
  185. return None, None
  186. if isinstance(raw, bytes):
  187. try:
  188. raw = raw.decode("utf-8")
  189. except UnicodeDecodeError:
  190. return None, "Console frames must be UTF-8 JSON."
  191. try:
  192. payload = json.loads(raw)
  193. except json.JSONDecodeError:
  194. return None, "Console frames must be JSON objects."
  195. if not isinstance(payload, dict):
  196. return None, "Console frames must be JSON objects."
  197. return payload, None
  198. @router.websocket("/api/console")
  199. async def console_ws(ws: WebSocket) -> None:
  200. gate = await _ws_gate(ws, "console")
  201. if gate is None:
  202. return
  203. peer, mode, cred = gate
  204. await ws.accept()
  205. profile = (ws.query_params.get("profile") or "").strip() or None
  206. out = _ConsoleSender(ws)
  207. try:
  208. from hermes_cli.console_engine import HermesConsoleEngine
  209. engine = HermesConsoleEngine(output_limit=_CONSOLE_OUTPUT_LIMIT)
  210. if profile and profile.lower() != "current":
  211. _resolve_profile_dir(profile)
  212. except HTTPException as exc:
  213. await out.error(str(exc.detail), prompt="")
  214. await ws.close(code=4400, reason=_ws_close_reason(str(exc.detail)))
  215. return
  216. except Exception as exc:
  217. _log.exception("console failed to initialize")
  218. await out.error(f"Console unavailable: {exc}", prompt="")
  219. await ws.close(code=1011)
  220. return
  221. _log.info("console accepted peer=%s mode=%s cred=%s profile=%s", peer, mode, cred, profile or "current")
  222. await out.prompt(type="ready", profile=profile or "current")
  223. active_task: asyncio.Task | None = None
  224. pending_confirmation: Optional[str] = None
  225. command_generation = 0
  226. async def run_command(line: str, *, confirmed: bool, command_id: int) -> None:
  227. nonlocal active_task, pending_confirmation, command_generation
  228. scope = InterruptScope()
  229. worker = _get_console_executor().submit(
  230. _execute_console_line, engine, line, confirmed=confirmed, profile=profile, scope=scope,
  231. )
  232. try:
  233. result = await _wait_for_console_worker(worker)
  234. except asyncio.CancelledError:
  235. await _unwind_console_worker(worker, scope, "cancelled")
  236. raise
  237. except TimeoutError:
  238. await _unwind_console_worker(worker, scope, "timed out")
  239. if command_id == command_generation:
  240. pending_confirmation = None
  241. await out.error_then_complete(
  242. "Command timed out. Hermes Console returned to the prompt.", line, command_id, "timeout",
  243. )
  244. except Exception as exc:
  245. if command_id == command_generation:
  246. pending_confirmation = None
  247. _log.exception("console command failed")
  248. await out.error_then_complete(str(exc) or exc.__class__.__name__, line, command_id, "error")
  249. else:
  250. if command_id != command_generation:
  251. return
  252. pending_confirmation = result.command if result.status == "confirm_required" else None
  253. await out.send_result(result, command_id=command_id)
  254. if result.status == "exit":
  255. await ws.close(code=1000)
  256. finally:
  257. if command_id == command_generation:
  258. active_task = None
  259. def start_command(line: str, *, confirmed: bool = False) -> None:
  260. nonlocal active_task, command_generation
  261. command_generation += 1
  262. active_task = asyncio.create_task(run_command(line, confirmed=confirmed, command_id=command_generation))
  263. try:
  264. while True:
  265. try:
  266. msg = await ws.receive()
  267. except RuntimeError:
  268. break
  269. if msg.get("type") == "websocket.disconnect":
  270. break
  271. payload, error = _console_json_payload(msg)
  272. if error:
  273. await out.prompt(type="error", message=error)
  274. continue
  275. if payload is None:
  276. continue
  277. frame_type = str(payload.get("type") or "").strip().lower()
  278. if frame_type == "ping":
  279. await out.prompt(type="pong")
  280. continue
  281. if frame_type == "cancel":
  282. if active_task and not active_task.done():
  283. command_generation += 1
  284. task, active_task = active_task, None
  285. task.cancel()
  286. # Report cancelled only once the worker (and any provider request it owns) is gone.
  287. with contextlib.suppress(asyncio.CancelledError):
  288. await task
  289. pending_confirmation = None
  290. await out.prompt(type="complete", status="cancelled")
  291. elif pending_confirmation:
  292. pending_confirmation = None
  293. await out.prompt(type="complete", status="cancelled")
  294. else:
  295. await out.prompt(type="complete", status="idle")
  296. continue
  297. if active_task and not active_task.done():
  298. await out.prompt(type="error", message="A console command is already running.")
  299. continue
  300. if frame_type == "confirm":
  301. command = str(payload.get("command") or pending_confirmation or "").strip()
  302. if not pending_confirmation:
  303. await out.prompt(type="error", message="No command is waiting for confirmation.")
  304. continue
  305. if command != pending_confirmation:
  306. await out.prompt(type="error", message="Confirmation does not match the pending command.")
  307. continue
  308. pending_confirmation = None
  309. start_command(command, confirmed=True)
  310. continue
  311. if frame_type in {"input", "command"}:
  312. line = str(payload.get("line") or payload.get("command") or "").strip()
  313. if not line:
  314. await out.prompt(type="complete", status="ok")
  315. continue
  316. if pending_confirmation:
  317. await out.prompt(
  318. type="error",
  319. message="Confirm or cancel the pending command before running another one.",
  320. )
  321. continue
  322. start_command(line)
  323. continue
  324. await out.prompt(type="error", message=f"Unsupported console frame: {frame_type or '?'}")
  325. except WebSocketDisconnect:
  326. pass
  327. finally:
  328. if active_task and not active_task.done():
  329. active_task.cancel()
  330. try:
  331. await active_task
  332. except (asyncio.CancelledError, Exception):
  333. pass
  334. def _lease_holder_pid(session_id: Optional[str], *, registry_home: Optional[str] = None) -> Optional[int]:
  335. """The live process holding ``session_id``'s single-writer lease, if any.
  336. A keep-alive PTY whose chat was never resumed from carries no resume target
  337. in its registry key, so the lease holder is what identifies the terminal
  338. that has to give the session back. Leases live under the HOME the chat runs
  339. in — a profile-scoped chat's child claims its lease in the profile's home,
  340. not the dashboard's launch home — so ``registry_home`` is the child's. A
  341. registry that cannot be read is not a reason to refuse the attach: the
  342. caller simply finds no holder.
  343. """
  344. if not session_id:
  345. return None
  346. try:
  347. for entry in active_session_registry_snapshot(registry_home=registry_home):
  348. if entry.get("session_id") == session_id and isinstance(entry.get("pid"), int):
  349. return entry["pid"]
  350. except (ActiveSessionRegistryError, OSError, ValueError):
  351. return None
  352. return None
  353. async def _pump_keepalive_input(ws: WebSocket, session: Any) -> None:
  354. """Writer loop for a keep-alive /api/pty socket: forward client input to the
  355. session's bridge, consuming resize escapes locally. On child EOF the drain
  356. task closes the attached socket with 4410, which unparks ws.receive()."""
  357. from hermes_cli.web_server_chat import _RESIZE_RE
  358. while True:
  359. try:
  360. msg = await ws.receive()
  361. except RuntimeError: # receive() after the drain task already closed us
  362. break
  363. if msg.get("type") == "websocket.disconnect":
  364. break
  365. raw = msg.get("bytes")
  366. if raw is None:
  367. text = msg.get("text")
  368. raw = text.encode("utf-8") if isinstance(text, str) else b""
  369. if not raw:
  370. continue
  371. # Resize escape is consumed locally, never written to the PTY.
  372. match = _RESIZE_RE.match(raw)
  373. if match and match.end() == len(raw):
  374. session.resize(ws, cols=int(match.group(1)), rows=int(match.group(2)))
  375. continue
  376. if not await session.write(ws, raw):
  377. # Only a stalled or exited child marks the session dead; a takeover just cancelled
  378. # this write, and the new viewer closes this socket as superseded.
  379. if not session.alive:
  380. await _close_stalled_pty_input(ws, path="keepalive")
  381. break
  382. async def _pty_channel_marker_state(
  383. ws: WebSocket, resume: Optional[str], force_fresh: bool,
  384. ) -> tuple[Optional[Path], bool, Optional[str]]:
  385. """(active_session_file, marker_preexisting, resume) for the /api/pty handler.
  386. A channel's marker may already belong to a live keep-alive PTY on that
  387. channel — only a marker this handler allocates is its own to drop on
  388. failure (#63553)."""
  389. channel = _channel_or_close_code(ws)
  390. if not channel:
  391. return None, False, resume
  392. from hermes_cli.web_server import _get_pty_active_session_files
  393. marker_files = _get_pty_active_session_files(ws.app)
  394. marker_preexisting = channel in marker_files
  395. active_session_file = _active_session_file_for_channel(ws.app, channel)
  396. if force_fresh:
  397. resume = None
  398. try:
  399. active_session_file.unlink(missing_ok=True)
  400. except OSError:
  401. pass
  402. marker_preexisting = False
  403. elif not resume:
  404. resume = _read_active_session_file(active_session_file)
  405. return active_session_file, marker_preexisting, resume
  406. @router.websocket("/api/pty")
  407. async def pty_ws(ws: WebSocket) -> None:
  408. from hermes_cli.web_server_chat import PTY_REGISTRY, PtyBridge, PtyUnavailableError, _PTY_BRIDGE_AVAILABLE, _RESIZE_RE
  409. from pm.package import InstallError
  410. gate = await _ws_gate(ws, "pty")
  411. if gate is None:
  412. return
  413. peer, mode, cred = gate
  414. await ws.accept()
  415. _log.info("pty accepted peer=%s mode=%s cred=%s", peer, mode, cred)
  416. # Native Windows can't import the POSIX PTY bridge: say so and close cleanly.
  417. if not _PTY_BRIDGE_AVAILABLE:
  418. await ws.send_text(
  419. "\r\n\x1b[31mChat unavailable: the embedded terminal requires a "
  420. "POSIX PTY, which native Windows Python doesn't provide.\x1b[0m\r\n"
  421. "\x1b[33mInstall Hermes inside WSL2 to use the dashboard's /chat "
  422. "tab — the rest of the dashboard works here.\x1b[0m\r\n"
  423. )
  424. await ws.close(code=1011)
  425. return
  426. raw_resume = ws.query_params.get("resume") or None
  427. resume = raw_resume
  428. profile = ws.query_params.get("profile") or None
  429. channel = _channel_or_close_code(ws)
  430. sidecar_url = _build_sidecar_url(channel) if channel else None
  431. force_fresh = (ws.query_params.get("fresh") or "").strip().lower() in {"1", "true", "yes", "on"}
  432. active_session_file, marker_preexisting, resume = await _pty_channel_marker_state(ws, resume, force_fresh)
  433. if channel and not force_fresh and resume and resume != raw_resume:
  434. # The client only pins the viewport to the bottom when it asked
  435. # for `?resume=`; announce the implicit active-session replay so
  436. # it gets the same follow-scroll treatment.
  437. # See #93518.
  438. await ws.send_json({"type": "resume", "id": resume})
  439. resolve_kwargs = {"resume": resume, "sidecar_url": sidecar_url, "profile": profile}
  440. if active_session_file is not None:
  441. resolve_kwargs["active_session_file"] = str(active_session_file)
  442. # A picked workspace only applies to a FRESH chat; a resumed session keeps its own cwd.
  443. if not resume:
  444. from hermes_cli.web_routers.chat_workspaces import resolve_chat_cwd
  445. try:
  446. workspace_cwd = resolve_chat_cwd(ws.query_params.get("cwd"))
  447. except HTTPException as exc: # dead/relative path: fail closed, never the launch dir
  448. await _pty_fail(ws, exc)
  449. return
  450. if workspace_cwd:
  451. resolve_kwargs["workspace_cwd"] = workspace_cwd
  452. try:
  453. argv, cwd, env = await _resolve_chat_argv_async(**resolve_kwargs)
  454. except HTTPException as exc: # unknown/invalid profile
  455. if not marker_preexisting:
  456. _discard_active_session_file(ws.app, channel, active_session_file)
  457. await _pty_fail(ws, exc)
  458. return
  459. except SystemExit as exc: # _make_tui_argv sys.exit(1)s when node/npm is missing
  460. if not marker_preexisting:
  461. _discard_active_session_file(ws.app, channel, active_session_file)
  462. await _pty_fail(ws, exc)
  463. return
  464. except InstallError as exc: # PM could not provide node; its remedy names the fix
  465. await _pty_fail(ws, exc)
  466. return
  467. raw_attach_token = ws.query_params.get("attach") or None
  468. attach_token = raw_attach_token
  469. registry_resume = raw_resume
  470. if raw_resume and env:
  471. registry_resume = env.get("HERMES_TUI_RESUME") or raw_resume
  472. if attach_token is not None and (registry_resume or profile):
  473. # Key explicit resumes on their canonical target, never the active-session fallback.
  474. attach_token = f"{attach_token}\0{profile or ''}\0{registry_resume or ''}"
  475. def _spawn():
  476. return PtyBridge.spawn(argv, cwd=cwd, env=env)
  477. if attach_token is None:
  478. # Legacy path: 1:1 socket<->PTY, killed on disconnect.
  479. try:
  480. bridge = _spawn()
  481. except PtyUnavailableError as exc:
  482. await _pty_fail(ws, exc)
  483. return
  484. except (FileNotFoundError, OSError) as exc:
  485. if not marker_preexisting:
  486. _discard_active_session_file(ws.app, channel, active_session_file)
  487. await _pty_fail(ws, exc)
  488. return
  489. try:
  490. await _legacy_pump(ws, bridge)
  491. finally:
  492. # The 1:1 PTY died with this socket; nothing survives to keep the
  493. # breadcrumb, so drop the marker instead of leaking the entry (#63553).
  494. # A preexisting marker belongs to a live keep-alive PTY on this channel
  495. # — only the marker this handler allocated is ours to drop. In a
  496. # ``finally``: the server may cancel the handler while the pump is still
  497. # awaiting the blocking ``bridge.close`` after the disconnect, and that
  498. # cancellation must not skip the cleanup.
  499. if not marker_preexisting:
  500. _discard_active_session_file(ws.app, channel, active_session_file)
  501. return
  502. # Keep-alive path: the PTY outlives this socket; reattach by token.
  503. try:
  504. await PTY_REGISTRY.close_other_sessions(raw_attach_token, keep_key=attach_token)
  505. holder_pid = _lease_holder_pid(registry_resume, registry_home=(env or {}).get("HERMES_HOME"))
  506. await PTY_REGISTRY.close_orphaned_sessions(registry_resume, keep_key=attach_token, holder_pid=holder_pid)
  507. session, _created = await PTY_REGISTRY.attach_or_spawn(
  508. attach_token,
  509. spawn=_spawn,
  510. active_session_file=active_session_file,
  511. )
  512. except (PtyUnavailableError, FileNotFoundError, OSError, RegistryFull) as exc:
  513. if not marker_preexisting:
  514. _discard_active_session_file(ws.app, channel, active_session_file)
  515. await _pty_fail(ws, exc)
  516. return
  517. if _created:
  518. # This PTY now owns this marker for its entire keep-alive lifetime.
  519. if channel and active_session_file is not None:
  520. session.active_session_cleanup = (
  521. lambda app=ws.app, ch=channel, path=active_session_file:
  522. _discard_active_session_file(app, ch, path)
  523. )
  524. elif not marker_preexisting:
  525. # A different channel attached to an already-existing PTY. The marker
  526. # just allocated for this channel is not owned by that PTY.
  527. _discard_active_session_file(ws.app, channel, active_session_file)
  528. # A fresh xterm can't rebuild the TUI from an arbitrary tail of alternate-
  529. # screen differential output; reused PTYs emit a full frame after replay.
  530. if not await session.attach(ws, force_redraw=not _created):
  531. # attach() detaches itself when the client dropped mid-replay, and a socket
  532. # superseded during replay is already closed by its replacement; only a
  533. # stalled redraw write leaves THIS socket attached and worth closing.
  534. if session._ws is ws:
  535. await _close_stalled_pty_input(ws, path="keepalive-redraw")
  536. PTY_REGISTRY.detach(attach_token, ws)
  537. return
  538. # Writer loop only: the session's drain task (one per PTY, inside the
  539. # registry) forwards output to whichever socket is attached and ring-buffers
  540. # it while detached. On child EOF it closes the attached socket with 4410,
  541. # which unparks ws.receive() — same half-open protection as the legacy pump.
  542. try:
  543. await _pump_keepalive_input(ws, session)
  544. except WebSocketDisconnect:
  545. pass
  546. finally:
  547. # Detach only — the PTY keeps running for a reattach; the registry
  548. # reaper closes it after the TTL (or immediately on process exit).
  549. PTY_REGISTRY.detach(attach_token, ws)
  550. # --- /api/ws: JSON-RPC sidecar for the Chat tab. Drives the same
  551. # tui_gateway.dispatch surface Ink uses over stdio so the dashboard can render
  552. # structured metadata next to the xterm; both transports bind to the same
  553. # session id, so agent emits fan out to both sinks.
  554. def _authority_for_ticket_home(authority, home: str):
  555. """The authority serving *home*: *authority* itself for its own home, else the served sibling,
  556. or None when this process does not serve it."""
  557. from pathlib import Path
  558. from gateway.session_authorities import authority_for_home
  559. if Path(authority.profile_id).resolve() == Path(home).resolve():
  560. return authority
  561. return authority_for_home(getattr(authority, 'runner', None), home)
  562. @router.websocket("/api/ws")
  563. async def gateway_ws(ws: WebSocket) -> None:
  564. if not await _close_unless_sidecar_allowed(ws, allow_internal=True, socket=GATEWAY_SOCKET):
  565. return
  566. from hermes_cli.mcp_startup import start_deferred_mcp_discovery_now
  567. from tui_gateway.ws import handle_ws
  568. # First chat client of a standalone dashboard: fire the discovery armed at boot (no-op
  569. # otherwise). Off-loop: the first act is a config read + the ~350 ms `mcp` SDK import.
  570. await asyncio.to_thread(start_deferred_mcp_discovery_now)
  571. # The authenticated identity (ticket / internal credential) stamped by
  572. # _ws_auth_reason becomes the identity authority for session ownership and
  573. # relay authorship. None on the legacy token path.
  574. identity = getattr(ws, "_hermes_auth_identity", None)
  575. authority = getattr(ws.app.state, "session_authority", None)
  576. if authority is not None and identity is None:
  577. # The upgrade gate above has already verified the legacy token. Do not
  578. # infer owner permissions from an identityless connection downstream.
  579. identity = {'user_id': 'legacy-token-owner', 'provider': 'session-token',
  580. 'profile_id': authority.profile_id, 'instance_id': authority.instance_id,
  581. 'capabilities': ['session:create', 'session:read', 'session:submit',
  582. 'session:control', 'session:approve', 'session:respond']}
  583. if identity is not None:
  584. # The dashboard gate authorizes the whole host (its REST routes take ``?profile=`` for
  585. # every profile), so its socket may select any served sibling too.
  586. identity = {**identity, 'profile_scope': 'host'}
  587. ticket_home = getattr(ws, "_hermes_ticket_profile_home", None)
  588. served = authority
  589. if ticket_home and authority is None:
  590. # Only the gateway mints a profile-bound ticket, and it unbinds its authority while the
  591. # listener stops: serving the launch profile now would answer the tab for the wrong one.
  592. await ws.close(code=1013)
  593. return
  594. if ticket_home and identity is not None:
  595. # A Webapp tab's ticket names its profile (``webapp.issue_gateway_ticket``): bind the socket
  596. # to that home's authority, as a native ticket does (``gateway/run_api.py``), so a request
  597. # that names no profile is answered for the tab's profile, not the launch profile.
  598. served = _authority_for_ticket_home(authority, ticket_home)
  599. if served is None:
  600. await ws.close(code=4403)
  601. return
  602. ws.scope['hermes.session_authority'] = served
  603. identity = {**identity, 'profile_id': served.profile_id, 'instance_id': served.instance_id}
  604. # The socket runs in the served profile's scope, as a native ticket's does (``gateway/run_api.py``):
  605. # legacy handlers (billing, usage, subscription) read that profile's secrets with no scope of
  606. # their own, and a multiplexed gateway refuses an unscoped read.
  607. profile_scope = contextlib.nullcontext()
  608. if served is not None:
  609. from gateway.session_authorities import owner_scope
  610. profile_scope = owner_scope(served)
  611. with profile_scope:
  612. await handle_ws(
  613. ws,
  614. auth_identity=identity,
  615. operator=True, # The dashboard upgrade gate above has verified this operator.
  616. subprotocol=getattr(ws, "_hermes_ws_subprotocol", None),
  617. )
  618. # --- /api/pub + /api/events: the PTY-side tui_gateway.entry opens /api/pub
  619. # (HERMES_TUI_SIDECAR_URL from /api/pty's env) and writes every dispatcher emit
  620. # through it; the dashboard fans frames out to /api/events subscribers on the
  621. # same channel — the React sidebar's tool-call feed without touching the PTY
  622. # child's stdio handshake with Ink.
  623. async def _accept_channel_ws(ws: WebSocket, *, allow_internal: bool = False) -> Optional[str]:
  624. if not await _close_unless_sidecar_allowed(ws, allow_internal=allow_internal):
  625. return None
  626. channel = _channel_or_close_code(ws)
  627. if not channel:
  628. await ws.close(code=4400)
  629. return None
  630. await ws.accept()
  631. return channel
  632. @router.websocket("/api/pub")
  633. async def pub_ws(ws: WebSocket) -> None:
  634. channel = await _accept_channel_ws(ws, allow_internal=True)
  635. if channel is None:
  636. return
  637. try:
  638. while True:
  639. await _broadcast_event(ws.app, channel, await ws.receive_text())
  640. except WebSocketDisconnect:
  641. pass
  642. @router.websocket("/api/events")
  643. async def events_ws(ws: WebSocket) -> None:
  644. channel = await _accept_channel_ws(ws)
  645. if channel is None:
  646. return
  647. event_channels, event_lock = _get_event_state(ws.app)
  648. async with event_lock:
  649. event_channels.setdefault(channel, set()).add(ws)
  650. try:
  651. while True:
  652. # Subscribers don't speak — receive() just blocks until disconnect.
  653. await ws.receive_text()
  654. except WebSocketDisconnect:
  655. pass
  656. finally:
  657. async with event_lock:
  658. subs = event_channels.get(channel)
  659. if subs is not None:
  660. subs.discard(ws)
  661. if not subs:
  662. event_channels.pop(channel, None)