anima-core 1.0.2 → 1.1.0

data/lib/events/bounce_back.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Events
+  # Transient failure event emitted when LLM delivery fails inside the
+  # Bounce Back transaction. The user event record is rolled back, and
+  # this event notifies clients to remove the phantom message and
+  # restore the text to the input field.
+  #
+  # Not persisted — not included in {Event::TYPES}.
+  class BounceBack < Base
+    TYPE = "bounce_back"
+
+    # @return [String] human-readable error description
+    attr_reader :error
+
+    # @return [Integer, nil] database ID of the rolled-back event (for client-side removal)
+    attr_reader :event_id
+
+    # @param content [String] original user message text to restore to input
+    # @param error [String] error description for the flash message
+    # @param session_id [Integer] session the message was intended for
+    # @param event_id [Integer, nil] ID of the event that was broadcast optimistically
+    def initialize(content:, error:, session_id:, event_id: nil)
+      super(content: content, session_id: session_id)
+      @error = error
+      @event_id = event_id
+    end
+
+    def type
+      TYPE
+    end
+
+    def to_h
+      super.merge(error: error, event_id: event_id)
+    end
+  end
+end

data/lib/events/subscribers/agent_dispatcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Reacts to non-pending {Events::UserMessage} emissions by scheduling
+    # {AgentRequestJob}. This is the event-driven bridge between the
+    # channel (which emits the intent) and the job (which persists and
+    # delivers the message).
+    #
+    # Pending messages are skipped — they are picked up by the running
+    # agent loop after it finishes the current turn.
+    class AgentDispatcher
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+        return unless payload[:type] == "user_message"
+        return if payload[:status] == Event::PENDING_STATUS
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        AgentRequestJob.perform_later(session_id, content: payload[:content])
+      end
+    end
+  end
+end

data/lib/events/subscribers/persister.rb

@@ -27,6 +27,12 @@ module Events
       end
 
       # Receives a Rails.event notification hash and persists it.
+      #
+      # Skips non-pending user messages — those are persisted by
+      # {AgentRequestJob} inside a transaction with LLM delivery
+      # (Bounce Back, #236). Also skips event types not in {Event::TYPES}
+      # (transient events like {Events::BounceBack}).
+      #
       # @param event [Hash] with :payload containing event data
       def emit(event)
         payload = event[:payload]
@@ -34,6 +40,8 @@ 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)
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
@@ -52,6 +60,15 @@ module Events
       def session=(new_session)
         @mutex.synchronize { @session = new_session }
       end
+
+      private
+
+      # Non-pending user messages are persisted by {AgentRequestJob} inside
+      # a transaction with LLM delivery. 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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Routes text messages between parent and child sessions, enabling
+    # bidirectional @mention communication.
+    #
+    # **Child → Parent:** When a sub-agent emits an {Events::AgentMessage},
+    # the router persists a {Events::UserMessage} in the parent session
+    # with attribution prefix, then wakes the parent via {AgentRequestJob}.
+    #
+    # **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}.
+    #
+    # Both directions use direct persistence + job enqueue (same pattern as
+    # {Tools::SpawnSubagent#spawn_child}) to avoid conflicts with the global
+    # {Persister} which skips non-pending user messages.
+    #
+    # This replaces the +return_result+ tool — sub-agents communicate
+    # through natural text messages instead of structured tool calls.
+    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"
+
+      # Regex to extract @mention names from parent agent messages.
+      MENTION_PATTERN = /@(\w[\w-]*)/
+
+      # Routes agent text messages between parent and child sessions.
+      #
+      # For sub-agent sessions: forwards to parent with attribution prefix.
+      # For parent sessions: scans for @mentions and routes to matching children.
+      #
+      # @param event [Hash] Rails.event notification hash with +:payload+ containing
+      #   an +agent_message+ event (type, session_id, content)
+      # @return [void]
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+        return unless payload[:type] == "agent_message"
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        content = payload[:content].to_s
+        return if content.empty?
+
+        session = Session.find_by(id: session_id)
+        return unless session
+
+        if session.sub_agent?
+          route_to_parent(session, content)
+        else
+          route_mentions_to_children(session, content)
+        end
+      end
+
+      private
+
+      # Forwards a sub-agent's text message to its parent session.
+      # Persists directly and enqueues a job so the parent agent wakes
+      # up to process the message.
+      #
+      # @param child [Session] the sub-agent session
+      # @param content [String] the sub-agent's message text
+      def route_to_parent(child, content)
+        parent = child.parent_session
+        return unless parent
+
+        name = child.name || "agent-#{child.id}"
+        attributed = format(ATTRIBUTION_FORMAT, name, content)
+
+        parent.create_user_event(attributed)
+        AgentRequestJob.perform_later(parent.id)
+      end
+
+      # Scans a parent agent's message for @mentions and routes the message
+      # to each mentioned child session.
+      #
+      # @param parent [Session] the parent session
+      # @param content [String] the parent agent's message text
+      def route_mentions_to_children(parent, content)
+        mentioned_names = content.scan(MENTION_PATTERN).flatten.uniq
+        return if mentioned_names.empty?
+
+        active_children = parent.child_sessions.where.not(name: nil).index_by(&:name)
+        return if active_children.empty?
+
+        mentioned_names.each do |name|
+          child = active_children[name]
+          next unless child
+
+          child.create_user_event(content)
+          AgentRequestJob.perform_later(child.id)
+        end
+      end
+    end
+  end
+end

