anima-core 1.3.0 → 1.5.0

data/lib/tui/message_store.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "settings"
+
 module TUI
   # Thread-safe in-memory store for chat entries displayed in the TUI.
-  # Replaces {Events::Subscribers::MessageCollector} in the WebSocket-based
-  # TUI, with no dependency on Rails or the Events module.
+  # Holds the WebSocket-delivered view of the session's conversation with
+  # no dependency on Rails or the Events module.
   #
   # Accepts Action Cable message payloads and stores typed entries:
   # - `{type: :rendered, data:, message_type:, id:}` for messages with structured decorator output
@@ -40,6 +42,7 @@ module TUI
       @pending_by_id = {}
       @mutex = Mutex.new
       @version = 0
+      @token_economy = default_token_economy
     end
 
     # Monotonically increasing counter that bumps on every mutation.
@@ -60,6 +63,36 @@ module TUI
       @mutex.synchronize { @entries.size + @pending_entries.size }
     end
 
+    # Returns token economy data for HUD display.
+    #
+    # Token counts, rate limits, and cache hit rate reflect the most recent API
+    # call — accumulating them across a session produces values larger than the
+    # context window, which is meaningless. `call_count` and `cache_history`
+    # remain session-wide so the HUD can detect "any metrics yet?" and render
+    # the per-call sparkline.
+    #
+    # @return [Hash] token economy stats:
+    #   - :input_tokens [Integer] uncached input tokens from the latest call
+    #   - :output_tokens [Integer] output tokens from the latest call
+    #   - :cache_read_input_tokens [Integer] cached token reads from the latest call
+    #   - :cache_creation_input_tokens [Integer] cache writes from the latest call
+    #   - :call_count [Integer] number of API calls tracked this session
+    #   - :cache_hit_rate [Float] hit rate of the latest call (0.0-1.0)
+    #   - :rate_limits [Hash, nil] latest rate limit values from API
+    #   - :cache_history [Array<Float>] per-call hit rates for the sparkline
+    def token_economy
+      @mutex.synchronize do
+        stats = @token_economy.dup
+        total_input = stats[:input_tokens] + stats[:cache_read_input_tokens] + stats[:cache_creation_input_tokens]
+        stats[:cache_hit_rate] = if total_input > 0
+          stats[:cache_read_input_tokens].to_f / total_input
+        else
+          0.0
+        end
+        stats
+      end
+    end
+
     # Processes a raw event payload from the WebSocket channel.
     # Uses structured decorator data when available; falls back to
     # role/content extraction for messages and tool counter aggregation.
@@ -67,12 +100,20 @@ module TUI
     # Events with `"action" => "update"` and a matching `"id"` replace
     # the existing entry's data in-place rather than appending.
     #
+    # Extracts api_metrics when present and records the latest call's
+    # token economy data for the HUD.
+    #
     # @param event_data [Hash] Action Cable event payload with "type", "content",
-    #   and optionally "rendered" (hash of mode => lines), "id", "action"
+    #   and optionally "rendered" (hash of mode => lines), "id", "action", "api_metrics"
     # @return [Boolean] true if the event type was recognized and handled
     def process_event(event_data)
       message_id = event_data["id"]
 
+      # Track API metrics for token economy HUD (only on create, not update)
+      if event_data["action"] != "update"
+        track_api_metrics(event_data["api_metrics"])
+      end
+
       if event_data["action"] == "update" && message_id
         return update_existing(event_data, message_id)
       end
@@ -93,6 +134,7 @@ module TUI
 
     # Removes all entries. Called on view mode change and session switch
     # to prepare for re-decorated viewport messages from the server.
+    # Resets token economy totals since we're starting fresh.
     # @return [void]
     def clear
       @mutex.synchronize do
@@ -100,28 +142,44 @@ module TUI
         @entries_by_id = {}
         @pending_entries = []
         @pending_by_id = {}
+        @token_economy = default_token_economy
         @version += 1
       end
     end
 
-    # Adds a pending message to the separate pending list.
+    # Adds a pending message to the separate pending list, or removes any
+    # existing entry when the decorator hides the PM in the current view
+    # mode (rendered hash present but its sole value is nil).
+    #
+    # Accepts the full +pending_message_created+ event payload. Falls back
+    # to a dimmed user-message envelope when no +rendered+ key is present
+    # (legacy producers, simple test fixtures).
+    #
     # Pending messages always render after real messages.
     #
     # @param pending_message_id [Integer] PendingMessage database ID
-    # @param content [String] message text
+    # @param payload [Hash] event payload with "content", "message_type",
+    #   and optionally "rendered" (hash of mode => decorator output)
     # @return [void]
-    def add_pending(pending_message_id, content)
+    def add_pending(pending_message_id, payload)
+      data = pending_entry_data(payload)
+      message_type = payload["message_type"] || "user_message"
+
       @mutex.synchronize do
-        entry = {
-          type: :rendered,
-          data: {"role" => "user", "content" => content, "status" => "pending"},
-          message_type: "user_message",
-          pending_message_id: pending_message_id
-        }
-        old = @pending_by_id[pending_message_id]
+        old = @pending_by_id.delete(pending_message_id)
         @pending_entries.delete(old) if old
-        @pending_entries << entry
-        @pending_by_id[pending_message_id] = entry
+
+        if data
+          entry = {
+            type: :rendered,
+            data: data,
+            message_type: message_type,
+            pending_message_id: pending_message_id
+          }
+          @pending_entries << entry
+          @pending_by_id[pending_message_id] = entry
+        end
+
         @version += 1
       end
     end
