anima-core 1.3.0 → 1.5.0

data/lib/events/message_updated.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a Message record is updated and committed.
+  # Used by subscribers that need to react to message changes
+  # (e.g. broadcasting updated token counts to WebSocket clients).
+  class MessageUpdated
+    TYPE = "message.updated"
+
+    attr_reader :message
+
+    # @param message [Message] the updated message record
+    def initialize(message)
+      @message = message
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, message:}
+    end
+  end
+end

data/lib/events/session_state_changed.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when a session's transport-level state changes. Carries the
+  # AASM state after a transition (+"idle"+/+"awaiting"+/+"executing"+)
+  # or a transient UI signal (+"interrupting"+).
+  #
+  # Subscribers broadcast the state over ActionCable so the TUI spinner
+  # and sub-agent HUD update in sync.
+  class SessionStateChanged
+    TYPE = "session.state_changed"
+
+    attr_reader :session_id, :state
+
+    # @param session_id [Integer] the session the state change belongs to
+    # @param state [String] transport state name
+    def initialize(session_id:, state:)
+      @session_id = session_id
+      @state = state
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id: session_id, state: state}
+    end
+  end
+end

data/lib/events/skill_activated.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after {Session#activate_skill} enqueues a skill's phantom
+  # pair. Subscribers rebroadcast the session's active skills/workflow
+  # so the HUD reflects the new activation immediately (before the
+  # pending message even promotes).
+  class SkillActivated
+    TYPE = "skill.activated"
+
+    attr_reader :session_id, :skill_name
+
+    # @param session_id [Integer] the session the skill was activated on
+    # @param skill_name [String] canonical skill name
+    def initialize(session_id:, skill_name:)
+      @session_id = session_id
+      @skill_name = skill_name
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, skill_name:}
+    end
+  end
+end

data/lib/events/start_melete.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when a +user_message+ PendingMessage lands on an idle session.
+  # Melete subscribes via {Events::Subscribers::MeleteKickoff} and runs
+  # its enrichment loop — activating skills, reading workflows, refining
+  # goals, renaming the session — then either:
+  #
+  # * emits {Events::StartMneme} when a goal changed during the run, so
+  #   Mneme can recall against the fresh goal set, or
+  # * emits {Events::StartProcessing} when goals were untouched, skipping
+  #   Mneme entirely (no new search seed to recall against).
+  #
+  # First stage of the +start_melete → (start_mneme) → start_processing+
+  # chain that orchestrates context enrichment before the LLM is called.
+  class StartMelete
+    TYPE = "session.start_melete"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose enrichment chain should continue
+    # @param pending_message_id [Integer, nil] the PendingMessage that triggered the chain
+    def initialize(session_id:, pending_message_id: nil)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/start_mneme.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted by {MeleteEnrichmentJob} when goals changed during the Melete
+  # run, signalling that Mneme should recall against the fresh goal set.
+  # Mneme subscribes via {Events::Subscribers::MnemeKickoff}, performs
+  # associative recall, enqueues its memories as background PendingMessages,
+  # and emits {Events::StartProcessing} to continue the drain.
+  #
+  # Second stage of the +start_melete → (start_mneme) → start_processing+
+  # chain. Conditional — when goals are untouched the pipeline jumps
+  # straight from {Events::StartMelete} to {Events::StartProcessing}.
+  class StartMneme
+    TYPE = "session.start_mneme"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose drain pipeline should start
+    # @param pending_message_id [Integer] the PendingMessage that triggered the chain
+    def initialize(session_id:, pending_message_id:)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/start_processing.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when an active PendingMessage lands on an idle session and does
+  # not require the Melete/Mneme enrichment pipeline (tool calls, tool
+  # responses, sub-agent replies), or when {MeleteEnrichmentJob} finishes
+  # without a goal change, or when {MnemeEnrichmentJob} finishes recall.
+  # The drain loop subscribes and begins processing the mailbox.
+  #
+  # Final stage of the +start_melete → (start_mneme) → start_processing+
+  # chain.
+  class StartProcessing
+    TYPE = "session.start_processing"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose drain loop should start
+    # @param pending_message_id [Integer, nil] the PendingMessage that triggered the chain, if any
+    def initialize(session_id:, pending_message_id: nil)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/subagent_evicted.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when {Mneme::Runner} advances the boundary past every remaining
+  # trace of a sub-agent — the spawn pair plus every +from_{nickname}+
+  # phantom pair. Subscribers broadcast the removal so clients drop the
+  # entry from the HUD panel.
+  #
+  # +session_id+ is the parent session (HUD owner), +child_id+ is the
+  # sub-agent session whose traces just aged out.
+  class SubagentEvicted
+    TYPE = "subagent.evicted"
+
+    attr_reader :session_id, :child_id
+
+    # @param session_id [Integer] parent session whose HUD should drop the entry
+    # @param child_id [Integer] sub-agent session whose traces were evicted
+    def initialize(session_id:, child_id:)
+      @session_id = session_id
+      @child_id = child_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, child_id:}
+    end
+  end
+end

