Support ask_user agent questions for remote REST/SSE clients

The ask_user tool's :enabled-fn checks :client-capabilities :code-assistant
:chat-capabilities :ask-question, which JSON-RPC editors set during
initialize but REST/SSE clients (e.g. eca-web) had no way to declare.
The LLM therefore could not invoke ask_user and emitted questions as
plain markdown, leaving web users unable to answer interactively.

Wire the missing pieces:
- Declare the askQuestion capability after the remote Jetty server binds.
- BroadcastMessenger.ask-question mints a requestId, registers a promise
  in a per-record pending-questions registry, and broadcasts chat:ask-question
  over SSE; falls back to the inner JSON-RPC messenger when no SSE clients
  are connected so editor sessions are unaffected.
- New POST /api/v1/answer route + handle-answer-question handler resolves
  the pending promise. Uses swap-vals! so concurrent answers for the same
  requestId atomically claim the entry; only the winner returns 204.

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

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

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Support `ask_user` agent questions for remote REST/SSE clients (e.g. `eca-web`): the remote server now declares the `askQuestion` capability, broadcasts `chat:ask-question` over SSE with a generated `requestId`, and accepts answers via the new `POST /api/v1/answer` endpoint. Falls back to the JSON-RPC inner messenger when no SSE clients are connected, preserving editor behavior.
+
 ## 0.132.0
 
 - `variantsByModel` entries now support an optional `:api` filter (string or vector) to restrict variant matching by provider API type.

src/eca/remote/handlers.clj

@@ -8,6 +8,7 @@
    [eca.config :as config]
    [eca.features.chat :as f.chat]
    [eca.handlers :as handlers]
+   [eca.remote.messenger :as remote.messenger]
    [eca.remote.sse :as sse]
    [eca.shared :as shared]
    [ring.core.protocols :as ring.protocols])
@@ -261,6 +262,28 @@
     (sse/broadcast! sse-connections* "trust:updated" {:trust trust})
     (json-response {:trust trust})))
 
+(defn handle-answer-question
+  "Resolves a pending question previously asked via the SSE `chat:ask-question`
+   event. Body: {:requestId String :answer (String|nil) :cancelled Boolean}.
+   Returns 204 on success, 400 if `requestId` is missing or blank, 404 if the
+   requestId is unknown (e.g. already answered or never registered)."
+  [{:keys [messenger]} request]
+  (let [body (parse-body request)
+        request-id (:requestId body)]
+    (cond
+      (not (and (string? request-id) (seq request-id)))
+      (error-response 400 "invalid_request" "Missing required field: requestId")
+
+      (remote.messenger/answer-question! messenger
+                                         request-id
+                                         (:answer body)
+                                         (:cancelled body))
+      (no-content)
+
+      :else
+      (error-response 404 "question_not_found"
+                      (str "No pending question for requestId " request-id)))))
+
 (defn handle-mcp-start [{:keys [db*] :as components} _request server-name]
   (let [config (config/all @db*)]
     (handlers/mcp-start-server (assoc components :config config) {:name server-name})

src/eca/remote/messenger.clj

@@ -11,7 +11,7 @@
 (defn- ->camel [data]
   (shared/map->camel-cased-map data))
 
-(defrecord BroadcastMessenger [inner sse-connections*]
+(defrecord BroadcastMessenger [inner sse-connections* pending-questions*]
   messenger/IMessenger
 
   (chat-content-received [_this data]
@@ -68,4 +68,39 @@
   (editor-diagnostics [_this uri]
     (messenger/editor-diagnostics inner uri))
   (ask-question [_this params]
-    (messenger/ask-question inner params)))
+    ;; If there are no SSE clients, fall back to the inner messenger so
+    ;; JSON-RPC editor sessions keep working unchanged. Otherwise mint a
+    ;; requestId, register a promise, and broadcast the question to all
+    ;; connected SSE clients. The promise is resolved by `answer-question!`
+    ;; when a client posts to /api/v1/answer.
+    (if (empty? @sse-connections*)
+      (messenger/ask-question inner params)
+      (let [request-id (str (random-uuid))
+            p (promise)]
+        (swap! pending-questions* assoc request-id p)
+        (sse/broadcast! sse-connections* "chat:ask-question"
+                        (->camel (assoc params :requestId request-id)))
+        p))))
+
+(defn make-broadcast-messenger
+  "Creates a BroadcastMessenger with a fresh pending-questions registry.
+   Prefer this over `->BroadcastMessenger` so callers don't have to know
+   about the internal registry atom."
+  [inner sse-connections*]
+  (->BroadcastMessenger inner sse-connections* (atom {})))
+
+(defn answer-question!
+  "Resolves a pending question (previously registered by `ask-question`) by
+   request-id. Delivers `{:answer answer :cancelled (boolean cancelled)}` to
+   the registered promise and removes the entry from the registry.
+   Returns true if a pending question was found and delivered, nil otherwise
+   (e.g. unknown or already-answered request-id).
+
+   Uses `swap-vals!` so that claiming the entry is a single atomic op:
+   under concurrent answer-question! calls for the same request-id only the
+   caller that wins the swap observes the entry in `old` and delivers."
+  [{:keys [pending-questions*]} request-id answer cancelled]
+  (let [[old _new] (swap-vals! pending-questions* dissoc request-id)]
+    (when-let [p (get old request-id)]
+      (deliver p {:answer answer :cancelled (boolean cancelled)})
+      true)))

src/eca/remote/routes.clj

@@ -43,6 +43,10 @@
       (when (= :post method)
         [handlers/handle-set-trust components request {:sse-connections* sse-connections*}])
 
+      ["api" "v1" "answer"]
+      (when (= :post method)
+        [handlers/handle-answer-question components request])
+
       ["api" "v1" "mcp"]
       (when (= :post method)
         [handlers/handle-mcp-add components request])

src/eca/remote/server.clj

@@ -300,6 +300,14 @@
                                    host-with-port
                                    "&pass=" token
                                    "&protocol=" protocol)]
