From 4155ea97e881e12d68688fc323abbd6c6bcce0f3 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:31:51 -0700 Subject: [PATCH] perf(serve): Desktop backend announces its socket before MCP discovery imports the SDK MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `cmd_dashboard` started the background MCP discovery thread before importing `hermes_cli.web_server`. The thread's first act is the ~350ms `mcp` SDK import, which holds the GIL against the main thread's own web_server import, so the HERMES_BACKEND_READY sentinel — and every renderer paint behind it — moved ~300ms later on every Desktop cold start with any MCP server configured. Desktop `serve` (headless + HERMES_DESKTOP=1) now arms discovery one second after the sentinel instead. Starting it AT the bind was measured to give back most of the gain (the renderer's WebSocket connect + first hydration reads contend on the same loop). An agent build inside that window pulls the deferred start forward itself via `wait_for_mcp_discovery`, so the bounded join and the late-binding tool refresh behave exactly as before. Dashboard and non-Desktop `serve` keep the eager pre-import ordering. Minimal reimplementation of the MCP-deferral slice of #96751 by @helix4u; the plugin-route deferral / 503 middleware / cron-after-bind slices were measured at ~0-10ms each and are not taken. Co-authored-by: Gille <4317663+helix4u@users.noreply.github.com> --- hermes_cli/main.py | 34 ++++++--- hermes_cli/mcp_startup.py | 41 +++++++++++ hermes_cli/web_server.py | 31 ++++++++ .../test_serve_mcp_discovery_after_bind.py | 70 +++++++++++++++++++ 4 files changed, 165 insertions(+), 11 deletions(-) create mode 100644 tests/hermes_cli/test_serve_mcp_discovery_after_bind.py diff --git a/hermes_cli/main.py b/hermes_cli/main.py index b801ac399d..16e0a32f2d 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -12401,18 +12401,29 @@ def cmd_dashboard(args): # this, a profile's configured MCP servers never connect, so desktop # sessions show no MCP tools. Spawn discovery in the background here so a # slow/dead server can't block dashboard startup. - try: - from hermes_cli.mcp_startup import start_background_mcp_discovery + # + # Desktop-spawned headless backends start it AFTER the socket binds + # instead (start_server's ready path): the thread's first act is the + # ~350ms `mcp` SDK import, which holds the GIL against the main thread's + # own web_server import and pushes the READY sentinel — and every + # renderer paint behind it — back by that much. The Desktop can't issue + # an agent turn until its WebSocket is up anyway, and _make_agent's + # bounded wait_for_mcp_discovery + the late-binding refresh cover a + # server that is still connecting when the first turn lands. + _mcp_discovery_after_bind = _headless_backend and os.environ.get("HERMES_DESKTOP") == "1" + if not _mcp_discovery_after_bind: + try: + from hermes_cli.mcp_startup import start_background_mcp_discovery - start_background_mcp_discovery( - logger=logger, - thread_name="dashboard-mcp-discovery", - ) - except Exception: - logger.debug( - "Background MCP tool discovery failed at dashboard startup", - exc_info=True, - ) + start_background_mcp_discovery( + logger=logger, + thread_name="dashboard-mcp-discovery", + ) + except Exception: + logger.debug( + "Background MCP tool discovery failed at dashboard startup", + exc_info=True, + ) from hermes_cli.web_server import start_server @@ -12435,6 +12446,7 @@ def cmd_dashboard(args): headless=_headless_backend, ssh_session_token=_ssh_session_token, ssh_owner_nonce=_ssh_owner_nonce, + start_mcp_discovery_after_bind=_mcp_discovery_after_bind, ) diff --git a/hermes_cli/mcp_startup.py b/hermes_cli/mcp_startup.py index c368805405..77a972591d 100644 --- a/hermes_cli/mcp_startup.py +++ b/hermes_cli/mcp_startup.py @@ -9,6 +9,7 @@ from typing import Optional _mcp_discovery_lock = threading.Lock() _mcp_discovery_started = False _mcp_discovery_thread: Optional[threading.Thread] = None +_mcp_discovery_deferred: Optional[threading.Timer] = None def _has_configured_mcp_servers() -> bool: @@ -172,6 +173,45 @@ def _discover_mcp_tools_without_interactive_oauth() -> None: discover_mcp_tools() +def defer_background_mcp_discovery(*, logger, thread_name: str, delay: float) -> None: + """Arm ``start_background_mcp_discovery`` to run ``delay`` seconds from now. + + Used by the Desktop ``serve`` backend after its socket is announced: the + discovery thread's first act is the ~350ms ``mcp`` SDK import, which holds + the GIL against the renderer's connect + first hydration reads if it starts + at bind time, and against the web_server import if it starts before. Any + consumer that needs discovery sooner (``wait_for_mcp_discovery`` from an + agent build) fires the deferred start immediately, so the bounded join and + the late-binding refresh behave exactly as if it had been started eagerly. + """ + global _mcp_discovery_deferred + with _mcp_discovery_lock: + if _mcp_discovery_started or _mcp_discovery_deferred is not None: + return + + def _fire() -> None: + global _mcp_discovery_deferred + with _mcp_discovery_lock: + _mcp_discovery_deferred = None + start_background_mcp_discovery(logger=logger, thread_name=thread_name) + + timer = threading.Timer(delay, _fire) + timer.daemon = True + timer.name = f"{thread_name}-deferred" + _mcp_discovery_deferred = timer + timer.start() + + +def _start_deferred_mcp_discovery_now() -> None: + """Run an armed deferred start immediately (idempotent, thread-safe).""" + with _mcp_discovery_lock: + timer = _mcp_discovery_deferred + if timer is None: + return + timer.cancel() + timer.function() + + def wait_for_mcp_discovery( timeout: "float | None" = None, *, single_query: bool = False ) -> None: @@ -188,6 +228,7 @@ def wait_for_mcp_discovery( ``mcp_single_query_discovery_timeout`` instead (default 15s vs 1.5s interactive) because one-shot sessions have no second turn to recover. """ + _start_deferred_mcp_discovery_now() thread = _mcp_discovery_thread if thread is None or not thread.is_alive(): return diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py index 9433f6f16d..cb5add9112 100644 --- a/hermes_cli/web_server.py +++ b/hermes_cli/web_server.py @@ -320,6 +320,11 @@ def _start_desktop_cron_ticker(stop_event: "threading.Event", interval: int = 60 provider.start(stop_event, **start_kwargs) +# Desktop `serve` only (start_server(start_mcp_discovery_after_bind=True)): +# seconds after the READY sentinel before the MCP discovery thread starts. +_DESKTOP_MCP_DISCOVERY_DELAY_S = 1.0 + + def _warm_gateway_module() -> None: """Pre-import heavy modules so the event loop is not stalled on first use. @@ -19668,6 +19673,7 @@ def start_server( headless: bool = False, ssh_session_token: Optional[str] = None, ssh_owner_nonce: Optional[str] = None, + start_mcp_discovery_after_bind: bool = False, ): """Start the web UI server. @@ -19682,6 +19688,10 @@ def start_server( ``ssh_session_token`` and ``ssh_owner_nonce`` are process-local Desktop SSH bootstrap state. Neither is persisted or exported to child processes. + + ``start_mcp_discovery_after_bind`` (Desktop ``serve``) defers the + background MCP discovery thread until the ready sentinel has been written, + so its SDK import cannot hold the GIL against the pre-bind import path. """ _apply_ssh_session_token(ssh_session_token or "") _apply_ssh_owner_nonce(ssh_owner_nonce) @@ -20059,6 +20069,27 @@ def start_server( print(f" Hermes Web UI → http://{host}:{actual_port}") _maybe_open_browser(host, actual_port, open_browser, initial_profile) + if start_mcp_discovery_after_bind: + # Deferred from cmd_dashboard for Desktop `serve` (see there). + # Not started at the bind itself either: the ~350ms `mcp` SDK + # import holds the GIL, and at bind time the renderer is doing + # its WebSocket handshake + first hydration reads against this + # loop (measured: starting it here gave back most of the + # READY gain as a slower connect). One second later the shell + # is painted and idle. An agent build inside that second fires + # the deferred start itself (wait_for_mcp_discovery), so its + # bounded join and the late-binding refresh are unchanged. + try: + from hermes_cli.mcp_startup import defer_background_mcp_discovery + + defer_background_mcp_discovery( + logger=_log, + thread_name="dashboard-mcp-discovery", + delay=_DESKTOP_MCP_DISCOVERY_DELAY_S, + ) + except Exception: + _log.debug("Deferred MCP discovery arm failed", exc_info=True) + # Collapse the peer-hangup teardown flood (#50005). When the Desktop # forcibly closes its WebSocket mid-write, asyncio logs a full # traceback per pending connection-lost callback — 50+ identical diff --git a/tests/hermes_cli/test_serve_mcp_discovery_after_bind.py b/tests/hermes_cli/test_serve_mcp_discovery_after_bind.py new file mode 100644 index 0000000000..0ae23f019e --- /dev/null +++ b/tests/hermes_cli/test_serve_mcp_discovery_after_bind.py @@ -0,0 +1,70 @@ +"""Desktop `serve` starts background MCP discovery only after the socket binds. + +The MCP SDK import (~350ms) used to run on a thread started BEFORE +web_server was imported, holding the GIL against the main thread's own +import path and delaying the READY sentinel the Desktop waits on. +""" + +from __future__ import annotations + +import logging +import threading + +import hermes_cli.mcp_startup as mcp_startup +import hermes_cli.web_server as web_server +from tests.hermes_cli.test_dashboard_auth_gate import _stub_uvicorn_run + + +def _reset_discovery_state(monkeypatch): + monkeypatch.setattr(mcp_startup, "_mcp_discovery_started", False) + monkeypatch.setattr(mcp_startup, "_mcp_discovery_thread", None) + monkeypatch.setattr(mcp_startup, "_mcp_discovery_deferred", None) + + +def test_desktop_serve_arms_mcp_discovery_only_after_ready_sentinel(monkeypatch): + _reset_discovery_state(monkeypatch) + order: list[str] = [] + monkeypatch.setattr( + mcp_startup, + "start_background_mcp_discovery", + lambda *, logger, thread_name: order.append("discovery:" + thread_name), + ) + monkeypatch.setattr(web_server, "_write_machine_sentinel_line", lambda line: order.append("sentinel")) + _stub_uvicorn_run(monkeypatch) + + web_server.start_server( + host="127.0.0.1", port=0, open_browser=False, headless=True, + start_mcp_discovery_after_bind=True, + ) + timer = mcp_startup._mcp_discovery_deferred + assert order == ["sentinel"] and isinstance(timer, threading.Timer) + timer.cancel() + # An agent build inside the delay window pulls discovery forward itself. + mcp_startup.wait_for_mcp_discovery(timeout=0) + assert order == ["sentinel", "discovery:dashboard-mcp-discovery"] + assert mcp_startup._mcp_discovery_deferred is None + + # Without the flag (dashboard / non-Desktop serve) start_server does not + # start discovery itself — cmd_dashboard's pre-import path still owns it. + order.clear() + _reset_discovery_state(monkeypatch) + web_server.start_server(host="127.0.0.1", port=0, open_browser=False, headless=True) + assert order == ["sentinel"] and mcp_startup._mcp_discovery_deferred is None + + +def test_deferred_discovery_fires_once_and_is_idempotent(monkeypatch): + _reset_discovery_state(monkeypatch) + calls: list[str] = [] + monkeypatch.setattr( + mcp_startup, + "start_background_mcp_discovery", + lambda *, logger, thread_name: calls.append(thread_name), + ) + log = logging.getLogger("test") + mcp_startup.defer_background_mcp_discovery(logger=log, thread_name="t", delay=60) + mcp_startup.defer_background_mcp_discovery(logger=log, thread_name="t", delay=60) # second arm is a no-op + first = mcp_startup._mcp_discovery_deferred + mcp_startup._start_deferred_mcp_discovery_now() + mcp_startup._start_deferred_mcp_discovery_now() + assert calls == ["t"] + assert first is not None and mcp_startup._mcp_discovery_deferred is None