data/lib/events/subscribers/transient_broadcaster.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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
+    # that never touch the database.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::TransientBroadcaster.new)
+    class TransientBroadcaster
+      include Events::Subscriber
+
+      # Event types that are broadcast without persistence.
+      TRANSIENT_TYPES = [Events::BounceBack::TYPE].freeze
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+
+        event_type = payload[:type]
+        return unless TRANSIENT_TYPES.include?(event_type)
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        ActionCable.server.broadcast(
+          "session_#{session_id}",
+          payload.transform_keys(&:to_s)
+        )
+      end
+    end
+  end
+end

data/lib/llm/client.rb

@@ -70,10 +70,13 @@ module LLM
     # @param messages [Array<Hash>] conversation messages in Anthropic format
     # @param registry [Tools::Registry] registered tools to make available
     # @param session_id [Integer, String] session ID for emitted events
+    # @param first_response [Hash, nil] pre-fetched first API response from
+    #   {AgentLoop#deliver!}. Skips the first API call when provided so
+    #   the Bounce Back transaction doesn't duplicate work.
     # @param options [Hash] additional API parameters (e.g. +system:+)
     # @return [String, nil] the assistant's final text response, or nil when interrupted
     # @raise [Providers::Anthropic::Error] on API errors
-    def chat_with_tools(messages, registry:, session_id:, **options)
+    def chat_with_tools(messages, registry:, session_id:, first_response: nil, **options)
       messages = messages.dup
       rounds = 0
 
@@ -84,13 +87,17 @@ module LLM
           return "[Tool loop exceeded #{max_rounds} rounds — halting]"
         end
 
-        response = provider.create_message(
-          model: model,
-          messages: messages,
-          max_tokens: max_tokens,
-          tools: registry.schemas,
-          **options
-        )
+        response = if first_response && rounds == 1
+          first_response
+        else
+          provider.create_message(
+            model: model,
+            messages: messages,
+            max_tokens: max_tokens,
+            tools: registry.schemas,
+            **options
+          )
+        end
 
         log(:debug, "stop_reason=#{response["stop_reason"]} content_types=#{(response["content"] || []).map { |b| b["type"] }.join(",")}")
 
@@ -189,6 +196,7 @@ module LLM
         {error: "#{error.class}: #{error.message}"}
       end
 
+      result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
 

