Add message flags — named checkpoints for resuming and forking chats

- New "flag" message role stored in the chat messages vector
- chat/addFlag request: inserts a flag after any message type
  (matches both contentId and content.id fields)
- chat/removeFlag request: removes a flag by contentId
- chat/fork request: forks chat up to a given contentId
- Flags filtered from LLM context in messages-after-last-compact-marker
- /resume listing shows 🚩 with flag names for labeled chats
- Protocol docs for ChatFlagContent, chat/addFlag, chat/removeFlag, chat/fork

Closes #395

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

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

Author: ericdallo

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Add `chatRetentionDays` config to control chat and cache cleanup retention period, default changed from 7 to 14 days. Set to 0 to disable cleanup. #393
 - Preserve full chat history across compactions using tombstone markers instead of replacing messages. #394
+- Add message flags — named checkpoints for resuming and forking chats. #395
 
 ## 0.123.3
 

docs/protocol.md

@@ -589,7 +589,8 @@ type ChatContent =
     | ChatToolCallRunningContent
     | ChatToolCalledContent
     | ChatToolCallRejectedContent
-    | ChatMetadataContent;
+    | ChatMetadataContent
+    | ChatFlagContent;
 
 /**
  * Simple text message from the LLM
@@ -1192,6 +1193,25 @@ interface ChatMetadataContent {
     title: string;
 }
 
+/**
+ * A named checkpoint flag in the chat history.
+ * Flags act as bookmarks that survive across sessions
+ * and are discoverable via timeline.
+ */
+interface ChatFlagContent {
+    type: 'flag';
+
+    /**
+     * The flag display text.
+     */
+    text: string;
+
+    /**
+     * Unique identifier for this flag.
+     */
+    contentId: string;
+}
+
 ```
 
 ### Chat approve tool call (➡️)
@@ -1512,6 +1532,107 @@ _Response:_
 interface ChatClearResponse {}
 ```
 
+### Chat add flag (➡️)
+
+A client request to add a named flag (checkpoint) to the chat history.
+The flag is inserted after the message identified by the given `contentId`.
+The `contentId` matches against both message-level `contentId` (user messages) and
+content `id` fields (tool calls, reasons, etc), allowing placement between any message types.
+Flags are persisted as messages and propagate automatically with fork and resume.
+
+_Request:_
+
+* method: `chat/addFlag`
+* params: `ChatAddFlagParams` defined as follows:
+
+```typescript
+interface ChatAddFlagParams {
+    /**
+     * The chat session identifier.
+     */
+    chatId: string;
+
+    /**
+     * The id of the message after which the flag is inserted.
+     * Matches against message contentId or content.id fields.
+     */
+    contentId: string;
+
+    /**
+     * The flag display text.
+     */
+    text: string;
+}
+```
+
+_Response:_
+
+```typescript
+interface ChatAddFlagResponse {}
+```
+
+### Chat remove flag (➡️)
+
+A client request to remove a flag from the chat history.
+The client is responsible for removing the flag from the UI after a successful response.
+
+_Request:_
+
+* method: `chat/removeFlag`
+* params: `ChatRemoveFlagParams` defined as follows:
+
+```typescript
+interface ChatRemoveFlagParams {
+    /**
+     * The chat session identifier.
+     */
+    chatId: string;
+
+    /**
+     * The content id of the flag to remove.
+     */
+    contentId: string;
+}
+```
+
+_Response:_
+
+```typescript
+interface ChatRemoveFlagResponse {}
+```
+
+### Chat fork (➡️)
+
+A client request to fork the chat into a new chat with messages up to and including
+the message identified by the given `contentId`. The server creates the new chat,
+sends a `chat/opened` notification with the new chat, then streams the kept messages
+via `chat/contentReceived`. A system message is also sent to the original chat.
+
+_Request:_
+
+* method: `chat/fork`
+* params: `ChatForkParams` defined as follows:
+
+```typescript
+interface ChatForkParams {
+    /**
+     * The chat session identifier of the source chat.
+     */
+    chatId: string;
+
+    /**
+     * The content id of the message up to which to fork (inclusive).
+     */
+    contentId: string;
+}
+```
+
+_Response:_
+
+```typescript
+interface ChatForkResponse {}
+```
+
 ### Chat cleared (⬅️)
 
 A server notification to clear a chat UI, currently supporting removing only messages of the chat.

src/eca/db.clj