+              ;; Declare the askQuestion capability now that the remote
+              ;; server is up, so the `ask_user` tool is enabled for the
+              ;; LLM. BroadcastMessenger.ask-question routes the question
+              ;; over SSE when at least one client is connected, and falls
+              ;; back to the inner JSON-RPC messenger otherwise.
+              (swap! (:db* components) assoc-in
+                     [:client-capabilities :code-assistant :chat-capabilities :ask-question]
+                     true)
               (when (and localhost-only? private? (not= host-base "127.0.0.1"))
                 (logger/warn logger-tag
                              (str "⚠️  Bound to 127.0.0.1:" actual-port " (localhost only) because another service "

src/eca/server.clj

@@ -273,7 +273,7 @@
         ;; HTTP server can be started later (e.g. when local project config
         ;; enables it after initialize). Broadcasting to an empty set is a no-op.
         sse-connections* (atom #{})
-        messenger (remote.messenger/->BroadcastMessenger stdio-messenger sse-connections*)
+        messenger (remote.messenger/make-broadcast-messenger stdio-messenger sse-connections*)
         start-remote-server!
         (fn [components]
           (when-let [rs (remote.server/start! components sse-connections*)]

test/eca/remote/handlers_test.clj

@@ -3,7 +3,10 @@
    [cheshire.core :as json]
    [clojure.test :refer [deftest is testing]]
    [eca.config :as config]
+   [eca.messenger :as messenger]
    [eca.remote.handlers :as handlers]
+   [eca.remote.messenger :as remote.messenger]
+   [eca.remote.sse :as sse]
    [eca.test-helper :as h]))
 
 (h/reset-components-before-test)
@@ -88,3 +91,43 @@
       (is (= 200 (:status response)))
       (is (string? (:version body)))
       (is (= "1.0" (:protocolVersion body))))))
+
+(deftest handle-answer-question-test
+  (let [inner (h/messenger)
+        sse-connections* (sse/create-connections)
+        broadcast-messenger (remote.messenger/make-broadcast-messenger inner sse-connections*)
+        os (java.io.ByteArrayOutputStream.)
+        _client (sse/add-client! sse-connections* os)
+        request-with-body (fn [body]
+                            {:body (java.io.ByteArrayInputStream.
+                                    (.getBytes ^String (json/generate-string body) "UTF-8"))})]
+
+    (testing "returns 400 when requestId is missing"
+      (let [response (handlers/handle-answer-question
+                      {:messenger broadcast-messenger}
+                      (request-with-body {:answer "x"}))
+            body (json/parse-string (:body response) true)]
+        (is (= 400 (:status response)))
+        (is (= "invalid_request" (get-in body [:error :code])))))
+
+    (testing "returns 404 when requestId is unknown"
+      (let [response (handlers/handle-answer-question
+                      {:messenger broadcast-messenger}
+                      (request-with-body {:requestId "nonexistent" :answer "x"}))
+            body (json/parse-string (:body response) true)]
+        (is (= 404 (:status response)))
+        (is (= "question_not_found" (get-in body [:error :code])))))
+
+    (testing "returns 204 and resolves the pending promise on a successful answer"
+      (let [p (messenger/ask-question broadcast-messenger {:chat-id "c1" :question "Q?"})]
+        (Thread/sleep 100)
+        (let [pending @(:pending-questions* broadcast-messenger)
+              [request-id _] (first pending)
+              response (handlers/handle-answer-question
+                        {:messenger broadcast-messenger}
+                        (request-with-body {:requestId request-id :answer "ok" :cancelled false}))]
+          (is (= 204 (:status response)))
+          (is (realized? p))
+          (is (= {:answer "ok" :cancelled false} @p)))))
+
+    (sse/close-all! sse-connections*)))

test/eca/remote/messenger_test.clj

@@ -11,7 +11,7 @@
 (deftest broadcast-messenger-delegates-and-broadcasts-test
   (let [inner (h/messenger)
         sse-connections* (sse/create-connections)
-        broadcast-messenger (remote.messenger/->BroadcastMessenger inner sse-connections*)
+        broadcast-messenger (remote.messenger/make-broadcast-messenger inner sse-connections*)
         os (java.io.ByteArrayOutputStream.)
         _client (sse/add-client! sse-connections* os)]
 
@@ -60,3 +60,46 @@
         (is (not (.contains (.toString os3 "UTF-8") "rewrite")))))
 
     (sse/close-all! sse-connections*)))
