PR #19938: fix(tui): accept WebSocket handshake before close to fix FastAPI 0.136 hang on /api/pty

• Repository: NousResearch/hermes-agent
• Author: oluwadareab12
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/19938

Description (problem / solution / changelog)

Fixes #19914

Root cause: FastAPI / Starlette 0.136 changed WebSocket close() semantics. Calling ws.close() before ws.accept() now hangs because the ASGI websocket.connect message must be consumed (via accept()) before a close frame can be sent. The three dashboard WebSocket handlers (/api/pty, /api/ws, /api/pub) all called ws.close() in early-return paths before ws.accept(), causing the handshake to hang indefinitely on FastAPI 0.136.

Fix: Move ws.accept() to the top of each handler before any early-return close(). The same close codes (4401, 4403, 4400) are returned — just after the handshake completes rather than before.

handle_ws change: Added an already_accepted keyword argument so gateway_ws can pass already_accepted=True after accepting itself, preventing a double-accept error.

Files changed:

• hermes_cli/web_server.py: /api/pty, /api/ws, /api/pub handlers
• tui_gateway/ws.py: handle_ws already_accepted parameter

5 new tests in tests/hermes_cli/test_pty_ws_accept_ordering.py, all passing.

Changed files

• hermes_cli/web_server.py (modified, +20/-8)
• plugins/kanban/dashboard/plugin_api.py (modified, +5/-3)
• tests/hermes_cli/conftest.py (added, +55/-0)
• tests/hermes_cli/test_pty_ws_accept_ordering.py (added, +126/-0)
• tests/hermes_cli/test_web_server.py (modified, +14/-8)
• tests/plugins/test_kanban_dashboard_plugin.py (modified, +6/-4)
• tui_gateway/ws.py (modified, +12/-3)

---

PR #19943: fix(cli): run dashboard PTY spawn off the event loop

• Repository: NousResearch/hermes-agent
• Author: konsisumer
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/19943

Description (problem / solution / changelog)

Run _resolve_chat_argv and PtyBridge.spawn in a thread executor so the dashboard /api/pty WebSocket handshake doesn't hang on FastAPI 0.136.

What changed and why

• hermes_cli/web_server.py: /api/pty now invokes _resolve_chat_argv and PtyBridge.spawn via loop.run_in_executor. Both are synchronous and can take seconds (_resolve_chat_argv may shell out to npm install / npm run build; PtyBridge.spawn forks a child). Running them inline starved uvicorn's websockets task so the HTTP 101 upgrade was never flushed and the browser saw the handshake hang. Errors raised from these calls (SystemExit, PtyUnavailableError, FileNotFoundError, OSError) still surface to the client as before.
• tests/hermes_cli/test_web_server.py: added test_argv_resolve_and_spawn_run_off_event_loop, which monkeypatches _resolve_chat_argv and PtyBridge.spawn to record whether asyncio.get_running_loop() succeeds inside them. With the fix both run on a worker thread; without it they'd run on the loop thread (verified by reverting the fix locally — the new test fails as expected).

How to test

• pytest tests/hermes_cli/test_web_server.py -q -k Pty
• Manual: hermes dashboard --tui, open the dashboard's Chat tab, confirm the xterm.js terminal connects without the WebSocket handshake timing out.

What platforms tested on

• macOS on darwin-arm64 (local) — full tests/hermes_cli/test_web_server.py (138 passed) and the targeted Pty subset (20 passed).

Fixes #19914

<!-- autocontrib:worker-id=issue-new-b47427ee kind=pr-open -->

Changed files

• hermes_cli/web_server.py (modified, +17/-5)
• tests/hermes_cli/test_web_server.py (modified, +39/-0)