@@ -57,7 +57,7 @@
                         :status (or :idle :running :stopping :login)
                         :created-at :number
                         :login-provider :string
-                        :messages [{:role (or "user" "assistant" "tool_call" "tool_call_output" "reason" "compact_marker" "server_tool_use" "server_tool_result")
+                        :messages [{:role (or "user" "assistant" "tool_call" "tool_call_output" "reason" "compact_marker" "flag" "server_tool_use" "server_tool_result")
                                     :content (or :string [::any-map]) ;; string for simple text, map/vector for structured content
                                     :content-id :string}]
                         :task {:next-id :number

src/eca/features/chat.clj

@@ -201,7 +201,11 @@
                        :content {:type :text
                                  :text (if (:auto? message-content)
                                          "── Chat auto-compacted ──"
-                                         "── Chat compacted ──")}}]))
+                                         "── Chat compacted ──")}}]
+    "flag" [{:role :system
+             :content {:type :flag
+                       :text (:text message-content)
+                       :contentId content-id}}]))
 
 (defn ^:private send-chat-contents! [messages chat-ctx]
   (doseq [message messages]
@@ -1169,3 +1173,80 @@
         :db* db*
         :messenger messenger}))
     {}))
+
+(defn ^:private find-last-message-idx
+  "Find the last message index matching content-id by checking both
+   :content-id (user messages) and [:content :id] (tool calls, etc)."
+  [messages content-id]
+  (loop [i (dec (count messages))]
+    (cond
+      (neg? i) nil
+      (let [msg (messages i)]
+        (or (= content-id (:content-id msg))
+            (= content-id (get-in msg [:content :id])))) i
+      :else (recur (dec i)))))
+
+(defn add-flag
+  "Add a named flag after the message identified by content-id.
+   Searches both :content-id and [:content :id] to support placement
+   after any message type (user, tool call, reason, etc).
+   Clears and replays the chat to render the flag at the correct position."
+  [{:keys [chat-id content-id text]} db* messenger metrics]
+  (let [messages (vec (get-in @db* [:chats chat-id :messages]))
+        insert-idx (find-last-message-idx messages content-id)]
+    (when insert-idx
+      (let [flag-id (str (random-uuid))
+            flag-msg {:role "flag" :content {:text text} :content-id flag-id}
+            insert-after (inc insert-idx)
+            new-messages (into (subvec messages 0 insert-after)
+                               (cons flag-msg (subvec messages insert-after)))]
+        (swap! db* assoc-in [:chats chat-id :messages] new-messages)
+        (db/update-workspaces-cache! @db* metrics)
+        (messenger/chat-cleared messenger {:chat-id chat-id :messages true})
+        (send-chat-contents! new-messages {:chat-id chat-id :db* db* :messenger messenger})))
+    {}))
+
+(defn remove-flag
+  "Remove a flag message identified by content-id from the chat."
+  [{:keys [chat-id content-id]} db* metrics]
+  (when-let [messages (get-in @db* [:chats chat-id :messages])]
+    (let [new-messages (vec (remove #(and (= "flag" (:role %))
+                                          (= content-id (:content-id %)))
+                                    messages))]
+      (when (not= (count new-messages) (count messages))
+        (swap! db* assoc-in [:chats chat-id :messages] new-messages)
+        (db/update-workspaces-cache! @db* metrics))))
+  {})
+
+(defn fork-chat
+  "Fork the chat creating a new chat with messages up to and including
+   the message identified by content-id."
+  [{:keys [chat-id content-id]} db* messenger metrics]
+  (let [chat (get-in @db* [:chats chat-id])
+        messages (vec (:messages chat))
+        target-idx (find-last-message-idx messages content-id)]
+    (when target-idx
+      (let [new-id (str (random-uuid))
+            now (System/currentTimeMillis)
+            new-title (f.commands/fork-title (:title chat))
+            kept-messages (subvec messages 0 (inc target-idx))
+            new-chat {:id new-id
+                      :title new-title
+                      :status :idle
+                      :created-at now
+                      :updated-at now
+                      :model (:model chat)
+                      :last-api (:last-api chat)
+                      :messages kept-messages
+                      :prompt-finished? true}]
+        (swap! db* assoc-in [:chats new-id] new-chat)
+        (db/update-workspaces-cache! @db* metrics)
+        (messenger/chat-opened messenger {:chat-id new-id :title new-title})
+        (send-chat-contents! kept-messages {:chat-id new-id :db* db* :messenger messenger})
+        (lifecycle/send-content! {:messenger messenger :chat-id new-id}
+                                 :system
+                                 (assoc-some {:type :metadata} :title new-title))
+        (lifecycle/send-content! {:messenger messenger :chat-id chat-id}
+                                 :system
+                                 {:type :text :text (str "Chat forked to: " new-title)})))
+    {}))

