perf(serve): Desktop backend announces its socket before MCP discovery imports the SDK

`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>
This commit is contained in:
Teknium
2026-09-02 05:31:51 -07:00
parent 0fd9218e5a
commit 4155ea97e8
4 changed files with 165 additions and 11 deletions
+23 -11
View File
@@ -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,
)
+41
View File
@@ -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
+31
View File
@@ -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
@@ -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