+
+(deftest ask-question-broadcasts-and-resolves-via-answer-test
+  (testing "ask-question registers a promise, broadcasts SSE, and answer-question! resolves it"
+    (let [inner (h/messenger)
+          sse-connections* (sse/create-connections)
+          broadcast-messenger (remote.messenger/make-broadcast-messenger inner sse-connections*)
+          os (java.io.ByteArrayOutputStream.)
+          _client (sse/add-client! sse-connections* os)
+          p (messenger/ask-question broadcast-messenger {:chat-id "c1" :question "Why?"})]
+      (Thread/sleep 100)
+      (is (not (realized? p)) "promise should not be realized before answer")
+      (let [output (.toString os "UTF-8")]
+        (is (.contains output "chat:ask-question") "SSE event name should be chat:ask-question")
+        (is (.contains output "\"chatId\":\"c1\"") "payload should be camel-cased")
+        (is (.contains output "\"requestId\"") "payload should include a generated requestId"))
+      (let [pending @(:pending-questions* broadcast-messenger)
+            [request-id _] (first pending)]
+        (is (= 1 (count pending)) "exactly one pending question should be registered")
+        (is (string? request-id))
+        (is (= true (remote.messenger/answer-question! broadcast-messenger request-id "because" false)))
+        (is (realized? p) "promise should be realized after answer-question!")
+        (is (= {:answer "because" :cancelled false} @p))
+        (is (empty? @(:pending-questions* broadcast-messenger))
+            "registry should be cleared after delivery"))
+      (sse/close-all! sse-connections*))))
+
+(deftest ask-question-falls-back-to-inner-when-no-sse-clients-test
+  (testing "ask-question delegates to inner messenger when no SSE clients are connected"
+    (let [inner (h/messenger)
+          sse-connections* (sse/create-connections)
+          broadcast-messenger (remote.messenger/make-broadcast-messenger inner sse-connections*)]
+      (reset! (:ask-question-response* inner) {:answer "from-inner" :cancelled false})
+      (let [result (messenger/ask-question broadcast-messenger {:chat-id "c1" :question "Why?"})]
+        (is (= {:answer "from-inner" :cancelled false} @result))
+        (is (empty? @(:pending-questions* broadcast-messenger))
+            "no SSE-side registration should occur when delegating to inner")))))
+
+(deftest answer-question-returns-nil-for-unknown-id-test
+  (testing "answer-question! returns nil when the request-id is unknown"
+    (let [inner (h/messenger)
+          sse-connections* (sse/create-connections)
+          broadcast-messenger (remote.messenger/make-broadcast-messenger inner sse-connections*)]
+      (is (nil? (remote.messenger/answer-question! broadcast-messenger "nonexistent" "x" false))))))