src/eca/features/commands.clj

@@ -25,7 +25,7 @@
 
 (set! *warn-on-reflection* true)
 
-(defn ^:private fork-title [title]
+(defn fork-title [title]
   (let [title (or title "Untitled")]
     (if-let [[_ base n] (re-matches #"(.+?)\s*\((\d+)\)\s*$" title)]
       (str base " (" (inc (parse-long n)) ")")
@@ -389,12 +389,18 @@
                                       (fn [s chat-id]
                                         (let [chat (get chats chat-id)
                                               msgs-count (count (filter #(= "user" (:role %))
-                                                                        (:messages chat)))]
+                                                                        (:messages chat)))
+                                              flags (->> (:messages chat)
+                                                         (filter #(= "flag" (:role %)))
+                                                         (map #(get-in % [:content :text])))]
                                           (if (> msgs-count 0)
-                                            (str s (format "%s - %s - %s\n"
+                                            (str s (format "%s - %s - %s%s\n"
                                                            (inc (.indexOf ^PersistentVector chats-ids chat-id))
                                                            (shared/ms->presentable-date (:created-at chat) "dd/MM/yyyy HH:mm")
-                                                           (or (:title chat) (format "No chat title (%s user messages)" msgs-count))))
+                                                           (or (:title chat) (format "No chat title (%s user messages)" msgs-count))
+                                                           (if (seq flags)
+                                                             (str " 🚩 " (string/join ", " flags))
+                                                             "")))
                                             s)))
                                       ""
                                       chats-ids)

src/eca/handlers.clj

@@ -226,6 +226,18 @@
   (metrics/task metrics :eca/chat-rollback
     (f.chat/rollback-chat params db* messenger)))
 
+(defn chat-add-flag [{:keys [db* metrics messenger]} params]
+  (metrics/task metrics :eca/chat-add-flag
+    (f.chat/add-flag params db* messenger metrics)))
+
+(defn chat-remove-flag [{:keys [db* metrics]} params]
+  (metrics/task metrics :eca/chat-remove-flag
+    (f.chat/remove-flag params db* metrics)))
+
+(defn chat-fork [{:keys [db* metrics messenger]} params]
+  (metrics/task metrics :eca/chat-fork
+    (f.chat/fork-chat params db* messenger metrics)))
+
 (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)))

src/eca/server.clj

@@ -106,6 +106,15 @@
 (defmethod jsonrpc.server/receive-request "chat/rollback" [_ components params]
   (eventually (handlers/chat-rollback (with-config components) params)))
 
+(defmethod jsonrpc.server/receive-request "chat/addFlag" [_ components params]
+  (eventually (handlers/chat-add-flag (with-config components) params)))
+
+(defmethod jsonrpc.server/receive-request "chat/removeFlag" [_ components params]
+  (eventually (handlers/chat-remove-flag (with-config components) params)))
+
+(defmethod jsonrpc.server/receive-request "chat/fork" [_ components params]
+  (eventually (handlers/chat-fork (with-config components) params)))
+
 (defmethod jsonrpc.server/receive-notification "mcp/stopServer" [_ components params]
   (async-notify (handlers/mcp-stop-server (with-config components) params)))
 

src/eca/shared.clj

@@ -316,6 +316,7 @@
 
 (defn messages-after-last-compact-marker
   "Returns messages after the last compact_marker, or all messages if none exists.
+   Filters out flag messages which are UI-only markers not meant for the LLM.
    Scans from the end for efficiency since markers are typically near the tail."
   [messages]
   (let [messages (vec messages)
@@ -324,10 +325,11 @@
                    (cond
                      (neg? i) -1
                      (= "compact_marker" (:role (messages i))) i
-                     :else (recur (dec i))))]
-    (if (neg? last-idx)
-      messages
-      (subvec messages (inc last-idx)))))
+                     :else (recur (dec i))))
+        result (if (neg? last-idx)
+                 messages
+                 (subvec messages (inc last-idx)))]
+    (vec (remove #(= "flag" (:role %)) result))))
 
 (defn compact-side-effect!
   "Performs side effects after chat compaction: appends a compact_marker tombstone