data/lib/mneme/compressed_viewport.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Mneme
+  # Builds a compressed viewport for Mneme's LLM context. Mneme sees
+  # conversation (user/agent messages and think events) but not mechanical
+  # execution (tool calls and responses). Tool calls are compressed to
+  # 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)
+  #
+  # 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: ..."
+  class CompressedViewport
+    ZONE_DELIMITERS = {
+      eviction: "── EVICTION ZONE (upper third) ──",
+      middle: "── MIDDLE ZONE ──",
+      recent: "── RECENT ZONE (lower third) ──"
+    }.freeze
+
+    # @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);
+    #   when nil, uses the session's full viewport
+    def initialize(session, token_budget:, from_event_id: nil)
+      @session = session
+      @token_budget = token_budget
+      @from_event_id = from_event_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?
+
+      zones = split_into_zones(events)
+      render_zones(zones)
+    end
+
+    # @return [Array<Event>] the raw events selected for this viewport
+    def events
+      @events ||= fetch_events
+    end
+
+    private
+
+    # Fetches events within token budget, starting from from_event_id.
+    # Selects newest-first until budget exhausted, returns chronological.
+    # Caches per-event token costs in @event_costs for reuse by split_into_zones.
+    #
+    # @return [Array<Event>]
+    def fetch_events
+      scope = @session.events.context_events.deliverable
+
+      if @from_event_id
+        scope = scope.where("id >= ?", @from_event_id)
+      end
+
+      selected = []
+      @event_costs = {}
+      remaining = @token_budget
+
+      scope.reorder(id: :desc).each do |event|
+        cost = event_token_cost(event)
+        break if cost > remaining && selected.any?
+
+        selected << event
+        @event_costs[event.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
+    # 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)] }
+      zone_size = costs.sum(&:last) / 3.0
+
+      result = {eviction: [], middle: [], recent: []}
+      cumulative = 0
+
+      costs.each do |event, cost|
+        cumulative += cost
+        result[zone_for_cumulative(cumulative, zone_size)] << event
+      end
+
+      result
+    end
+
+    # Renders zones with delimiters, compressing tool calls into counters.
+    #
+    # @param zones [Hash{Symbol => Array<Event>}]
+    # @return [String]
+    def render_zones(zones)
+      %i[eviction middle recent].flat_map { |name|
+        [ZONE_DELIMITERS[name], render_zone(zones[name])]
+      }.join("\n")
+    end
+
+    # Determines which zone an event belongs to based on cumulative token position.
+    #
+    # @param cumulative [Numeric] cumulative token count including this event
+    # @param zone_size [Float] token count per zone (total / 3)
+    # @return [Symbol] :eviction, :middle, or :recent
+    def zone_for_cumulative(cumulative, zone_size)
+      if cumulative <= zone_size
+        :eviction
+      elsif cumulative <= zone_size * 2
+        :middle
+      else
+        :recent
+      end
+    end
+
+    # Renders a single zone: conversation events 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.
+    #
+    # @param zone_events [Array<Event>]
+    # @return [String]
+    def render_zone(zone_events)
+      lines = []
+      tool_count = 0
+
+      zone_events.each do |event|
+        if conversation_event?(event) || think_event?(event)
+          lines << flush_tool_count(tool_count)
+          tool_count = 0
+          lines << render_event_line(event)
+        elsif event.event_type == "tool_call"
+          tool_count += 1
+        end
+      end
+
+      lines << flush_tool_count(tool_count)
+      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)
+    end
+
+    # Think events are tool_call events 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
+    end
+
+    ROLE_LABELS = {
+      "user_message" => "User",
+      "agent_message" => "Assistant",
+      "system_message" => "System"
+    }.freeze
+
+    # Renders a single event as a transcript line.
+    #
+    # @param event [Event]
+    # @return [String]
+    def render_event_line(event)
+      prefix = "event #{event.id}"
+      data = event.payload
+      if think_event?(event)
+        "#{prefix} Think: #{data.dig("tool_input", "thoughts")}"
+      else
+        "#{prefix} #{ROLE_LABELS.fetch(event.event_type)}: #{data["content"]}"
+      end
+    end
+
+    # Returns a tool count string if any tools were called, nil otherwise.
+    #
+    # @param count [Integer] number of tool calls to flush
+    # @return [String, nil]
+    def flush_tool_count(count)
+      return if count == 0
+      "[#{count} #{(count == 1) ? "tool" : "tools"} called]"
+    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
+    end
+  end
+end