@@ -169,24 +227,21 @@ module TUI
       end
     end
 
-    # Removes entries by their message IDs. Used when the brain reports
-    # that messages have left the LLM's viewport (context window eviction).
-    # Acquires the mutex once for the entire batch.
+    # Removes all entries with message ID <= cutoff. Used when Mneme
+    # evicts messages above the cutoff in the chat view (older messages
+    # at the top with smaller IDs).
     #
-    # @param message_ids [Array<Integer>] database IDs of messages to remove
+    # @param cutoff_id [Integer] last evicted message ID
     # @return [Integer] count of entries actually removed
-    def remove_by_ids(message_ids)
+    def remove_above(cutoff_id)
       @mutex.synchronize do
-        removed = 0
-        message_ids.each do |message_id|
-          entry = @entries_by_id.delete(message_id)
-          next unless entry
-
+        evicted = @entries.select { |e| e[:id] && e[:id] <= cutoff_id }
+        evicted.each do |entry|
           @entries.delete(entry)
-          removed += 1
+          @entries_by_id.delete(entry[:id])
         end
-        @version += 1 if removed > 0
-        removed
+        @version += 1 if evicted.any?
+        evicted.size
       end
     end
 
@@ -211,6 +266,33 @@ module TUI
       end
     end
 
+    # Builds the +data+ hash for a pending entry. Returns nil when the
+    # decorator hid the PM (the +rendered+ key is present but its sole
+    # value is nil), so the caller can treat that as a removal. Falls
+    # back to a dimmed user-message envelope when no +rendered+ key is
+    # present at all (legacy callers, fixtures).
+    #
+    # The decorator's hash already carries its own +"status" => "pending"+
+    # marker; the symbolized form is converted here so the TUI's lookup
+    # via +data["status"]+ remains uniform.
+    def pending_entry_data(payload)
+      if payload.key?("rendered")
+        values = payload["rendered"]&.values&.compact
+        return nil if values.nil? || values.empty?
+
+        normalize_pending_data(values.first)
+      else
+        {"role" => "user", "content" => payload["content"], "status" => "pending"}
+      end
+    end
+
+    # Symbol/string keys arrive interchangeably from decorators that build
+    # hash literals server-side. Normalize keys to strings so chat.rb's
+    # +data["role"]+ / +data["status"]+ lookups always hit.
+    def normalize_pending_data(rendered)
+      rendered.transform_keys(&:to_s)
+    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.
@@ -346,5 +428,60 @@ module TUI
       last = @entries.last
       last if last&.dig(:type) == :tool_counter
     end
+
+    # Default token economy state for initialization and reset.
+    # @return [Hash]
+    def default_token_economy
+      {
+        input_tokens: 0,
+        output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        call_count: 0,
+        rate_limits: nil,
+        cache_history: []
+      }
+    end
+
+    # Records API metrics from the most recent message.
+    #
+    # Token counts and rate limits are last-wins (per-request semantics);
+    # `call_count` increments and `cache_history` appends so the HUD can
+    # show a sparkline of per-call hit rates.
+    #
+    # @param api_metrics [Hash, nil] metrics from API response with "usage" and "rate_limits"
+    # @return [void]
+    def track_api_metrics(api_metrics)
+      return unless api_metrics.is_a?(Hash)
+
+      @mutex.synchronize do
+        usage = api_metrics["usage"]
+        if usage.is_a?(Hash)
+          input = usage["input_tokens"].to_i
+          cache_read = usage["cache_read_input_tokens"].to_i
+          cache_create = usage["cache_creation_input_tokens"].to_i
+
+          @token_economy[:input_tokens] = input
+          @token_economy[:output_tokens] = usage["output_tokens"].to_i
+          @token_economy[:cache_read_input_tokens] = cache_read
+          @token_economy[:cache_creation_input_tokens] = cache_create
+          @token_economy[:call_count] += 1
+
+          # Per-call cache hit rate for sparkline graph
+          total = input + cache_read + cache_create
+          hit_rate = (total > 0) ? cache_read.to_f / total : 0.0
+          history = @token_economy[:cache_history]
+          history.shift if history.size >= Settings.message_store_max_cache_history
+          history << hit_rate
+        end
+
+        rate_limits = api_metrics["rate_limits"]
+        if rate_limits.is_a?(Hash)
+          @token_economy[:rate_limits] = rate_limits
+        end
+
+        @version += 1
+      end
+    end
   end
 end

data/lib/tui/performance_logger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require_relative "settings"
 
 module TUI
   # Frame-level performance logger for TUI render profiling.
@@ -18,8 +19,6 @@ module TUI
   #   logger.measure(:line_count) { widget.line_count(width) }
   #   logger.end_frame
   class PerformanceLogger
-    LOG_PATH = "log/tui_performance.log"
-
     # @param enabled [Boolean] whether to actually log (no-op when false)
     def initialize(enabled: false)
       @enabled = enabled
@@ -30,7 +29,7 @@ module TUI
 
       return unless @enabled
 
-      @logger = Logger.new(LOG_PATH, 1, 5 * 1024 * 1024) # 5MB rotation
+      @logger = Logger.new(Settings.performance_log_path, 1, 5 * 1024 * 1024) # 5MB rotation
       @logger.formatter = proc { |_sev, time, _prog, msg| "#{time.strftime("%H:%M:%S.%L")} #{msg}\n" }
       @logger.info("TUI Performance Logger started — pid=#{Process.pid}")
     end