anima-core 1.1.3 → 1.3.0

data/lib/events/subscribers/persister.rb

@@ -3,12 +3,17 @@
 module Events
   module Subscribers
     # Persists all events to SQLite as they flow through the event bus.
-    # Each event is written as an Event record belonging to the active session.
+    # Each event is written as a Message record belonging to the active session.
     #
     # When initialized with a specific session, all events are saved to that
     # session. When initialized without one (global mode), the session is
     # looked up from the event's session_id payload field.
     #
+    # User messages are NOT persisted here — they are created directly by
+    # their callers ({SessionChannel#speak}, {AgentLoop#run}) so the
+    # message ID is available for bounce-back cleanup. Pending user
+    # messages live in the {PendingMessage} table, outside the event bus.
+    #
     # @example Session-scoped
     #   persister = Events::Subscribers::Persister.new(session)
     #   Events::Bus.subscribe(persister)
@@ -28,10 +33,10 @@ module Events
 
       # Receives a Rails.event notification hash and persists it.
       #
-      # Skips non-pending user messages — those are persisted by their
-      # callers ({SessionChannel#speak} for idle sessions,
-      # {AgentLoop#process} for direct usage). Also skips event types
-      # not in {Event::TYPES} (transient events like {Events::BounceBack}).
+      # Skips user messages — those are persisted by their callers
+      # ({SessionChannel#speak}, {AgentLoop#run}). Also skips event
+      # types not in {Message::TYPES} (transient events like
+      # {Events::BounceBack}).
       #
       # @param event [Hash] with :payload containing event data
       def emit(event)
@@ -40,19 +45,18 @@ module Events
 
         event_type = payload[:type]
         return if event_type.nil?
-        return unless Event::TYPES.include?(event_type)
-        return if persisted_by_job?(event_type, payload)
+        return unless Message::TYPES.include?(event_type)
+        return if event_type == "user_message"
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
 
         @mutex.synchronize do
