Support chat/list and chat/open for eca-desktop

ericdallo · ericdallo · commit 6455e3e54a0b · 2026-04-17T00:19:37.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- New `chat/list` JSON-RPC request returning a summary list of persisted chats for the current workspace (id, title, status, createdAt, updatedAt, model, messageCount). Supports optional `limit` and `sortBy` params. Lets clients populate a chat sidebar on startup without requiring the user to resume each chat manually.
+- New `chat/open` JSON-RPC request that replays a persisted chat to the client by emitting `chat/cleared` (messages), `chat/opened` and the full sequence of `chat/contentReceived` notifications without mutating server state. Intended to be paired with `chat/list` to render a chat the user has not opened in the current client session.
+
 ## 0.127.1
 
 - Auto allow ask_user tool by default.
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -1756,6 +1756,108 @@ _Response:_
 interface ChatUpdateResponse {}
 ```
 
+### Chat list (↩️)
+
+A client request to list all persisted chats for the current workspace,
+so a freshly-started client can populate its sidebar without waiting for the
+user to resume or re-create each chat.
+
+Subagent chats are excluded. Results are sorted descending by `updatedAt` by
+default, falling back to `createdAt` when `updatedAt` is missing.
+
+_Request:_
+
+* method: `chat/list`
+* params: `ChatListParams` defined as follows:
+
+```typescript
+interface ChatListParams {
+    /**
+     * Optional maximum number of chats to return.
+     * When omitted or non-positive, all chats are returned.
+     */
+    limit?: number;
+
+    /**
+     * Optional sort key. Defaults to "updatedAt".
+     */
+    sortBy?: 'updatedAt' | 'createdAt';
+}
+```
+
+_Response:_
+
+```typescript
+interface ChatListResponse {
+    chats: ChatSummary[];
+}
+
+interface ChatSummary {
+    /** The chat session identifier. */
+    id: string;
+
+    /** Human-readable title, when available. */
+    title?: string;
+
+    /** Current chat status. */
+    status: 'idle' | 'running' | 'stopping' | 'login';
+
+    /** Epoch millis when the chat was created, when available. */
+    createdAt?: number;
+
+    /** Epoch millis of the most recent update, when available. */
+    updatedAt?: number;
+
+    /** The last full model id used for this chat, when available. */
+    model?: string;
+
+    /** Number of persisted messages. */
+    messageCount: number;
+}
+```
+
+### Chat open (↩️)
+
+A client request to hydrate a previously-persisted chat so it can be rendered
+in the UI. The server replays the chat by emitting `chat/cleared` (messages),
+`chat/opened`, and a sequence of `chat/contentReceived` notifications matching
+the persisted messages — without mutating server state. Typically used after
+`chat/list` when the user selects a chat that has not been opened in the current
+client session.
+
+_Request:_
+
+* method: `chat/open`
+* params: `ChatOpenParams` defined as follows:
+
+```typescript
+interface ChatOpenParams {
+    /**
+     * The chat session identifier to open.
+     */
+    chatId: string;
+}
+```
+
+_Response:_
+
+```typescript
+interface ChatOpenResponse {
+    /**
+     * True when the chat exists and its content has been replayed via
+     * chat/cleared + chat/opened + chat/contentReceived. False when the
+     * chat is unknown or is a subagent chat.
+     */
+    found: boolean;
+
+    /** The chat id that was replayed (echo of the request), present when found. */
+    chatId?: string;
+
+    /** The chat title at the time of replay, when available. */
+    title?: string;
+}
+```
+
 ### Chat selected agent changed (➡️)
 
 A client notification for server telling the user selected a different agent in chat.
diff --git a/integration-test/integration/chat/list_test.clj b/integration-test/integration/chat/list_test.clj
@@ -0,0 +1,69 @@
+(ns integration.chat.list-test
+  "Exercises the `chat/list` and `chat/open` JSON-RPC methods end-to-end: creates
+  a chat via a simple prompt, asks the server for the current chat list, then
+  replays it via `chat/open` and asserts the server emits the expected
+  `chat/cleared` + `chat/opened` + `chat/contentReceived` notifications."
+  (:require
+   [clojure.test :refer [deftest is testing]]
+   [integration.eca :as eca]
+   [integration.fixture :as fixture]
+   [llm-mock.mocks :as llm.mocks]
+   [matcher-combinators.matchers :as m]
+   [matcher-combinators.test :refer [match?]]))
+
+(eca/clean-after-test)
+
+(defn- drain-until-progress-finished!
+  "Drain chat/contentReceived notifications for `chat-id` until we observe the
+  finishing progress event. Used to wait for a prompt to settle."
+  [chat-id]
+  (loop []
+    (let [n (eca/client-awaits-server-notification :chat/contentReceived)]
+      (when-not (and (= chat-id (:chatId n))
+                     (= "system" (:role n))
+                     (= "progress" (get-in n [:content :type]))
+                     (= "finished" (get-in n [:content :state])))
+        (recur)))))
+
+(deftest chat-list-and-open-test
+  (testing "chat/list returns summaries and chat/open replays the chat"
+    (eca/start-process!)
+
+    (llm.mocks/set-case! :simple-text-0)
+
+    (eca/request! (fixture/initialize-request))
+    (eca/notify! (fixture/initialized-notification))
+
+    (let [prompt-resp (eca/request! (fixture/chat-prompt-request
+                                     {:model "openai/gpt-4.1"
+                                      :message "Hello"}))
+          chat-id (:chatId prompt-resp)]
+      (is (string? chat-id))
+      (drain-until-progress-finished! chat-id)
+
+      (testing "chat/list includes the new chat"
+        (let [result (eca/request! [:chat/list {}])]
+          (is (match? {:chats (m/embeds
+                               [{:id chat-id
+                                 :status "idle"
+                                 :messageCount (m/pred pos-int?)}])}
+                      result))))
+
+      (testing "chat/list honours :limit"
+        (let [result (eca/request! [:chat/list {:limit 1}])]
+          (is (= 1 (count (:chats result))))))
+
+      (testing "chat/open replays chat/cleared + chat/opened + contentReceived"
+        (let [open-resp (eca/request! [:chat/open {:chat-id chat-id}])
+              cleared (eca/client-awaits-server-notification :chat/cleared)
+              opened (eca/client-awaits-server-notification :chat/opened)]
+          (is (match? {:found true :chatId chat-id} open-resp))
+          (is (match? {:chatId chat-id :messages true} cleared))
+          (is (match? {:chatId chat-id} opened))
+          ;; At least one content-received notification must follow
+          (is (match? {:chatId chat-id}
+                      (eca/client-awaits-server-notification :chat/contentReceived)))))
+
+      (testing "chat/open returns found=false for unknown chat ids"
+        (let [result (eca/request! [:chat/open {:chat-id "does-not-exist"}])]
+          (is (match? {:found false} result)))))))
diff --git a/src/eca/features/chat.clj b/src/eca/features/chat.clj
@@ -1337,4 +1337,48 @@
         (lifecycle/send-content! {:messenger messenger :chat-id chat-id}
                                  :system
                                  {:type :text :text (str "Chat forked to: " new-title)})))
-    {}))
+    {}))
+
+(defn list-chats
+  "Pure projection over `(:chats db)`: returns a summary list intended for the
+   client sidebar. Subagent chats are excluded. Supports optional
+   `:limit` (positive int) and `:sort-by` (`:updated-at` or `:created-at`;
+   default `:updated-at`). Results are sorted descending by the chosen
+   timestamp, falling back to the other when the primary is nil."
+  [db {:keys [limit] sort-key :sort-by}]
+  (let [primary (or sort-key :updated-at)
+        secondary (if (= primary :updated-at) :created-at :updated-at)
+        chats (->> (vals (:chats db))
+                   (remove :subagent)
+                   (sort-by (fn [c] (or (get c primary) (get c secondary) 0)) >)
+                   (mapv (fn [{:keys [id title status created-at updated-at model messages]}]
+                           (shared/assoc-some
+                            {:id id
+                             :title title
+                             :status (or status :idle)
+                             :message-count (count messages)}
+                            :created-at created-at
+                            :updated-at updated-at
+                            :model model))))]
+    {:chats (if (and limit (pos? (long limit)))
+              (vec (take (long limit) chats))
+              chats)}))
+
+(defn open-chat!
+  "Replay a persisted chat over the wire so a freshly-started client can render
+   it. Emits `chat/cleared` (messages) followed by `chat/opened` and streams each
+   persisted message via `send-chat-contents!`. Performs no DB mutation.
+   Returns `{:found? false}` when the chat does not exist or is a subagent,
+   otherwise `{:found? true :chat-id ... :title ...}`."
+  [{:keys [chat-id]} db* messenger]
+  (let [chat (get-in @db* [:chats chat-id])]
+    (if (or (nil? chat) (:subagent chat))
+      {:found? false}
+      (let [title (:title chat)
+            messages (:messages chat)
+            chat-ctx {:chat-id chat-id :db* db* :messenger messenger}]
+        (messenger/chat-cleared messenger {:chat-id chat-id :messages true})
+        (messenger/chat-opened messenger (assoc-some {:chat-id chat-id} :title title))
+        (send-chat-contents! messages chat-ctx)
+        (lifecycle/send-content! chat-ctx :system (assoc-some {:type :metadata} :title title))
+        {:found? true :chat-id chat-id :title title}))))
diff --git a/src/eca/handlers.clj b/src/eca/handlers.clj
@@ -244,6 +244,21 @@
   (metrics/task metrics :eca/chat-update
     (f.chat/update-chat params db* messenger metrics)))
 
+(defn chat-list
+  "Return a summary list of persisted chats for the current DB.
+   Supports optional :limit and :sort-by params (see `f.chat/list-chats`)."
+  [{:keys [db* metrics]} params]
+  (metrics/task metrics :eca/chat-list
+    (f.chat/list-chats @db* params)))
+
+(defn chat-open
+  "Replay a persisted chat over the wire for the client to render.
+   Emits chat/cleared, chat/opened and per-message chat/contentReceived
+   notifications for the target chat. Returns `{:found? bool ...}`."
+  [{:keys [db* messenger metrics]} params]
+  (metrics/task metrics :eca/chat-open
+    (f.chat/open-chat! params db* messenger)))
+
 (defn mcp-stop-server [{:keys [db* messenger metrics config]} params]
   (metrics/task metrics :eca/mcp-stop-server
     (f.tools/stop-server! (:name params) db* messenger config metrics)))
diff --git a/src/eca/server.clj b/src/eca/server.clj
@@ -118,6 +118,12 @@
 (defmethod jsonrpc.server/receive-request "chat/update" [_ components params]
   (eventually (handlers/chat-update (with-config components) params)))
 
+(defmethod jsonrpc.server/receive-request "chat/list" [_ components params]
+  (eventually (handlers/chat-list (with-config components) params)))
+
+(defmethod jsonrpc.server/receive-request "chat/open" [_ components params]
+  (eventually (handlers/chat-open (with-config components) params)))
+
 (defmethod jsonrpc.server/receive-notification "mcp/stopServer" [_ components params]
   (async-notify (handlers/mcp-stop-server (with-config components) params)))
 
diff --git a/test/eca/handlers_test.clj b/test/eca/handlers_test.clj
@@ -7,6 +7,7 @@
    [eca.handlers :as handlers]
    [eca.models :as models]
    [eca.test-helper :as h]
+   [matcher-combinators.matchers :as m]
    [matcher-combinators.test :refer [match?]]))
 
 (h/reset-components-before-test)
@@ -259,3 +260,103 @@
     (is (match? {:config-updated [{:chat {:variants ["high" "medium"]
                                           :select-variant "high"}}]}
                 (h/messages)))))
+
+(defn ^:private seed-chats!
+  "Seed the test db with a map of chats keyed by id."
+  [chats]
+  (swap! (h/db*) assoc :chats chats))
+
+(deftest chat-list-test
+  (testing "Returns empty list when db has no chats"
+    (h/reset-components!)
+    (is (match? {:chats []}
+                (handlers/chat-list (h/components) {}))))
+
+  (testing "Returns summary of all non-subagent chats"
+    (h/reset-components!)
+    (seed-chats!
+     {"a" {:id "a" :title "First" :status :idle
+           :created-at 100 :updated-at 300 :model "anthropic/claude"
+           :messages [{:role "user" :content "hi"}
+                      {:role "assistant" :content "hello"}]}
+      "b" {:id "b" :title "Second" :status :idle
+           :created-at 200 :updated-at 400
+           :messages []}})
+    (is (match? {:chats (m/in-any-order
+                         [{:id "b" :title "Second" :status :idle
+                           :created-at 200 :updated-at 400 :message-count 0}
+                          {:id "a" :title "First" :status :idle
+                           :created-at 100 :updated-at 300
+                           :model "anthropic/claude" :message-count 2}])}
+                (handlers/chat-list (h/components) {}))))
+
+  (testing "Subagent chats are excluded"
+    (h/reset-components!)
+    (seed-chats!
+     {"visible" {:id "visible" :title "Normal" :status :idle
+                 :created-at 100 :updated-at 100 :messages []}
+      "hidden" {:id "hidden" :title "Sub" :status :idle
+                :created-at 200 :updated-at 200 :messages []
+                :subagent true :parent-chat-id "visible"}})
+    (let [{:keys [chats]} (handlers/chat-list (h/components) {})]
+      (is (= 1 (count chats)))
+      (is (= "visible" (:id (first chats))))))
+
+  (testing "Sorted by :updated-at descending by default"
+    (h/reset-components!)
+    (seed-chats!
+     {"old" {:id "old" :status :idle :created-at 10 :updated-at 100 :messages []}
+      "mid" {:id "mid" :status :idle :created-at 20 :updated-at 200 :messages []}
+      "new" {:id "new" :status :idle :created-at 30 :updated-at 300 :messages []}})
+    (is (= ["new" "mid" "old"]
+           (mapv :id (:chats (handlers/chat-list (h/components) {}))))))
+
+  (testing "`limit` caps the number of returned chats after sorting"
+    (h/reset-components!)
+    (seed-chats!
+     {"a" {:id "a" :status :idle :created-at 10 :updated-at 100 :messages []}
+      "b" {:id "b" :status :idle :created-at 20 :updated-at 200 :messages []}
+      "c" {:id "c" :status :idle :created-at 30 :updated-at 300 :messages []}})
+    (is (= ["c" "b"]
+           (mapv :id (:chats (handlers/chat-list (h/components) {:limit 2}))))))
+
+  (testing "`sort-by :created-at` switches the sort key"
+    (h/reset-components!)
+    (seed-chats!
+     {"x" {:id "x" :status :idle :created-at 30 :updated-at 100 :messages []}
+      "y" {:id "y" :status :idle :created-at 20 :updated-at 200 :messages []}
+      "z" {:id "z" :status :idle :created-at 10 :updated-at 300 :messages []}})
+    (is (= ["x" "y" "z"]
+           (mapv :id (:chats (handlers/chat-list (h/components)
+                                                 {:sort-by :created-at})))))))
+
+(deftest chat-open-test
+  (testing "Unknown chat returns {:found? false} and emits no messages"
+    (h/reset-components!)
+    (is (match? {:found? false}
+                (handlers/chat-open (h/components) {:chat-id "missing"})))
+    (is (nil? (:chat-opened (h/messages)))))
+
+  (testing "Subagent chat is treated as not found"
+    (h/reset-components!)
+    (seed-chats!
+     {"sub" {:id "sub" :status :idle :subagent true :parent-chat-id "main"
+             :messages [] :created-at 1 :updated-at 1}})
+    (is (match? {:found? false}
+                (handlers/chat-open (h/components) {:chat-id "sub"})))
+    (is (nil? (:chat-opened (h/messages)))))
+
+  (testing "Known chat emits chat/cleared + chat/opened and returns found? true"
+    (h/reset-components!)
+    (seed-chats!
+     {"c1" {:id "c1" :title "Hello world" :status :idle
+            :created-at 10 :updated-at 20
+            :messages [{:role "user" :content [{:type :text :text "hi"}]}]}})
+    (let [result (handlers/chat-open (h/components) {:chat-id "c1"})]
+      (is (match? {:found? true
+                   :chat-id "c1"
+                   :title "Hello world"}
+                  result))
+      (is (match? {:chat-clear [{:chat-id "c1" :messages true}]
+                   :chat-opened [{:chat-id "c1" :title "Hello world"}]}
+                  (h/messages))))))
