Per-chat scoping of chat/selectedModelChanged and chat/selectedAgentChanged

Both notifications now accept an optional chatId. When supplied AND
valid AND the chat exists, the server persists model/variant/agent on
that specific chat record (using a CAS swap so a concurrent chat/delete
cannot resurrect a deleted chat as a ghost record) and emits a
config/updated notification carrying the same chatId so clients scope
the update to one chat. Invalid or unknown ids fall through to the
legacy session-wide path with a warn log so we never announce per-chat
state for a chat the server does not recognize.

Also wires up Phase A from the same issue: chat/prompt now treats a
client-supplied unknown chatId as a new empty chat (atomic CAS seed +
chat/opened emission), with validation rejecting blank, the reserved
subagent- prefix, embedded whitespace / control chars, and ids longer
than 256 chars. tool-call-{approve,reject} now no-op safely on unknown
chats. The persisted per-chat key for the agent is now :agent (was
:selected-agent) for symmetry with :model / :variant. The remote REST
endpoints /chat/:chatId/select-{model,agent,variant} now forward the
URL chat-id to the underlying handlers.

editor-code-assistant/eca-emacs#231

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

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

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Support client-generated chat ids: clients may now create the `chatId` themselves and send it on the first `chat/prompt`. eca-emacs#231.
+- Per-chat scoping of model/agent changes: `chat/selectedModelChanged` and `chat/selectedAgentChanged` now accept an optional `chatId`; when provided the server scopes the persisted state and the resulting `config/updated` broadcast to that chat. The remote REST endpoints `/chat/:chatId/select-model|select-agent|select-variant` now forward the URL chat-id to those handlers (previously dropped). `validate-client-chat-id` is now public and rejects whitespace / control chars. eca-emacs#231.
+
 ## 0.133.0
 
 - Add `chat/promptSteerRemove` notification for discarding a pending steer message before it is consumed at the next LLM turn boundary. Idempotent: silent no-op when no steer is pending.

docs/protocol.md

@@ -366,7 +366,22 @@ _Request:_
 ```typescript
 interface ChatPromptParams {
     /**
-     * The chat session identifier. If not provided, a new chat session will be created.
+     * The chat session identifier.
+     *
+     * Clients should generate this id (e.g. a UUID) at the moment the user
+     * opens a new chat in the UI and reuse it across all subsequent requests
+     * for that chat. If the server has never seen the id, it materializes a
+     * new empty chat record on demand and emits a `chat/opened` notification
+     * so other observers (additional clients, remote viewers) can sync.
+     *
+     * Backward compatibility: clients that omit this field still work — the
+     * server will mint an id and return it in the response. In that legacy
+     * path no `chat/opened` notification is emitted (the prompting client
+     * already learns the id from the response payload).
+     *
+     * Reserved: ids starting with `subagent-` are reserved for server-managed
+     * subagent chats and will be rejected. Ids must be non-blank and at most
+     * 256 characters.
      */
     chatId?: string;
 
@@ -1740,8 +1755,18 @@ interface ChatClearedParams {
 
 ### Chat opened (⬅️)
 
-A server notification indicating a new chat was created server-side (e.g. via `/fork`).
-Clients should create a new chat entry in the UI. The chat messages will follow as `chat/contentReceived` notifications.
+A server notification indicating that a chat exists or was just materialized
+server-side. Emitted when:
+
+- a chat is forked via `/fork` or the `chat/fork` request,
+- a persisted chat is replayed via `chat/open`,
+- a client-supplied `chatId` is seen for the first time on `chat/prompt`
+  (the legacy null-`chatId` path does not emit this).
+
+Clients should treat this notification as **idempotent**: if the `chatId`
+already exists in the client's UI, no new chat entry should be created — the
+notification should be ignored or used to update the title. Chat messages
+follow as `chat/contentReceived` notifications.
 
 _Notification:_
 
@@ -1752,17 +1777,70 @@ _Notification:_
 interface ChatOpenedParams {
 
     /**
-     * The new chat session identifier.
+     * The chat session identifier.
      */
     chatId: string;
 
     /**
-     * The title of the new chat.
+     * The title of the chat. Absent for client-initiated new chats that do
+     * not yet have a title.
      */
     title?: string;
 }
 ```
 