-          target_session.events.create!(
-            event_type: event_type,
+          target_session.messages.create!(
+            message_type: event_type,
             payload: payload,
-            status: payload[:status],
             tool_use_id: payload[:tool_use_id],
-            timestamp: payload[:timestamp] || Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+            timestamp: payload[:timestamp] || Time.current.to_ns
           )
         end
       end
@@ -60,17 +64,6 @@ module Events
       def session=(new_session)
         @mutex.synchronize { @session = new_session }
       end
-
-      private
-
-      # Non-pending user messages are persisted by their callers
-      # ({SessionChannel#speak}, {AgentLoop#process}) so the event ID
-      # is available for bounce-back cleanup if LLM delivery fails.
-      # Pending messages are still auto-persisted here because they
-      # queue while the session is busy.
-      def persisted_by_job?(event_type, payload)
-        event_type == "user_message" && payload[:status] != Event::PENDING_STATUS
-      end
     end
   end
 end

data/lib/events/subscribers/subagent_message_router.rb

@@ -14,7 +14,8 @@ module Events
     #
     # **Parent → Child:** When a parent agent emits an {Events::AgentMessage}
     # containing `@name` mentions, the router persists the message in each
-    # matching child session and wakes them via {AgentRequestJob}.
+    # matching child session with a +[from parent]:+ origin label and wakes
+    # them via {AgentRequestJob}.
     #
     # Both directions delegate to {Session#enqueue_user_message}, which
     # respects the target session's processing state — persisting directly
@@ -25,9 +26,12 @@ module Events
     class SubagentMessageRouter
       include Events::Subscriber
 
-      # Attribution prefix format for messages routed from child to parent.
-      # @example "[sub-agent @loop-sleuth]: Here's what I found..."
-      ATTRIBUTION_FORMAT = "[sub-agent @%s]: %s"
+      # @see Tools::ResponseTruncator::ATTRIBUTION_FORMAT
+      ATTRIBUTION_FORMAT = Tools::ResponseTruncator::ATTRIBUTION_FORMAT
+
+      # Origin label for messages routed from parent agent to sub-agent.
+      # Lets the sub-agent distinguish delegated work from direct user input.
+      PARENT_ATTRIBUTION_FORMAT = "[from parent]: %s"
 
       # Regex to extract @mention names from parent agent messages.
       MENTION_PATTERN = /@(\w[\w-]*)/
@@ -64,7 +68,8 @@ module Events
       private
 
       # Forwards a sub-agent's text message to its parent session
-      # via {Session#enqueue_user_message}.
+      # via {Session#enqueue_user_message}. Truncates oversized messages
+      # to protect the parent's context window.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text
@@ -73,13 +78,18 @@ module Events
         return unless parent
 
         name = child.name || "agent-#{child.id}"
-        attributed = format(ATTRIBUTION_FORMAT, name, content)
+        truncated = Tools::ResponseTruncator.truncate(
+          content,
+          threshold: Anima::Settings.max_subagent_response_chars,
+          reason: "sub-agent output displays first/last #{Tools::ResponseTruncator::HEAD_LINES} lines"
+        )
+        attributed = format(ATTRIBUTION_FORMAT, name, truncated)
 
         parent.enqueue_user_message(attributed)
       end
 
       # Scans a parent agent's message for @mentions and routes the message
-      # to each mentioned child session.
+      # to each mentioned child session with origin attribution.
       #
       # @param parent [Session] the parent session
       # @param content [String] the parent agent's message text
@@ -90,11 +100,13 @@ module Events
         active_children = parent.child_sessions.where.not(name: nil).index_by(&:name)
         return if active_children.empty?
 
+        attributed = format(PARENT_ATTRIBUTION_FORMAT, content)
+
         mentioned_names.each do |name|
           child = active_children[name]
           next unless child
 
-          child.enqueue_user_message(content)
+          child.enqueue_user_message(attributed)
         end
       end
     end

data/lib/events/subscribers/transient_broadcaster.rb

@@ -3,8 +3,8 @@
 module Events
   module Subscribers
     # Bridges transient (non-persisted) events to ActionCable so clients
-    # receive them over WebSocket. Persisted events reach clients via
-    # {Event::Broadcasting} callbacks; this subscriber handles events
+    # receive them over WebSocket. Persisted messages reach clients via
+    # {Message::Broadcasting} callbacks; this subscriber handles events
     # that never touch the database.
     #
     # @example Registering at boot

data/lib/events/user_message.rb

@@ -4,25 +4,14 @@ module Events
   class UserMessage < Base
     TYPE = "user_message"
 
-    # @return [String, nil] "pending" when queued during active processing, nil otherwise
-    attr_reader :status
-
     # @param content [String] message text
     # @param session_id [Integer, nil] session identifier
-    # @param status [String, nil] "pending" when queued during active agent processing
-    def initialize(content:, session_id: nil, status: nil)
-      super(content: content, session_id: session_id)
-      @status = status
+    def initialize(content:, session_id: nil)
+      super
     end
 
     def type
       TYPE
     end
-
-    def to_h
-      h = super
-      h[:status] = status if status
-      h
-    end
   end
 end

data/lib/llm/client.rb

@@ -15,8 +15,8 @@ module LLM
   #   registry.register(Tools::WebGet)
   #   client.chat_with_tools(messages, registry: registry, session_id: session.id)
   class Client
-    # Synthetic tool_result message when a tool is skipped due to user interrupt.
-    INTERRUPT_MESSAGE = "Stopped by user"
+    # Synthetic tool_result when a tool is skipped because the human pressed Escape.
+    INTERRUPT_MESSAGE = "Your human wants your attention"
 
     # @return [Providers::Anthropic] the underlying API provider
     attr_reader :provider
@@ -65,7 +65,7 @@ module LLM
     # tool interaction so they're persisted and visible in the event stream.
     #
     # When the user interrupts via Escape, remaining tools receive synthetic
-    # "Stopped by user" results and the loop exits without another LLM call.
+    # "Your human wants your attention" results and the loop exits without another LLM call.
     #
     # @param messages [Array<Hash>] conversation messages in Anthropic format
     # @param registry [Tools::Registry] registered tools to make available
@@ -90,6 +90,7 @@ module LLM
         response = if first_response && rounds == 1
           first_response
         else
+          broadcast_session_state(session_id, "llm_generating")
           provider.create_message(
             model: model,
             messages: messages,
@@ -109,11 +110,14 @@ module LLM
             {role: "user", content: tool_results}
           ]
 
-          if interrupted?(session_id)
-            clear_interrupt!(session_id)
-            return nil
-          end
+          return nil if handle_interrupt!(session_id)
         else
+          # Discard the text response if the user pressed Escape while
+          # the API was generating it. Without this check the interrupt
+          # flag set during the blocking API call would be silently
+          # cleared by the ensure block in AgentRequestJob.
+          return nil if handle_interrupt!(session_id)
+
           return extract_text(response)
         end
       end
@@ -151,9 +155,12 @@ module LLM
     def execute_tools(response, registry, session_id)
       tool_uses = extract_tool_uses(response)
       results = []
+      interrupted = false
 
       tool_uses.each_with_index do |tool_use, index|
-        if interrupted?(session_id)
+        # Check-only here; clearing happens in handle_interrupt! after the loop
+        interrupted ||= interrupt_requested?(session_id)
+        if interrupted
           remaining = tool_uses[index..]
           results.concat(interrupt_remaining_tools(remaining, session_id)) if remaining&.any?
           break
@@ -164,7 +171,7 @@ module LLM
       results
     end
 
-    # Creates synthetic "Stopped by user" results for all tools in the list.
+    # Creates synthetic "Your human wants your attention" results for all tools in the list.
     #
     # @param tool_uses [Array<Hash>] remaining tool_use content blocks
     # @param session_id [Integer, String] session ID for events
@@ -188,6 +195,8 @@ module LLM
 
       log(:debug, "tool_call: #{name}(#{input.to_json})")
 
+      broadcast_session_state(session_id, "tool_executing", tool: name)
+
       Events::Bus.emit(Events::ToolCall.new(
         content: "Calling #{name}", tool_name: name,
         tool_input: input, tool_use_id: id, timeout: timeout,
@@ -197,6 +206,7 @@ module LLM
       result = registry.execute(name, input)
       result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
+      result_content = truncate_tool_result(result_content, registry, name)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
 
       Events::Bus.emit(Events::ToolResponse.new(
@@ -225,7 +235,7 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: error_content}
     end
 
-    # Creates a synthetic "Stopped by user" result for a tool that was not
+    # Creates a synthetic "Your human wants your attention" result for a tool that was not
     # executed due to user interrupt. Emits both ToolCall and ToolResponse
     # events so the TUI shows the interrupted tool in the event stream.
     #
@@ -238,7 +248,7 @@ module LLM
       input = tool_use["input"] || {}
 
       Events::Bus.emit(Events::ToolCall.new(
-        content: "Skipped #{name} (interrupted)", tool_name: name,
+        content: "Skipped #{name} — your human wants your attention", tool_name: name,
         tool_input: input, tool_use_id: id, session_id: session_id
       ))
 
@@ -250,22 +260,35 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: INTERRUPT_MESSAGE}
     end
 
-    # Checks the database for a pending interrupt flag on the session.
+    # Checks whether the session has a pending interrupt flag.
     #
     # @param session_id [Integer, String] session to check
-    # @return [Boolean] whether the session has a pending interrupt request
-    def interrupted?(session_id)
+    # @return [Boolean] true when interrupt is pending
+    def interrupt_requested?(session_id)
       Session.where(id: session_id, interrupt_requested: true).exists?
     end
 
-    # Clears the interrupt flag so the agent loop can continue with pending
-    # messages. Also cleared by {AgentRequestJob#clear_interrupt} as a safety
-    # net for unexpected exits.
+    # Atomically checks for a pending interrupt and clears it in one query.
+    # Used at loop boundaries (after tools, before LLM text return) to
+    # short-circuit the agent loop when the user presses Escape.
     #
-    # @param session_id [Integer, String] session to clear
+    # @param session_id [Integer, String] session to check
+    # @return [Boolean] true when interrupt was detected and cleared
+    def handle_interrupt!(session_id)
+      Session.where(id: session_id, interrupt_requested: true)
+        .update_all(interrupt_requested: false) > 0
+    end
+
+    # Broadcasts a session state transition to all subscribed clients.
+    # Delegates to {Session#broadcast_session_state} which handles both
+    # the session's own stream and the parent's stream for HUD updates.
+    #
+    # @param session_id [Integer, String] session to broadcast for
+    # @param state [String] one of "idle", "llm_generating", "tool_executing", "interrupting"
+    # @param tool [String, nil] tool name when state is "tool_executing"
     # @return [void]
-    def clear_interrupt!(session_id)
-      Session.where(id: session_id).update_all(interrupt_requested: false)
+    def broadcast_session_state(session_id, state, tool: nil)
+      Session.find_by(id: session_id)&.broadcast_session_state(state, tool: tool)
     end
 
     def log(level, message)
@@ -277,5 +300,16 @@ module LLM
     def format_tool_result(result)
       result.is_a?(Hash) ? result.to_json : result.to_s
     end
+
+    # Applies head+tail truncation when a tool result exceeds the tool's
+    # configured character threshold. Skips tools that opt out (e.g. read).
+    def truncate_tool_result(content, registry, tool_name)
+      threshold = registry.truncation_threshold(tool_name)
+      return content unless threshold
+
+      lines = Tools::ResponseTruncator::HEAD_LINES
+      reason = "#{tool_name} output displays first/last #{lines} lines"
+      Tools::ResponseTruncator.truncate(content, threshold: threshold, reason: reason)
+    end
   end
 end

data/lib/mcp/config.rb

@@ -6,7 +6,7 @@ require "toml-rb"
 module Mcp
   # Reads and writes MCP server configuration from a TOML file at
   # {DEFAULT_PATH}. Supports HTTP and stdio transports. Secrets stored
-  # in Rails encrypted credentials are interpolated via
+  # in the encrypted secrets table are interpolated via
   # +${credential:key_name}+ syntax in any string value.
   #
   # @example Config file format (~/.anima/mcp.toml)
@@ -187,7 +187,7 @@ module Mcp
     end
 
     # Replaces +${credential:key_name}+ placeholders with values from
-    # Rails encrypted credentials via {Mcp::Secrets}.
+    # the encrypted secrets table via {Mcp::Secrets}.
     #
     # @param value [String] string potentially containing placeholders
     # @return [String] interpolated string

data/lib/mcp/secrets.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 module Mcp
-  # CRUD operations for MCP server secrets stored in Rails encrypted credentials.
-  # Secrets live under the +mcp+ namespace in the credentials file:
+  # CRUD operations for MCP server secrets stored in the encrypted secrets table.
+  # Secrets live under the +mcp+ namespace:
   #
-  #   mcp:
-  #     linear_api_key: "sk-xxx"
-  #     mythonix_api_key: "Bearer tok-yyy"
+  #   Mcp::Secrets.set("linear_api_key", "sk-xxx")
+  #   Mcp::Secrets.get("linear_api_key") #=> "sk-xxx"
   #
   # Referenced in mcp.toml via +${credential:key_name}+ syntax, resolved at
   # runtime by {Mcp::Config#interpolate_credentials}.
@@ -23,7 +22,7 @@ module Mcp
     VALID_KEY_PATTERN = /\A\w+\z/
 
     class << self
-      # Stores a secret in encrypted credentials.
+      # Stores a secret in encrypted storage.
       #
       # @param key [String] secret identifier (e.g. "linear_api_key")
       # @param value [String] secret value
@@ -35,7 +34,7 @@ module Mcp
         CredentialStore.write(NAMESPACE, key => value)
       end
 
-      # Retrieves a secret from encrypted credentials.
+      # Retrieves a secret from encrypted storage.
       #
       # @param key [String] secret identifier
       # @return [String, nil] secret value or nil if not found
@@ -50,7 +49,7 @@ module Mcp
         CredentialStore.list(NAMESPACE)
       end
 
-      # Removes a secret from encrypted credentials.
+      # Removes a secret from encrypted storage.
       #
       # @param key [String] secret identifier to remove
       # @return [void]

data/lib/mneme/compressed_viewport.rb

@@ -7,16 +7,16 @@ module Mneme
   # aggregate counters like `[4 tools called]`.
   #
   # The viewport is split into three zones separated by delimiters:
-  # - **Eviction zone** — events about to leave the viewport (upper third)
-  # - **Middle zone** — events in the middle of the viewport
-  # - **Recent zone** — the most recent events (lower third)
+  # - **Eviction zone** — messages about to leave the viewport (upper third)
+  # - **Middle zone** — messages in the middle of the viewport
+  # - **Recent zone** — the most recent messages (lower third)
   #
   # Zone boundaries are calculated WITH tool call tokens (they affect
   # position), then tool calls are removed and replaced with counters.
   #
   # @example
   #   viewport = Mneme::CompressedViewport.new(session, token_budget: 60_000)
-  #   viewport.render  #=> "── EVICTION ZONE ──\nevent 42 User: ..."
+  #   viewport.render  #=> "── EVICTION ZONE ──\nmessage 42 User: ..."
   class CompressedViewport
     ZONE_DELIMITERS = {
       eviction: "── EVICTION ZONE (upper third) ──",
@@ -26,74 +26,74 @@ module Mneme
 
     # @param session [Session] the session to build viewport for
     # @param token_budget [Integer] total tokens available for Mneme's viewport
-    # @param from_event_id [Integer, nil] start from this event ID (inclusive);
+    # @param from_message_id [Integer, nil] start from this message ID (inclusive);
     #   when nil, uses the session's full viewport
-    def initialize(session, token_budget:, from_event_id: nil)
+    def initialize(session, token_budget:, from_message_id: nil)
       @session = session
       @token_budget = token_budget
-      @from_event_id = from_event_id
+      @from_message_id = from_message_id
     end
 
     # Renders the compressed viewport as a string ready for Mneme's LLM context.
     #
     # @return [String] compressed viewport with zone delimiters
     def render
-      return "" if events.empty?
+      return "" if messages.empty?
 
-      zones = split_into_zones(events)
+      zones = split_into_zones(messages)
       render_zones(zones)
     end
 
-    # @return [Array<Event>] the raw events selected for this viewport
-    def events
-      @events ||= fetch_events
+    # @return [Array<Message>] the raw messages selected for this viewport
+    def messages
+      @messages ||= fetch_messages
     end
 
     private
 
-    # Fetches events within token budget, starting from from_event_id.
+    # Fetches messages within token budget, starting from from_message_id.
     # Selects newest-first until budget exhausted, returns chronological.
-    # Caches per-event token costs in @event_costs for reuse by split_into_zones.
+    # Caches per-message token costs in @message_costs for reuse by split_into_zones.
     #
-    # @return [Array<Event>]
-    def fetch_events
-      scope = @session.events.context_events.deliverable
+    # @return [Array<Message>]
+    def fetch_messages
+      scope = @session.messages.context_messages
 
-      if @from_event_id
-        scope = scope.where("id >= ?", @from_event_id)
+      if @from_message_id
+        scope = scope.where("id >= ?", @from_message_id)
       end
 
       selected = []
-      @event_costs = {}
+      @message_costs = {}
       remaining = @token_budget
 
-      scope.reorder(id: :desc).each do |event|
-        cost = event_token_cost(event)
+      scope.reorder(id: :desc).each do |message|
+        cost = message_token_cost(message)
         break if cost > remaining && selected.any?
 
-        selected << event
-        @event_costs[event.id] = cost
+        selected << message
+        @message_costs[message.id] = cost
         remaining -= cost
       end
 
       selected.reverse
     end
 
-    # Splits events into three zones by token count.
-    # Zone boundaries are calculated including ALL events (tool calls count
+    # Splits messages into three zones by token count.
+    # Zone boundaries are calculated including ALL messages (tool calls count
     # toward position), but zone assignment uses cumulative tokens.
     #
-    # @return [Hash{Symbol => Array<Event>}] :eviction, :middle, :recent
-    def split_into_zones(events)
-      costs = events.map { |event| [event, @event_costs[event.id] || event_token_cost(event)] }
+    # @return [Hash{Symbol => Array<Message>}] :eviction, :middle, :recent
+    def split_into_zones(messages)
+      costs = messages.map { |message| [message, @message_costs[message.id] || message_token_cost(message)] }
       zone_size = costs.sum(&:last) / 3.0
 
       result = {eviction: [], middle: [], recent: []}
       cumulative = 0
 
-      costs.each do |event, cost|
+      costs.each do |message, cost|
         cumulative += cost
-        result[zone_for_cumulative(cumulative, zone_size)] << event
+        result[zone_for_cumulative(cumulative, zone_size)] << message
       end
 
       result
@@ -101,7 +101,7 @@ module Mneme
 
     # Renders zones with delimiters, compressing tool calls into counters.
     #
-    # @param zones [Hash{Symbol => Array<Event>}]
+    # @param zones [Hash{Symbol => Array<Message>}]
     # @return [String]
     def render_zones(zones)
       %i[eviction middle recent].flat_map { |name|
@@ -124,23 +124,23 @@ module Mneme
       end
     end
 
-    # Renders a single zone: conversation events as full text, consecutive
+    # Renders a single zone: conversation messages as full text, consecutive
     # tool calls/responses compressed into `[N tools called]` counters.
-    # tool_response events are intentionally silent — they affect zone boundaries
-    # via token cost but are not rendered; only tool_call events increment the counter.
+    # tool_response messages are intentionally silent — they affect zone boundaries
+    # via token cost but are not rendered; only tool_call messages increment the counter.
     #
-    # @param zone_events [Array<Event>]
+    # @param zone_messages [Array<Message>]
     # @return [String]
-    def render_zone(zone_events)
+    def render_zone(zone_messages)
       lines = []
       tool_count = 0
 
-      zone_events.each do |event|
-        if conversation_event?(event) || think_event?(event)
+      zone_messages.each do |message|
+        if conversation_message?(message) || think_message?(message)
           lines << flush_tool_count(tool_count)
           tool_count = 0
-          lines << render_event_line(event)
-        elsif event.event_type == "tool_call"
+          lines << render_message_line(message)
+        elsif message.message_type == "tool_call"
           tool_count += 1
         end
       end
@@ -149,17 +149,17 @@ module Mneme
       lines.compact.join("\n")
     end
 
-    # @return [Boolean] true if event is a user/agent/system message
-    def conversation_event?(event)
-      event.event_type.in?(Event::CONVERSATION_TYPES)
+    # @return [Boolean] true if message is a user/agent/system message
+    def conversation_message?(message)
+      message.message_type.in?(Message::CONVERSATION_TYPES)
     end
 
-    # Think events are tool_call events with tool_name == "think".
+    # Think messages are tool_call messages with tool_name == "think".
     # They carry the agent's reasoning and are treated as conversation.
     #
     # @return [Boolean]
-    def think_event?(event)
-      event.event_type == "tool_call" && event.payload["tool_name"] == Event::THINK_TOOL
+    def think_message?(message)
+      message.message_type == "tool_call" && message.payload["tool_name"] == Message::THINK_TOOL
     end
 
     ROLE_LABELS = {
@@ -168,17 +168,17 @@ module Mneme
       "system_message" => "System"
     }.freeze
 
-    # Renders a single event as a transcript line.
+    # Renders a single message as a transcript line.
     #
-    # @param event [Event]
+    # @param message [Message]
     # @return [String]
-    def render_event_line(event)
-      prefix = "event #{event.id}"
-      data = event.payload
-      if think_event?(event)
+    def render_message_line(message)
+      prefix = "message #{message.id}"
+      data = message.payload
+      if think_message?(message)
         "#{prefix} Think: #{data.dig("tool_input", "thoughts")}"
       else
-        "#{prefix} #{ROLE_LABELS.fetch(event.event_type)}: #{data["content"]}"
+        "#{prefix} #{ROLE_LABELS.fetch(message.message_type)}: #{data["content"]}"
       end
     end
 
@@ -192,9 +192,9 @@ module Mneme
     end
 
     # @return [Integer] token cost using cached count or heuristic
-    def event_token_cost(event)
-      cached = event.token_count
-      (cached > 0) ? cached : event.estimate_tokens
+    def message_token_cost(message)
+      cached = message.token_count
+      (cached > 0) ? cached : message.estimate_tokens
     end
   end
 end

data/lib/mneme/l2_runner.rb

@@ -110,22 +110,22 @@ module Mneme
     # @return [Array<Hash>] single-element messages array
     def build_messages(snapshots)
       content = snapshots.map.with_index(1) { |snap, idx|
-        "--- Snapshot #{idx} (events #{snap.from_event_id}..#{snap.to_event_id}) ---\n#{snap.text}"
+        "--- Snapshot #{idx} (messages #{snap.from_message_id}..#{snap.to_message_id}) ---\n#{snap.text}"
       }.join("\n\n")
 
       [{role: "user", content: "Compress these #{snapshots.size} Level 1 snapshots into a single Level 2 summary:\n\n#{content}"}]
     end
 
     # Builds the tool registry with L2 context for SaveSnapshot.
-    # The event range spans from the first L1's start to the last L1's end.
+    # The message range spans from the first L1's start to the last L1's end.
     #
     # @param snapshots [Array<Snapshot>]
     # @return [Tools::Registry]
     def build_registry(snapshots)
       registry = ::Tools::Registry.new(context: {
         main_session: @session,
-        from_event_id: snapshots.first.from_event_id,
-        to_event_id: snapshots.last.to_event_id,
+        from_message_id: snapshots.first.from_message_id,
+        to_message_id: snapshots.last.to_message_id,
         level: 2
       })
       TOOLS.each { |tool| registry.register(tool) }