anima-core 0.2.1 → 1.0.0

data/lib/tui/cable_client.rb

@@ -17,7 +17,7 @@ module TUI
   # heartbeat monitoring.
   #
   # @example
-  #   client = TUI::CableClient.new(host: "localhost:42134", session_id: 1)
+  #   client = TUI::CableClient.new(host: "localhost:42134")
   #   client.connect
   #   client.speak("Hello!")
   #   messages = client.drain_messages
@@ -31,23 +31,39 @@ module TUI
     BACKOFF_CAP = 30.0 # maximum backoff delay
     PING_STALE_THRESHOLD = 6.0 # seconds without ping before connection is stale
 
+    # Message types queued for the TUI render loop via @message_queue
+    MSG_TYPE_CONNECTION = "connection"
+
+    # Connection status values sent as MSG_TYPE_CONNECTION messages.
+    # These are message-level concepts for the TUI — distinct from the
+    # internal @status state machine (:disconnected, :connecting, etc.).
+    STATUS_SUBSCRIBING = "subscribing"
+    STATUS_SUBSCRIBED = "subscribed"
+    STATUS_REJECTED = "rejected"
+    STATUS_DISCONNECTED = "disconnected"
+    STATUS_RECONNECTING = "reconnecting"
+    STATUS_FAILED = "failed"
+
     # @return [String] brain server host:port
     attr_reader :host
 
     # @return [Integer] current session ID
     attr_reader :session_id
 
-    # @return [Symbol] connection status (:disconnected, :connecting, :connected, :subscribed, :reconnecting)
+    # @return [Symbol] connection status (:disconnected, :connecting, :connected, :subscribed, :reconnecting).
+    #   Note: the "subscribing" concept exists only as a message-level status
+    #   (see {STATUS_SUBSCRIBING}) queued for the TUI, not as an internal state.
     attr_reader :status
 
     # @return [Integer] current reconnection attempt (0 when connected)
     attr_reader :reconnect_attempt
 
     # @param host [String] brain server address (e.g. "localhost:42134")
-    # @param session_id [Integer] session to subscribe to
-    def initialize(host:, session_id:)
+    # @param session_id [Integer, nil] session to subscribe to (nil for server-side resolution)
+    def initialize(host:, session_id: nil)
       @host = host
       @session_id = session_id
+      @subscribed_session_id = session_id
       @status = :disconnected
       @message_queue = Thread::Queue.new
       @mutex = Mutex.new
@@ -110,6 +126,23 @@ module TUI
       send_action("change_view_mode", {"view_mode" => mode})
     end
 
+    # Requests the brain to recall (delete) a pending message so the user
+    # can edit it before the LLM sees it.
+    #
+    # @param event_id [Integer] database ID of the pending user_message event
+    def recall_pending(event_id)
+      send_action("recall_pending", {"event_id" => event_id})
+    end
+
+    # Sends an Anthropic subscription token to the brain for validation and storage.
+    # The token flows directly from TUI input to encrypted credentials — never
+    # enters the LLM context window.
+    #
+    # @param token [String] Anthropic subscription token (sk-ant-oat01-...)
+    def save_token(token)
+      send_action("save_token", {"token" => token})
+    end
+
     # Updates the local session ID reference after a server-side session switch.
     #
     # @param new_id [Integer] the new session ID
@@ -131,17 +164,6 @@ module TUI
       messages
     end
 
-    # Unsubscribes from the current session and subscribes to a new one.
-    #
-    # @deprecated Use {#create_session} or {#switch_session} instead.
-    #   The server now handles stream switching via the session protocol.
-    # @param new_session_id [Integer] session to switch to
-    def resubscribe(new_session_id)
-      unsubscribe_current
-      @mutex.synchronize { @session_id = new_session_id }
-      subscribe
-    end
-
     # Closes the WebSocket connection and cleans up the background thread.
     # Prevents automatic reconnection.
     def disconnect
@@ -264,8 +286,8 @@ module TUI
       if attempt > MAX_RECONNECT_ATTEMPTS
         @mutex.synchronize { @status = :disconnected }
         @message_queue << {
-          "type" => "connection",
-          "status" => "failed",
+          "type" => MSG_TYPE_CONNECTION,
+          "status" => STATUS_FAILED,
           "message" => "Reconnection failed after #{MAX_RECONNECT_ATTEMPTS} attempts"
         }
         return false