+### Chat status changed (⬅️)
+
+A server notification carrying lifecycle transitions for a chat. Clients
+typically use it to drive a "chat is running/idle/stopping" indicator.
+
+_Notification:_
+
+* method: `chat/statusChanged`
+* params: `ChatStatusChangedParams` defined as follows:
+
+```typescript
+interface ChatStatusChangedParams {
+
+    /**
+     * The chat session identifier.
+     */
+    chatId: string;
+
+    /**
+     * Lifecycle status of the chat.
+     *
+     * - `running`:  a prompt is actively being processed (LLM streaming, tool calls in flight).
+     * - `idle`:     prompt finished; chat is ready for further input.
+     * - `stopping`: a stop has been requested (via `chat/promptStop`) and the
+     *               chat is winding down its in-flight work.
+     */
+    status: 'running' | 'idle' | 'stopping';
+}
+```
+
+### Chat deleted (⬅️)
+
+A server notification confirming that a chat was deleted (either via the
+`chat/delete` request from this client or via another connected client / a
+server-side cleanup such as `chatRetentionDays`). Clients should remove the
+chat from their UI.
+
+_Notification:_
+
+* method: `chat/deleted`
+* params: `ChatDeletedParams` defined as follows:
+
+```typescript
+interface ChatDeletedParams {
+
+    /**
+     * The chat session identifier that was deleted.
+     */
+    chatId: string;
+}
+```
+
 ### Chat delete (↩️)
 
 A client request to delete a existing chat, removing all previous messages and used tokens/costs from memory, good for reduce context or start a new clean chat.
