anima-core 1.4.0 → 1.5.0

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)

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

data/lib/events/subscribers/subagent_message_router.rb

@@ -2,24 +2,25 @@
 
 module Events
   module Subscribers
-    # Routes text messages between parent and child sessions, enabling
-    # bidirectional @mention communication.
+    # Routes agent text messages between parent and child sessions,
+    # enabling bidirectional @mention communication.
     #
-    # **Child → Parent:** When a sub-agent emits an {Events::AgentMessage},
-    # the router creates a {Events::UserMessage} in the parent session
-    # with attribution prefix. If the parent is idle, persists directly
-    # and wakes it via {AgentRequestJob}. If the parent is mid-turn,
-    # emits a pending message that is promoted after the current loop
-    # completes — same mechanism as {SessionChannel#speak}.
+    # Subscribes to {Events::MessageCreated} and filters on
+    # +message_type == "agent_message"+ — the Message record is the single
+    # source of truth for LLM-produced text, so routing hangs off the
+    # persistence lifecycle rather than a parallel domain-event emission.
     #
-    # **Parent → Child:** When a parent agent emits an {Events::AgentMessage}
-    # containing `@name` mentions, the router persists the message in each
-    # matching child session with a +[from parent]:+ origin label and wakes
-    # them via {AgentRequestJob}.
+    # **Child → Parent:** When a sub-agent persists an +agent_message+,
+    # the router enqueues a {PendingMessage} on the parent with sub-agent
+    # attribution. The PM's +after_create_commit+ kicks off the drain
+    # pipeline when the parent is idle; otherwise the message queues
+    # silently and the idle-wake rule picks it up.
     #
-    # Both directions delegate to {Session#enqueue_user_message}, which
-    # respects the target session's processing state — persisting directly
-    # when idle, deferring via pending queue when mid-turn.
+    # **Parent → Child:** When a parent agent persists an +agent_message+
+    # containing +@name+ mentions, the router enqueues a PendingMessage
+    # in each matching child session with a +[from parent]:+ origin label.
+    #
+    # Both directions delegate to {Session#enqueue_user_message}.
     #
     # This replaces the +return_result+ tool — sub-agents communicate
     # through natural text messages instead of structured tool calls.
@@ -35,25 +36,21 @@ module Events
 
       # Routes agent text messages between parent and child sessions.
       #
-      # For sub-agent sessions: forwards to parent with attribution prefix.
+      # For sub-agent sessions: forwards to parent with attribution.
       # 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)
+      # @param event [Hash] Rails.event notification hash with +:payload+
+      #   carrying the persisted {Message} record under +:message+
       # @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
+        message = event.dig(:payload, :message)
+        return unless message.is_a?(Message)
+        return unless message.message_type == "agent_message"
 
-        content = payload[:content].to_s
+        content = message.payload["content"].to_s
         return if content.empty?
 
-        session = Session.find_by(id: session_id)
-        return unless session
+        session = message.session
 
         if session.sub_agent?
           route_to_parent(session, content)
@@ -66,8 +63,8 @@ module Events
 
       # Forwards a sub-agent's text message to its parent session
       # via {Session#enqueue_user_message} with source metadata.
-      # The parent's {PendingMessage} (or idle-path message) owns the
-      # attribution formatting — the router passes raw content.
+      # The parent's {PendingMessage} owns the attribution formatting —
+      # the router passes raw content.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text

data/lib/events/subscribers/subagent_visibility_broadcaster.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Broadcasts sub-agent eviction to the parent session's stream so the
+    # TUI HUD panel removes the entry. Fires in response to
+    # {Events::SubagentEvicted}, which {Mneme::Runner} emits after a
+    # boundary advance leaves a sub-agent with no remaining traces in the
+    # parent viewport.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::SubagentVisibilityBroadcaster.new) { |event|
+    #     event[:name] == "anima.subagent.evicted"
+    #   }
+    class SubagentVisibilityBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        ActionCable.server.broadcast(
+          "session_#{session_id}",
+          {
+            "action" => "subagent_evicted",
+            "session_id" => session_id,
+            "child_id" => payload[:child_id]
+          }
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/tool_response_creator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Records a tool's outcome as a +tool_response+ PendingMessage on
+    # {Events::ToolExecuted}. One ToolExecuted → one PM. The subscriber
+    # owns no state transitions: the session stays in +:executing+ until
+    # {DrainJob} claims it via the +executing → awaiting+ branch of
+    # +start_processing+ (gated by +Session#tool_round_complete?+).
+    #
+    # The PM's +after_create_commit+ emits {Events::StartProcessing}
+    # whenever the AASM guard says drain may now claim — typically when
+    # the last sibling tool_response of the round lands.
+    class ToolResponseCreator
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session = Session.find(payload[:session_id])
+
+        session.pending_messages.create!(
+          content: payload[:content].to_s,
+          source_type: "tool",
+          source_name: payload[:tool_name],
+          message_type: "tool_response",
+          tool_use_id: payload[:tool_use_id],
+          success: payload[:success]
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/transient_broadcaster.rb

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

data/lib/events/tool_executed.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted by {ToolExecutionJob} after a tool finishes running.
+  # Carries the tool result so the response subscriber can create a
+  # +tool_response+ PendingMessage and release the session back to idle
+  # — which in turn wakes the drain loop for the next LLM round.
+  class ToolExecuted
+    TYPE = "session.tool_executed"
+
+    attr_reader :session_id, :tool_use_id, :tool_name, :content, :success
+
+    # @param session_id [Integer] session the tool ran on behalf of
+    # @param tool_use_id [String] pairing ID for the originating +tool_use+ block
+    # @param tool_name [String] name of the tool that executed
+    # @param content [String] tool output (already formatted and truncated)
+    # @param success [Boolean] +true+ on normal completion, +false+ on error or interrupt
+    def initialize(session_id:, tool_use_id:, tool_name:, content:, success:)
+      @session_id = session_id
+      @tool_use_id = tool_use_id
+      @tool_name = tool_name
+      @content = content
+      @success = success
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, tool_use_id:, tool_name:, content:, success:}
+    end
+  end
+end

data/lib/events/workflow_activated.rb

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