data/lib/events/subscribers/active_state_broadcaster.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Rebroadcasts the session's active skills and workflow whenever the
+    # set can change: skill activation, workflow activation, or Mneme
+    # eviction. Same handler, three triggers — each event carries a
+    # +session_id+ and the broadcaster reads live state off the session.
+    #
+    # @example Registering at boot
+    #   trigger = ->(event) {
+    #     %w[anima.skill.activated anima.workflow.activated anima.eviction.completed]
+    #       .include?(event[:name])
+    #   }
+    #   Events::Bus.subscribe(Events::Subscribers::ActiveStateBroadcaster.new, &trigger)
+    class ActiveStateBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        session_id = event.dig(:payload, :session_id)
+        session = Session.find_by(id: session_id)
+        session&.broadcast_active_state!
+      end
+    end
+  end
+end

data/lib/events/subscribers/authentication_broadcaster.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Reacts to {Events::AuthenticationRequired} by surfacing the provider
+    # rejection to the operator. Emits a +system_message+ into the
+    # conversation (so the failure lives in history) and broadcasts an
+    # +authentication_required+ frame on the session's ActionCable stream
+    # (so the TUI can prompt for a new token).
+    #
+    # Follows the same shape as {SessionStateBroadcaster}: jobs emit
+    # typed events, broadcasters own the ActionCable side.
+    class AuthenticationBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        message = payload[:content]
+
+        Events::Bus.emit(Events::SystemMessage.new(
+          content: "Authentication failed: #{message}",
+          session_id: session_id
+        ))
+
+        ActionCable.server.broadcast(
+          "session_#{session_id}",
+          {"action" => "authentication_required", "message" => message}
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/drain_kickoff.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Entry subscriber for the drain loop. On {Events::StartProcessing},
+    # enqueues {DrainJob} — the actual work (session claim, PM promotion,
+    # LLM call) happens in the job so the emitter's thread isn't blocked.
+    class DrainKickoff
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        session_id = event[:payload][:session_id]
+        return unless session_id
+
+        DrainJob.perform_later(session_id)
+      end
+    end
+  end
+end

data/lib/events/subscribers/eviction_broadcaster.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Broadcasts eviction cutoff to connected WebSocket clients after Mneme
+    # advances the boundary. Clients drop all messages above the cutoff
+    # (id <= evict_above_id) — older messages at the top of the chat view.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::EvictionBroadcaster.new) { |event|
+    #     event[:name] == "anima.eviction.completed"
+    #   }
+    class EvictionBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        ActionCable.server.broadcast(
+          "session_#{payload[:session_id]}",
+          {"action" => "eviction", "evict_above_id" => payload[:evict_above_id]}
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/llm_response_handler.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Handles the aftermath of a single LLM round-trip emitted via
+    # {Events::LLMResponded}. Persists the assistant's output as Message
+    # records, transitions the session state, and — when the response
+    # includes a +tool_use+ block — queues {ToolExecutionJob} for each
+    # tool.
+    #
+    # This is where session state moves away from +:awaiting+: either
+    # {Session#response_complete!} on a text-only response, or
+    # {Session#tool_received!} before dispatching tool work. The drain
+    # job itself never transitions state past +:awaiting+ — that is this
+    # subscriber's responsibility, per the SOLID rule that event
+    # emission is the final act of a piece.
+    class LLMResponseHandler
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session = Session.find(payload[:session_id])
+
+        response = payload[:response] || {}
+        api_metrics = payload[:api_metrics]
+
+        tool_uses = normalize_tool_uses(response)
+        text = extract_text(response)
+
+        persist_agent_message(session, text, api_metrics) if text.present?
+        tool_uses.each { |tool_use| persist_tool_call(session, tool_use) }
+
+        if tool_uses.any?
+          session.tool_received! if session.may_tool_received?
+          dispatch_tool_executions(session, tool_uses)
+        elsif session.may_response_complete?
+          session.response_complete!
+        end
+      end
+
+      private
+
+      def content_blocks(response)
+        response["content"] || response[:content] || []
+      end
+
+      def block_type(block)
+        block["type"] || block[:type]
+      end
+
+      # Returns tool_use blocks with a guaranteed +id+. Generates a UUID
+      # once when the provider omits one so persistence and dispatch see
+      # the same id — a missing match breaks tool_use/tool_result
+      # pairing in the Anthropic conversation.
+      def normalize_tool_uses(response)
+        content_blocks(response).filter_map do |block|
+          next unless block_type(block) == "tool_use"
+
+          {
+            "id" => block["id"] || block[:id] || SecureRandom.uuid,
+            "name" => block["name"] || block[:name],
+            "input" => block["input"] || block[:input] || {}
+          }
+        end
+      end
+
+      def extract_text(response)
+        content_blocks(response)
+          .select { |block| block_type(block) == "text" }
+          .map { |block| block["text"] || block[:text] }
+          .join
+      end
+
+      def persist_agent_message(session, text, api_metrics)
+        session.messages.create!(
+          message_type: "agent_message",
+          payload: {"type" => "agent_message", "content" => text, "session_id" => session.id},
+          timestamp: Time.current.to_ns,
+          api_metrics: api_metrics
+        )
+      end
+
+      def persist_tool_call(session, tool_use)
+        session.messages.create!(
+          message_type: "tool_call",
+          tool_use_id: tool_use["id"],
+          payload: {
+            "type" => "tool_call",
+            "tool_name" => tool_use["name"],
+            "tool_use_id" => tool_use["id"],
+            "tool_input" => tool_use["input"],
+            "content" => "Calling #{tool_use["name"]}"
+          },
+          timestamp: Time.current.to_ns
+        )
+      end
+
+      def dispatch_tool_executions(session, tool_uses)
+        tool_uses.each do |tool_use|
+          ToolExecutionJob.perform_later(
+            session.id,
+            tool_use_id: tool_use["id"],
+            tool_name: tool_use["name"],
+            tool_input: tool_use["input"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/events/subscribers/melete_kickoff.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Entry subscriber for the Melete stage of the drain pipeline. On
+    # {Events::StartMelete}, enqueues {MeleteEnrichmentJob} to run
+    # skill/goal/workflow preparation asynchronously.
+    class MeleteKickoff
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        return unless session_id
+
+        MeleteEnrichmentJob.perform_later(
+          session_id,
+          pending_message_id: payload[:pending_message_id]
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/message_broadcaster.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Broadcasts message lifecycle events to connected WebSocket clients
+    # via ActionCable. Subscribes to {Events::MessageCreated} and
+    # {Events::MessageUpdated} events.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::MessageBroadcaster.new) { |event|
+    #     event[:name].start_with?("anima.message.")
+    #   }
+    class MessageBroadcaster
+      include Events::Subscriber
+
+      ACTION_MAP = {
+        Events::MessageCreated::TYPE => "create",
+        Events::MessageUpdated::TYPE => "update"
+      }.freeze
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        message = event[:payload][:message]
+        action = ACTION_MAP.fetch(event[:payload][:type])
+        session = message.session
+        broadcast_payload = message.payload.merge("id" => message.id, "action" => action)
+        broadcast_payload["api_metrics"] = message.api_metrics if message.api_metrics.present?
+        broadcast_payload["rendered"] = {session.view_mode => message.decorate.render(session.view_mode)}
+
+        ActionCable.server.broadcast("session_#{message.session_id}", broadcast_payload)
+      end
+    end
+  end
+end

data/lib/events/subscribers/mneme_kickoff.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Entry subscriber for the Mneme stage of the drain pipeline. On
+    # {Events::StartMneme}, enqueues {MnemeEnrichmentJob} to run
+    # associative recall asynchronously.
+    class MnemeKickoff
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        return unless session_id
+
+        MnemeEnrichmentJob.perform_later(
+          session_id,
+          pending_message_id: payload[:pending_message_id]
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/mneme_scheduler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Checks whether Mneme should run after each persisted message.
+    # Subscribes to {Events::MessageCreated} events.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::MnemeScheduler.new) { |event|
+    #     event[:name] == "anima.message.created"
+    #   }
+    class MnemeScheduler
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        event[:payload][:message].session.schedule_mneme!
+      end
+    end
+  end
+end

data/lib/events/subscribers/persister.rb

@@ -9,10 +9,9 @@ module Events
     # 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.
+    # User messages are NOT persisted here — {DrainJob} promotes them
+    # from {PendingMessage} into the Message stream as part of the drain
+    # cycle so bounce-back semantics stay close to the promotion.
     #
     # @example Session-scoped
     #   persister = Events::Subscribers::Persister.new(session)
@@ -33,10 +32,9 @@ module Events
 
       # Receives a Rails.event notification hash and persists it.
       #
-      # 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}).
+      # Skips user messages — those are promoted from PendingMessage by
+      # {DrainJob}. Also skips event types not in {Message::TYPES}
+      # (transient events like {Events::BounceBack}).
       #
       # @param event [Hash] with :payload containing event data
       def emit(event)
@@ -56,7 +54,8 @@ module Events
             message_type: event_type,
             payload: payload,
             tool_use_id: payload[:tool_use_id],
-            timestamp: payload[:timestamp] || Time.current.to_ns
+            timestamp: payload[:timestamp] || Time.current.to_ns,
+            api_metrics: payload[:api_metrics]
           )
         end
       end

data/lib/events/subscribers/session_state_broadcaster.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Broadcasts session state over ActionCable in response to
+    # {Events::SessionStateChanged}. Sends +session_state+ to the session
+    # stream and, for sub-agents, +child_state+ to the parent stream so the
+    # HUD updates without a full children refresh.
+    #
+    # @example Registering at boot
+    #   trigger = ->(event) { event[:name] == "anima.session.state_changed" }
+    #   Events::Bus.subscribe(Events::Subscribers::SessionStateBroadcaster.new, &trigger)
+    class SessionStateBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        state = payload[:state]
+
+        action_payload = {"action" => "session_state", "state" => state, "session_id" => session_id}
+        ActionCable.server.broadcast("session_#{session_id}", action_payload)
+
+        parent_id = Session.where(id: session_id).pick(:parent_session_id)
+        return unless parent_id
+
+        parent_payload = action_payload.merge("action" => "child_state", "child_id" => session_id)
+        ActionCable.server.broadcast("session_#{parent_id}", parent_payload)
+      end
+    end
+  end
+end