perf(cli): stop eager MCP discovery from blocking agent-capable startup

hermes_cli/main.py

@@ -11262,6 +11262,26 @@ _AGENT_SUBCOMMANDS = {
 }
 
 
+def _is_tui_chat_launch(args) -> bool:
+    return bool(getattr(args, "tui", False) or os.environ.get("HERMES_TUI") == "1")
+
+
+def _command_has_dedicated_mcp_startup(args) -> bool:
+    if args.command == "acp":
+        return True
+    if args.command == "gateway" and getattr(args, "gateway_command", None) == "run":
+        return True
+    if args.command == "cron" and getattr(args, "cron_command", None) in {"run", "tick"}:
+        return True
+    return False
+
+
+def _should_background_mcp_startup(args) -> bool:
+    if _is_tui_chat_launch(args):
+        return False
+    return args.command in {None, "chat", "rl"}
+
+
 def _prepare_agent_startup(args) -> None:
     """Discover plugins/MCP/hooks for commands that can run an agent turn."""
     _sub_attr, _sub_set = _AGENT_SUBCOMMANDS.get(args.command, (None, None))
@@ -11281,19 +11301,42 @@ def _prepare_agent_startup(args) -> None:
             "plugin discovery failed at CLI startup",
             exc_info=True,
         )
-    try:
-        # MCP tool discovery — no event loop running in CLI/TUI startup,
-        # so inline is safe.  Moved here from model_tools.py module scope
-        # to avoid freezing the gateway's event loop on its first message
-        # via the same lazy import path (#16856).
-        from tools.mcp_tool import discover_mcp_tools
+    _run_inline_mcp_discovery = True
+    if _is_tui_chat_launch(args):
+        # The TUI launcher hands off to a dedicated startup path that already
+        # backgrounds MCP discovery with a bounded join before the first tool
+        # snapshot.
+        _run_inline_mcp_discovery = False
+    elif _command_has_dedicated_mcp_startup(args):
+        # These entrypoints already do their own MCP startup later on the real
+        # runtime path (gateway executor, ACP launcher, cron job runner).
+        _run_inline_mcp_discovery = False
+    elif _should_background_mcp_startup(args):
+        try:
+            from hermes_cli.mcp_startup import start_background_mcp_discovery
 
-        discover_mcp_tools()
-    except Exception:
-        logger.debug(
-            "MCP tool discovery failed at CLI startup",
-            exc_info=True,
-        )
+            start_background_mcp_discovery(
+                logger=logger,
+                thread_name="cli-mcp-discovery",
+            )
+        except Exception:
+            logger.debug(
+                "Background MCP tool discovery failed at CLI startup",
+                exc_info=True,
+            )
+        _run_inline_mcp_discovery = False
+    if _run_inline_mcp_discovery:
+        try:
+            # MCP tool discovery remains synchronous for entrypoints that do
+            # not own a later bounded/executor startup path.
+            from tools.mcp_tool import discover_mcp_tools
+
+            discover_mcp_tools()
+        except Exception:
+            logger.debug(
+                "MCP tool discovery failed at CLI startup",
+                exc_info=True,
+            )
     try:
         from hermes_cli.config import load_config
         from agent.shell_hooks import register_from_config

hermes_cli/mcp_startup.py

@@ -0,0 +1,59 @@
+"""Shared CLI/TUI-safe helpers for background MCP discovery."""
+
+from __future__ import annotations
+
+import threading
+from typing import Optional
+
+_mcp_discovery_lock = threading.Lock()
+_mcp_discovery_started = False
+_mcp_discovery_thread: Optional[threading.Thread] = None
+
+
+def _has_configured_mcp_servers() -> bool:
+    """Cheap config probe so non-MCP users avoid importing the MCP stack."""
+    try:
+        from hermes_cli.config import read_raw_config
+
+        mcp_servers = (read_raw_config() or {}).get("mcp_servers")
+        return isinstance(mcp_servers, dict) and len(mcp_servers) > 0
+    except Exception:
+        # Be conservative: if config probing fails, try discovery in the
+        # background so startup still can't block.
+        return True
+
+
+def start_background_mcp_discovery(*, logger, thread_name: str) -> None:
+    """Spawn one shared background MCP discovery thread for this process."""
+    global _mcp_discovery_started, _mcp_discovery_thread
+
+    with _mcp_discovery_lock:
+        if _mcp_discovery_started:
+            return
+        _mcp_discovery_started = True
+        if not _has_configured_mcp_servers():
+            return
+
+        def _discover() -> None:
+            try:
+                from tools.mcp_tool import discover_mcp_tools
+
+                discover_mcp_tools()
+            except Exception:
+                logger.debug("Background MCP tool discovery failed", exc_info=True)
+
+        thread = threading.Thread(
+            target=_discover,
+            name=thread_name,
+            daemon=True,
+        )
+        _mcp_discovery_thread = thread
+        thread.start()
+
+
+def wait_for_mcp_discovery(timeout: float = 0.75) -> None:
+    """Briefly wait for background MCP discovery before the first tool snapshot."""
+    thread = _mcp_discovery_thread
+    if thread is None or not thread.is_alive():
+        return
+    thread.join(timeout=timeout)