Dispatch handlers off protocol thread to prevent ECA unresponsiveness

The jsonrpc4clj protocol thread processes all client messages sequentially
on a single thread. Any blocking handler (MCP init/stop, inline completion,
provider login, etc.) would stall all subsequent messages.

Adopt clojure-lsp's `eventually` pattern (promesa p/thread) to dispatch
request and notification handlers to background threads, releasing the
protocol thread immediately.

- Add `eventually` macro for request handlers (returns promise, jsonrpc4clj
  sends response when it resolves)
- Add `async-notify` macro for notification handlers (fire-and-forget with
  error logging)
- Wrap all request handlers except initialize/shutdown (lifecycle ordering)
- Wrap all notification handlers except exit/toolCallApprove/toolCallReject/
  promptStop (lifecycle and critical-path control flow)
- Fix MCP stop-server! to cancel in-progress init and use fire-and-forget
  for force-stop path
- Simplify MCP start-server!/restart-server! by removing redundant daemon
  threads (async-notify already provides background thread)
- Extract with-init-thread macro for init thread lifecycle tracking

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca <git@eca.dev>

Author: ericdallo

CHANGELOG.md

@@ -3,6 +3,8 @@
 ## Unreleased
 
 - Bump plumcp to 0.2.0-beta6.
+- Fix MCP server start/stop blocking the protocol thread, causing ECA to become unresponsive.
+- Dispatch request and notification handlers off the protocol thread to prevent blocking.
 
 ## 0.122.1
 

src/eca/features/tools/mcp.clj

@@ -50,6 +50,18 @@
     (.interrupt thread))
   (reset! init-threads* {}))
 