@@ -274,8 +296,8 @@ module TUI
       delay = backoff_delay(attempt)
       @mutex.synchronize { @status = :reconnecting }
       @message_queue << {
-        "type" => "connection",
-        "status" => "reconnecting",
+        "type" => MSG_TYPE_CONNECTION,
+        "status" => STATUS_RECONNECTING,
         "attempt" => attempt,
         "max_attempts" => MAX_RECONNECT_ATTEMPTS,
         "delay" => delay.round(1)
@@ -324,17 +346,17 @@ module TUI
           @status = :subscribed
           @reconnect_attempt = 0
         end
-        @message_queue << {"type" => "connection", "status" => "subscribed"}
+        @message_queue << {"type" => MSG_TYPE_CONNECTION, "status" => STATUS_SUBSCRIBED}
       when "reject_subscription"
         on_disconnected
-        @message_queue << {"type" => "connection", "status" => "rejected"}
+        @message_queue << {"type" => MSG_TYPE_CONNECTION, "status" => STATUS_REJECTED}
       when "disconnect"
         if data["reconnect"] == false
           @mutex.synchronize do
             @intentional_disconnect = true
             @status = :disconnected
           end
-          @message_queue << {"type" => "connection", "status" => "disconnected"}
+          @message_queue << {"type" => MSG_TYPE_CONNECTION, "status" => STATUS_DISCONNECTED}
         else
           on_disconnected
         end
@@ -353,30 +375,46 @@ module TUI
         return if @status == :disconnected || @status == :reconnecting
         @status = :disconnected
       end
-      @message_queue << {"type" => "connection", "status" => "disconnected"}
+      @message_queue << {"type" => MSG_TYPE_CONNECTION, "status" => STATUS_DISCONNECTED}
     end
 
+    # Captures the current session ID under mutex, queues a "subscribing"
+    # status for the TUI, then sends the Action Cable subscribe command.
+    #
+    # The "subscribing" message must be queued _before_ the subscribe command
+    # so the TUI clears stale state before history arrives. Action Cable
+    # transmits history (via +subscribed+ callback) before sending
+    # +confirm_subscription+, so the TUI would see history first, then
+    # the "subscribed" status.
+    #
+    # @see handle_protocol_message called on "welcome" to trigger this
     def subscribe
-      identifier = {channel: "SessionChannel", session_id: @session_id}.to_json
+      sid = @mutex.synchronize do
+        @subscribed_session_id = @session_id || 0
+      end
+      @message_queue << {"type" => MSG_TYPE_CONNECTION, "status" => STATUS_SUBSCRIBING}
+      identifier = {channel: "SessionChannel", session_id: sid}.to_json
       send_command("subscribe", identifier)
     end
 
-    def unsubscribe_current
-      identifier = {channel: "SessionChannel", session_id: @session_id}.to_json
-      send_command("unsubscribe", identifier)
-    end
-
     def send_action(action, data = {})
-      identifier = {channel: "SessionChannel", session_id: @session_id}.to_json
       payload = data.merge("action" => action).to_json
 
       @ws&.send({
         command: "message",
-        identifier: identifier,
+        identifier: subscription_identifier,
         data: payload
       }.to_json)
     end
 
+    # Returns the identifier matching the active ActionCable subscription.
+    # After session switches, @session_id changes but the subscription
+    # identifier must match the one used during subscribe.
+    def subscription_identifier
+      sid = @mutex.synchronize { @subscribed_session_id }
+      {channel: "SessionChannel", session_id: sid}.to_json
+    end
+
     def send_command(command, identifier)
       @ws&.send({
         command: command,

data/lib/tui/message_store.rb

@@ -6,8 +6,8 @@ module TUI
   # TUI, with no dependency on Rails or the Events module.
   #
   # Accepts Action Cable event payloads and stores typed entries:
-  # - `{type: :rendered, data:, event_type:}` for events with structured decorator output
-  # - `{type: :message, role:, content:}` for user/agent messages (fallback)
+  # - `{type: :rendered, data:, event_type:, id:}` for events with structured decorator output
+  # - `{type: :message, role:, content:, id:}` for user/agent messages (fallback)
   # - `{type: :tool_counter, calls:, responses:}` for tool activity
   #
   # Structured data takes priority when available. Events with nil
@@ -17,6 +17,9 @@ module TUI
   # Tool counters aggregate per agent turn: a new counter starts when a
   # tool_call arrives after a message entry. Consecutive tool events
   # increment the same counter until the next message breaks the chain.
+  #
+  # When an event arrives with `"action" => "update"` and a known `"id"`,
+  # the existing entry is replaced in-place, preserving display order.
   class MessageStore
     MESSAGE_TYPES = %w[user_message agent_message].freeze
 
@@ -27,6 +30,7 @@ module TUI
 
     def initialize
       @entries = []
+      @entries_by_id = {}
       @mutex = Mutex.new
     end
 
@@ -39,14 +43,23 @@ module TUI
     # Uses structured decorator data when available; falls back to
     # role/content extraction for messages and tool counter aggregation.
     #
+    # Events with `"action" => "update"` and a matching `"id"` replace
+    # the existing entry's data in-place rather than appending.
+    #
     # @param event_data [Hash] Action Cable event payload with "type", "content",
-    #   and optionally "rendered" (hash of mode => lines)
+    #   and optionally "rendered" (hash of mode => lines), "id", "action"
     # @return [Boolean] true if the event type was recognized and handled
     def process_event(event_data)
+      event_id = event_data["id"]
+
+      if event_data["action"] == "update" && event_id
+        return update_existing(event_data, event_id)
+      end
+
       rendered = extract_rendered(event_data)
 
       if rendered
-        record_rendered(rendered, event_type: event_data["type"])
+        record_rendered(rendered, event_type: event_data["type"], id: event_id)
       else
         case event_data["type"]
         when "tool_call" then record_tool_call
@@ -61,11 +74,87 @@ module TUI
     # to prepare for re-decorated viewport events from the server.
     # @return [void]
     def clear
-      @mutex.synchronize { @entries = [] }
+      @mutex.synchronize do
+        @entries = []
+        @entries_by_id = {}
+      end
+    end
+
+    # Returns the last pending user message for recall editing.
+    # Walks entries backwards and returns the first pending user_message found.
+    #
+    # @return [Hash, nil] `{id: Integer, content: String}` or nil if none pending
+    def last_pending_user_message
+      @mutex.synchronize do
+        @entries.reverse_each do |entry|
+          next unless entry[:event_type] == "user_message"
+
+          if entry[:type] == :rendered && entry.dig(:data, "status") == "pending"
+            return {id: entry[:id], content: entry.dig(:data, "content")}
+          end
+
+          # Only check the most recent user message
+          break
+        end
+        nil
+      end
+    end
+
+    # Removes an entry by its event ID. Used when a pending message is
+    # recalled for editing or deleted by another client.
+    #
+    # @param event_id [Integer] database ID of the event to remove
+    # @return [Boolean] true if the entry was found and removed
+    def remove_by_id(event_id)
+      @mutex.synchronize do
+        entry = @entries_by_id.delete(event_id)
+        return false unless entry
+
+        @entries.delete(entry)
+        true
+      end
+    end
+
+    # Removes entries by their event IDs. Used when the brain reports
+    # that events have left the LLM's viewport (context window eviction).
+    # Acquires the mutex once for the entire batch.
+    #
+    # @param event_ids [Array<Integer>] database IDs of events to remove
+    # @return [Integer] count of entries actually removed
+    def remove_by_ids(event_ids)
+      @mutex.synchronize do
+        removed = 0
+        event_ids.each do |event_id|
+          entry = @entries_by_id.delete(event_id)
+          next unless entry
+
+          @entries.delete(entry)
+          removed += 1
+        end
+        removed
+      end
     end
 
     private
 
+    # Replaces data on an existing entry matched by event ID.
+    # Only updates rendered entries — tool counters and plain messages
+    # are not individually addressable by ID.
+    #
+    # @return [Boolean] true if the entry was found and updated
+    def update_existing(event_data, event_id)
+      rendered = extract_rendered(event_data)
+      return false unless rendered
+
+      @mutex.synchronize do
+        entry = @entries_by_id[event_id]
+        return false unless entry
+
+        entry[:data] = rendered
+        true
+      end
+    end
+
     # Extracts the first non-nil structured data hash from the rendered payload.
     # The "rendered" hash is keyed by view mode — the server includes only the
     # session's current mode, so there is always at most one entry.
@@ -76,9 +165,11 @@ module TUI
       event_data.dig("rendered")&.values&.compact&.first
     end
 
-    def record_rendered(data, event_type: nil)
+    def record_rendered(data, event_type: nil, id: nil)
       @mutex.synchronize do
-        @entries << {type: :rendered, data: data, event_type: event_type}
+        entry = {type: :rendered, data: data, event_type: event_type, id: id}
+        @entries << entry
+        @entries_by_id[id] = entry if id
       end
       true
     end
@@ -107,8 +198,12 @@ module TUI
       content = event_data["content"]
       return false if content.nil?
 
+      event_id = event_data["id"]
+
       @mutex.synchronize do
-        @entries << {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content}
+        entry = {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content, id: event_id}
+        @entries << entry
+        @entries_by_id[event_id] = entry if event_id
       end
       true
     end