data/lib/mneme/l2_runner.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Mneme
+  # Compresses multiple Level 1 snapshots into a single Level 2 snapshot.
+  # L2 snapshots capture days/weeks-scale context from hourly L1 summaries,
+  # preventing unbounded snapshot growth via recursive compression.
+  #
+  # Triggered from {MnemeJob} after an L1 snapshot is created, when enough
+  # uncovered L1 snapshots have accumulated (configurable via
+  # +mneme.l2_snapshot_threshold+ in config.toml).
+  #
+  # @example
+  #   Mneme::L2Runner.new(session).call
+  class L2Runner
+    TOOLS = [
+      Tools::SaveSnapshot,
+      Tools::EverythingOk
+    ].freeze
+
+    SYSTEM_PROMPT = <<~PROMPT
+      You are Mneme, the memory department of an AI agent named Anima.
+      Your job is to compress multiple conversation summaries into a single
+      higher-level summary.
+
+      You MUST ONLY communicate through tool calls — NEVER output text.
+
+      ──────────────────────────────
+      WHAT YOU SEE
+      ──────────────────────────────
+      Several Level 1 snapshots — hourly conversation summaries.
+      Each captures key decisions, goals discussed, and important context
+      from a portion of the conversation history.
+
+      ──────────────────────────────
+      YOUR TASK
+      ──────────────────────────────
+      Compress the snapshots into ONE Level 2 summary that captures the
+      essential arc across all of them. If the snapshots contain meaningful
+      content, call save_snapshot. If they are purely mechanical, call
+      everything_ok.
+
+      Preserve:
+      - Key decisions and their reasoning
+      - Goal progress across the time span
+      - Important context shifts or pivots
+      - Relationships and patterns across snapshots
+
+      Drop:
+      - Redundant details repeated across snapshots
+      - Mechanical execution details
+      - Interim decisions that were superseded by later ones
+
+      Always finish with exactly ONE tool call: either save_snapshot or everything_ok.
+    PROMPT
+
+    # @param session [Session] the main session whose L1 snapshots to compress
+    # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
+    def initialize(session, client: nil)
+      @session = session
+      @client = client || LLM::Client.new(
+        model: Anima::Settings.fast_model,
+        max_tokens: Anima::Settings.mneme_max_tokens,
+        logger: Mneme.logger
+      )
+    end
+
+    # Compresses uncovered L1 snapshots into a single L2 snapshot.
+    # Returns early if not enough L1 snapshots have accumulated.
+    #
+    # @return [String, nil] LLM response text, or nil when skipped
+    def call
+      l1_snapshots = eligible_snapshots
+      threshold = Anima::Settings.mneme_l2_snapshot_threshold
+      sid = @session.id
+      snapshot_count = l1_snapshots.size
+
+      if snapshot_count < threshold
+        log.debug("session=#{sid} — only #{snapshot_count}/#{threshold} L1 snapshots, skipping L2")
+        return
+      end
+
+      messages = build_messages(l1_snapshots)
+      registry = build_registry(l1_snapshots)
+
+      log.info("session=#{sid} — running L2 compression (#{snapshot_count} L1 snapshots)")
+
+      result = @client.chat_with_tools(
+        messages,
+        registry: registry,
+        session_id: nil,
+        system: SYSTEM_PROMPT
+      )
+
+      log.info("session=#{sid} — L2 compression done: #{result.to_s.truncate(200)}")
+      result
+    end
+
+    private
+
+    # L1 snapshots that are not yet covered by any L2 snapshot.
+    #
+    # @return [Array<Snapshot>]
+    def eligible_snapshots
+      @session.snapshots.for_level(1).not_covered_by_l2.chronological.to_a
+    end
+
+    # Frames L1 snapshot texts as a user message for the LLM.
+    #
+    # @param snapshots [Array<Snapshot>]
+    # @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}"
+      }.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.
+    #
+    # @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,
+        level: 2
+      })
+      TOOLS.each { |tool| registry.register(tool) }
+      registry
+    end
+
+    # @return [Logger]
+    def log = Mneme.logger
+  end
+end