+(defmacro ^:private with-init-thread
+  "Registers the current thread in `init-threads*` for the given server name,
+  executes body, and deregisters in a finally block. Allows `stop-server!` and
+  `shutdown!` to interrupt in-progress initializations."
+  [server-name & body]
+  `(let [name# ~server-name]
+     (register-init-thread! name# (Thread/currentThread))
+     (try
+       ~@body
+       (finally
+         (deregister-init-thread! name#)))))
+
 (def ^:private env-var-regex
   #"\$(\w+)|\$\{([^}]+)\}")
 
@@ -421,28 +433,32 @@
             (on-server-updated (->server server-name server-config :disabled db))
             (let [t (Thread.
                      (fn []
-                       (try
-                         (initialize-server! server-name db* config metrics on-server-updated)
-                         (finally
-                           (deregister-init-thread! server-name)))))]
+                       (with-init-thread server-name
+                         (initialize-server! server-name db* config metrics on-server-updated))))]
               (.setName t (str "mcp-init-" server-name))
               (.setDaemon t true)
-              (register-init-thread! server-name t)
               (.start t))))))))
 
 (def ^:private disconnect-timeout-ms 3000)
 
 (defn stop-server! [name db* config {:keys [on-server-updated]}]
+  (when-let [^Thread init-thread (get @init-threads* name)]
+    (logger/info logger-tag (format "Interrupting in-progress init thread for server '%s'" name))
+    (.interrupt init-thread)
+    (deregister-init-thread! name))
   (when-let [{:keys [client http-client]} (get-in @db* [:mcp-clients name])]
     (let [server-config (get-in config [:mcpServers name])]
       (swap! db* assoc-in [:mcp-clients name :status] :stopping)
       (on-server-updated (->server name server-config :stopping @db*))
       (let [f (future (try (pmc/disconnect! client) (catch Exception _ nil)))]
         (when-not (deref f disconnect-timeout-ms nil)
           (logger/warn logger-tag (format "Timeout disconnecting MCP server %s, forcing transport stop" name))
-          (if http-client
-            (try (pp/stop! http-client) (catch Exception _))
-            (try (pp/stop-client-transport! (pcs/?transport client) false) (catch Exception _)))))
+          ;; Fire-and-forget: pp/stop! can block indefinitely on HttpClient.close()
+          ;; awaiting internal thread termination, so we must not block the caller.
+          (future
+            (if http-client
+              (try (pp/stop! http-client) (catch Exception _))
+              (try (pp/stop-client-transport! (pcs/?transport client) false) (catch Exception _))))))
       (swap! db* assoc-in [:mcp-clients name :status] :stopped)
       (on-server-updated (->server name server-config :stopped @db*))
       (swap! db* update :mcp-clients dissoc name)
@@ -452,7 +468,8 @@
   (when-let [server-config (get-in config [:mcpServers name])]
     (when (get server-config :disabled false)
       (logger/info logger-tag (format "Starting MCP server %s from manual request despite :disabled=true" name)))
-    (initialize-server! name db* config metrics on-server-updated)))
+    (with-init-thread name
+      (initialize-server! name db* config metrics on-server-updated))))
 
 (defn ^:private open-browser! [^String url]
   (try
@@ -495,20 +512,12 @@
         (open-browser! authorization-endpoint)))))
 
 (defn ^:private restart-server!
-  "Stop the server if running, then spawn a daemon thread to re-initialize it."
+  "Stop the server if running, then re-initialize it on the current thread."
   [name db* config metrics on-server-updated]
   (when (get-in @db* [:mcp-clients name :client])
     (stop-server! name db* config {:on-server-updated on-server-updated}))
-  (let [t (Thread.
-           (fn []
-             (try
-               (initialize-server! name db* config metrics on-server-updated)
-               (finally
-                 (deregister-init-thread! name)))))]
-    (.setName t (str "mcp-init-" name))
-    (.setDaemon t true)
-    (register-init-thread! name t)
-    (.start t)))
+  (with-init-thread name
+    (initialize-server! name db* config metrics on-server-updated)))
 
 (defn logout-server!
   "Logout from an MCP server by clearing stored OAuth credentials and restarting it."

src/eca/server.clj

@@ -14,7 +14,8 @@
    [eca.shared :as shared :refer [assoc-some]]
    [jsonrpc4clj.io-server :as io-server]
    [jsonrpc4clj.liveness-probe :as liveness-probe]
-   [jsonrpc4clj.server :as jsonrpc.server]))
+   [jsonrpc4clj.server :as jsonrpc.server]
+   [promesa.core :as p]))
 
 (set! *warn-on-reflection* true)
 
@@ -37,13 +38,31 @@
 (defn ^:private with-config [components]
   (assoc components :config (config/all @(:db* components))))
 
+(defmacro ^:private eventually
+  "Dispatches handler body to a background thread, returning a promise.
+  Releases the protocol thread immediately. jsonrpc4clj resolves the promise
+  and sends the JSON-RPC response when the work completes."
+  [& body]
+  `(p/thread ~@body))
+
+(defmacro ^:private async-notify
+  "Dispatches notification handler body to a background thread.
+  Releases the protocol thread immediately. Exceptions are logged since
+  notification handlers have no response channel."
+  [& body]
+  `(p/thread
+     (try
+       ~@body
+       (catch Throwable e#
+         (logger/error e# "[server] Error in async notification handler")))))
+
 (defmethod jsonrpc.server/receive-request "initialize" [_ {:keys [server] :as components} params]
   (when-let [parent-process-id (:process-id params)]
     (liveness-probe/start! parent-process-id log-wrapper-fn #(exit server)))
   (handlers/initialize components params))
 
 (defmethod jsonrpc.server/receive-notification "initialized" [_ components _params]
-  (handlers/initialized (with-config components)))
+  (async-notify (handlers/initialized (with-config components))))
 
 (defmethod jsonrpc.server/receive-request "shutdown" [_ components _params]
   (handlers/shutdown (with-config components)))
@@ -52,19 +71,19 @@
   (exit server))
 
 (defmethod jsonrpc.server/receive-notification "workspace/didChangeWorkspaceFolders" [_ components params]
-  (handlers/workspace-did-change-folders (with-config components) params))
+  (async-notify (handlers/workspace-did-change-folders (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/prompt" [_ components params]
-  (handlers/chat-prompt (with-config components) params))
+  (eventually (handlers/chat-prompt (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/queryContext" [_ components params]
-  (handlers/chat-query-context (with-config components) params))
+  (eventually (handlers/chat-query-context (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/queryFiles" [_ components params]
-  (handlers/chat-query-files (with-config components) params))
+  (eventually (handlers/chat-query-files (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/queryCommands" [_ components params]
-  (handlers/chat-query-commands (with-config components) params))
+  (eventually (handlers/chat-query-commands (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "chat/toolCallApprove" [_ components params]
   (handlers/chat-tool-call-approve (with-config components) params))
@@ -76,62 +95,62 @@
   (handlers/chat-prompt-stop (with-config components) params))
 
 (defmethod jsonrpc.server/receive-request "chat/delete" [_ components params]
-  (handlers/chat-delete (with-config components) params))
+  (eventually (handlers/chat-delete (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/clear" [_ components params]
-  (handlers/chat-clear (with-config components) params))
+  (eventually (handlers/chat-clear (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "chat/rollback" [_ components params]
-  (handlers/chat-rollback (with-config components) params))
+  (eventually (handlers/chat-rollback (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/stopServer" [_ components params]
-  (handlers/mcp-stop-server (with-config components) params))
+  (async-notify (handlers/mcp-stop-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/startServer" [_ components params]
-  (handlers/mcp-start-server (with-config components) params))
+  (async-notify (handlers/mcp-start-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/connectServer" [_ components params]
-  (handlers/mcp-connect-server (with-config components) params))
+  (async-notify (handlers/mcp-connect-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/logoutServer" [_ components params]
-  (handlers/mcp-logout-server (with-config components) params))
+  (async-notify (handlers/mcp-logout-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/disableServer" [_ components params]
-  (handlers/mcp-disable-server (with-config components) params))
+  (async-notify (handlers/mcp-disable-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "mcp/enableServer" [_ components params]
-  (handlers/mcp-enable-server (with-config components) params))
+  (async-notify (handlers/mcp-enable-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "mcp/updateServer" [_ components params]
-  (handlers/mcp-update-server (with-config components) params))
+  (eventually (handlers/mcp-update-server (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "chat/selectedAgentChanged" [_ components params]
-  (handlers/chat-selected-agent-changed (with-config components) params))
+  (async-notify (handlers/chat-selected-agent-changed (with-config components) params)))
 
 ;; Legacy: backward compat for clients using old method name
 (defmethod jsonrpc.server/receive-notification "chat/selectedBehaviorChanged" [_ components params]
-  (handlers/chat-selected-agent-changed (with-config components) params))
+  (async-notify (handlers/chat-selected-agent-changed (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-notification "chat/selectedModelChanged" [_ components params]
-  (handlers/chat-selected-model-changed (with-config components) params))
+  (async-notify (handlers/chat-selected-model-changed (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "providers/list" [_ components params]
-  (handlers/providers-list (with-config components) params))
+  (eventually (handlers/providers-list (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "providers/login" [_ components params]
-  (handlers/providers-login (with-config components) params))
+  (eventually (handlers/providers-login (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "providers/loginInput" [_ components params]
-  (handlers/providers-login-input (with-config components) params))
+  (eventually (handlers/providers-login-input (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "providers/logout" [_ components params]
-  (handlers/providers-logout (with-config components) params))
+  (eventually (handlers/providers-logout (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "completion/inline" [_ components params]
-  (handlers/completion-inline (with-config components) params))
+  (eventually (handlers/completion-inline (with-config components) params)))
 
 (defmethod jsonrpc.server/receive-request "rewrite/prompt" [_ components params]
-  (handlers/rewrite-prompt (with-config components) params))
+  (eventually (handlers/rewrite-prompt (with-config components) params)))
 
 (defn ^:private monitor-server-logs [log-ch]
   ;; NOTE: if this were moved to `initialize`, after timbre has been configured,
@@ -236,4 +255,4 @@
          server (io-server/stdio-server {:log-ch log-ch
                                          :trace-ch log-ch
                                          :trace-level (if verbose? "verbose" "off")})]
-     (start-server! server))))
+     (start-server! server))))