@@ -1943,6 +2021,16 @@ _Notification:_
 
 ```typescript
 interface ChatSelectedAgentChanged {
+    /**
+     * The chat session identifier the change applies to.
+     *
+     * When provided, the server persists the selection on this specific
+     * chat record and the resulting `config/updated` broadcast carries the
+     * same `chatId` so clients scope the update to one chat. When omitted,
+     * the change is treated as session-wide (legacy behavior).
+     */
+    chatId?: string;
+
     /**
      * The selected agent.
      */
@@ -1965,6 +2053,16 @@ _Notification:_
 
 ```typescript
 interface ChatSelectedModelChanged {
+    /**
+     * The chat session identifier the change applies to.
+     *
+     * When provided, the server persists model + variant on this specific
+     * chat record and the resulting `config/updated` broadcast carries the
+     * same `chatId` so clients scope the update to one chat. When omitted,
+     * the change is treated as session-wide (legacy behavior).
+     */
+    chatId?: string;
+
     /**
      * The selected model (full model name, e.g. "anthropic/claude-sonnet-4-5").
      */
@@ -2322,6 +2420,17 @@ _Notification:_
 
 ```typescript
 interface ConfigUpdatedParams {
+    /**
+     * When present, scopes this update to a single chat: clients should
+     * apply the per-chat fields (`selectModel`, `selectAgent`,
+     * `selectVariant`, `selectTrust`) only to the chat with this id and
+     * leave other chats untouched. When absent, the update is session-wide
+     * and clients should apply the per-chat fields to every chat (legacy
+     * behavior, used for the initial config push and other genuinely
+     * session-wide events).
+     */
+    chatId?: string;
+
     /**
      * Configs related to chat.
      */

src/eca/config.clj

@@ -665,12 +665,25 @@
       (when (seq result)
         result))))
 
-(defn notify-fields-changed-only! [config-updated messenger db*]
-  (let [config-to-notify (diff-keeping-vectors (:last-config-notified @db*)
-                                               config-updated)]
-    (when (seq config-to-notify)
-      (swap! db* update :last-config-notified shared/deep-merge config-to-notify)
-      (messenger/config-updated messenger config-to-notify))))
+(defn notify-fields-changed-only!
+  "Emit `config/updated` with the fields that have changed against the
+   session-level mirror (`:last-config-notified`) and update that mirror.
+
+   When called with `chat-id` (4-arity), the broadcast is scoped to that
+   chat: it includes `:chat-id` in the payload so the client can apply
+   the change only to that chat's UI state, and bypasses the session-
+   level mirror diff (so per-chat changes never collapse against the
+   session mirror or each other). Used by `chat/selectedModelChanged`
+   and `chat/selectedAgentChanged` when the client supplies a `chatId`."
+  ([config-updated messenger db*]
+   (let [config-to-notify (diff-keeping-vectors (:last-config-notified @db*)
+                                                config-updated)]
+     (when (seq config-to-notify)
+       (swap! db* update :last-config-notified shared/deep-merge config-to-notify)
+       (messenger/config-updated messenger config-to-notify))))
+  ([config-updated messenger _db* chat-id]
+   (when chat-id
+     (messenger/config-updated messenger (assoc config-updated :chat-id chat-id)))))
 
 (defn notify-selected-model-changed!
   "Server-initiated equivalent of a client `chat/selectedModelChanged`: aligns

src/eca/features/chat.clj

@@ -1244,64 +1244,118 @@
      :model full-model
      :status :prompting}))
 
+(def ^:private max-client-chat-id-length 256)
+
+(defn validate-client-chat-id
+  "Validates a client-supplied chat id. Returns nil when valid, otherwise an
+   error message string.
+
+   Public so non-prompt selection handlers (`chat/selectedModelChanged`,
+   `chat/selectedAgentChanged`) can apply the same rules to their `chat-id`
+   field.
+
+   Rejected: blank, the reserved `subagent-` prefix (used for deterministic
+   subagent chat ids in `eca.features.tools.agent`), embedded whitespace or
+   control characters (which would mangle log lines / tab-line titles), and
+   ids longer than `max-client-chat-id-length` characters."
+  [chat-id]
+  (cond
+    (string/blank? chat-id)
+    "chatId must be a non-blank string"
+
+    (string/starts-with? chat-id "subagent-")
+    "chatId prefix 'subagent-' is reserved for server-managed subagent chats"
+
+    (re-find #"[\s\p{Cntrl}]" chat-id)
+    "chatId must not contain whitespace or control characters"
+
+    (> (count chat-id) max-client-chat-id-length)
+    (str "chatId must be " max-client-chat-id-length " characters or fewer")))
+
 (defn prompt
   [{:keys [message agent behavior chat-id contexts variant trust] :as params} db* messenger config metrics]
-  (let [raw-agent (or agent
-                      behavior ;; backward compat: accept old 'behavior' param
-                      (-> config :chat :defaultAgent) ;; legacy
-                      (-> config :defaultAgent))
-        chat-id (or chat-id
-                    (let [new-id (str (random-uuid))]
-                      (swap! db* assoc-in [:chats new-id] {:id new-id})
-                      new-id))
-        selected-agent (config/validate-agent-name raw-agent config)
-        agent-config (get-in config [:agent selected-agent])
-        base-chat-ctx (assoc-some {:metrics metrics
-                                   :config config
-                                   :contexts contexts
-                                   :db* db*
-                                   :messenger messenger
-                                   :user-content-id (lifecycle/new-content-id)
-                                   :message (string/trim message)
-                                   :chat-id chat-id
-                                   :agent selected-agent
-                                   :agent-config agent-config
-                                   :trust trust
-                                   :variant (or variant (:variant agent-config))}
-                                  :parent-chat-id (get-in @db* [:chats chat-id :parent-chat-id]))
-        _ (when (some? trust)
-            (swap! db* assoc-in [:chats chat-id :trust] trust))]
-    (try
-      (prompt* params base-chat-ctx)
-      (catch Exception e
-        (logger/error e)
-        (lifecycle/send-content! base-chat-ctx :system {:type :text
-                                                        :text (str "Error: " (ex-message e) "\n\nCheck ECA stderr for more details.")})
-        (lifecycle/finish-chat-prompt! :idle (dissoc base-chat-ctx :on-finished-side-effect))
-        {:chat-id chat-id
-         :model "error"
-         :status :error}))))
+  (let [provided-chat-id chat-id
+        invalid-id-reason (when (some? provided-chat-id)
+                            (validate-client-chat-id provided-chat-id))]
+    (if invalid-id-reason
+      (do (logger/warn logger-tag "Rejected chat/prompt with invalid chat-id"
+                       {:chat-id provided-chat-id :reason invalid-id-reason})
+          {:chat-id provided-chat-id
+           :model "error"
+           :status :error})
+      (let [raw-agent (or agent
+                          behavior ;; backward compat: accept old 'behavior' param
+                          (-> config :chat :defaultAgent) ;; legacy
+                          (-> config :defaultAgent))
+            chat-id (or provided-chat-id (str (random-uuid)))
+            ;; Atomically seed the chat record if absent and remember whether
+            ;; we were the ones to create it. swap-vals! returns [old new] so
+            ;; chat-just-created? is true iff the chat was missing pre-swap.
+            [old-db _] (swap-vals! db* update :chats
+                                   (fn [chats]
+                                     (if (contains? chats chat-id)
+                                       chats
+                                       (assoc chats chat-id {:id chat-id}))))
+            chat-just-created? (not (contains? (:chats old-db) chat-id))
+            ;; Notify observers (other clients, remote SSE viewers) about a
+            ;; new client-initiated chat. Skipped on the legacy null-id path
+            ;; because the prompting client learns its id from the response.
+            _ (when (and provided-chat-id chat-just-created?)
+                (messenger/chat-opened messenger {:chat-id chat-id}))
+            selected-agent (config/validate-agent-name raw-agent config)
+            agent-config (get-in config [:agent selected-agent])
+            base-chat-ctx (assoc-some {:metrics metrics
+                                       :config config
+                                       :contexts contexts
+                                       :db* db*
+                                       :messenger messenger
+                                       :user-content-id (lifecycle/new-content-id)
+                                       :message (string/trim message)
+                                       :chat-id chat-id
+                                       :agent selected-agent
+                                       :agent-config agent-config
+                                       :trust trust
+                                       :variant (or variant (:variant agent-config))}
+                                      :parent-chat-id (get-in @db* [:chats chat-id :parent-chat-id]))
+            _ (when (some? trust)
+                (swap! db* assoc-in [:chats chat-id :trust] trust))]
+        (try
+          (prompt* params base-chat-ctx)
+          (catch Exception e
+            (logger/error e)
+            (lifecycle/send-content! base-chat-ctx :system {:type :text
+                                                            :text (str "Error: " (ex-message e) "\n\nCheck ECA stderr for more details.")})
+            (lifecycle/finish-chat-prompt! :idle (dissoc base-chat-ctx :on-finished-side-effect))
+            {:chat-id chat-id
+             :model "error"
+             :status :error}))))))
 
 (defn tool-call-approve [{:keys [chat-id tool-call-id save]} db* messenger metrics]
-  (let [chat-ctx {:chat-id chat-id
-                  :db* db*
-                  :metrics metrics
-                  :messenger messenger}]
-    (tc/transition-tool-call! db* chat-ctx tool-call-id :user-approve
-                              {:reason {:code :user-choice-allow
-                                        :text "Tool call allowed by user choice"}})
-    (when (= "session" save)
-      (let [tool-call-name (get-in @db* [:chats chat-id :tool-calls tool-call-id :name])]
-        (swap! db* assoc-in [:tool-calls tool-call-name :remember-to-approve?] true)))))
+  (if-not (get-in @db* [:chats chat-id :tool-calls tool-call-id])
+    (logger/warn logger-tag "tool-call-approve ignored: unknown chat or tool-call"
+                 {:chat-id chat-id :tool-call-id tool-call-id})
+    (let [chat-ctx {:chat-id chat-id
+                    :db* db*
+                    :metrics metrics
+                    :messenger messenger}]
+      (tc/transition-tool-call! db* chat-ctx tool-call-id :user-approve
+                                {:reason {:code :user-choice-allow
+                                          :text "Tool call allowed by user choice"}})
+      (when (= "session" save)
+        (let [tool-call-name (get-in @db* [:chats chat-id :tool-calls tool-call-id :name])]
+          (swap! db* assoc-in [:tool-calls tool-call-name :remember-to-approve?] true))))))
 
 (defn tool-call-reject [{:keys [chat-id tool-call-id]} db* messenger metrics]
-  (let [chat-ctx {:chat-id chat-id
-                  :db* db*
-                  :metrics metrics
-                  :messenger messenger}]
-    (tc/transition-tool-call! db* chat-ctx tool-call-id :user-reject
-                              {:reason {:code :user-choice-deny
-                                        :text "Tool call rejected by user choice"}})))
+  (if-not (get-in @db* [:chats chat-id :tool-calls tool-call-id])
+    (logger/warn logger-tag "tool-call-reject ignored: unknown chat or tool-call"
+                 {:chat-id chat-id :tool-call-id tool-call-id})
+    (let [chat-ctx {:chat-id chat-id
+                    :db* db*
+                    :metrics metrics
+                    :messenger messenger}]
+      (tc/transition-tool-call! db* chat-ctx tool-call-id :user-reject
+                                {:reason {:code :user-choice-deny
+                                          :text "Tool call rejected by user choice"}}))))
 
 (defn query-context
   [{:keys [query contexts chat-id]}