anima-core 1.3.0 → 1.5.0

data/lib/events/subscribers/subagent_message_router.rb

@@ -2,33 +2,31 @@
 
 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.
     class SubagentMessageRouter
       include Events::Subscriber
 
-      # @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"
@@ -38,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)
@@ -68,8 +62,9 @@ module Events
       private
 
       # Forwards a sub-agent's text message to its parent session
-      # via {Session#enqueue_user_message}. Truncates oversized messages
-      # to protect the parent's context window.
+      # via {Session#enqueue_user_message} with source metadata.
+      # 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
@@ -83,9 +78,8 @@ module Events
           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)
+        parent.enqueue_user_message(truncated, source_type: "subagent", source_name: name)
       end
 
       # Scans a parent agent's message for @mentions and routes the message

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

data/lib/llm/client.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
 module LLM
-  # Convenience layer over {Providers::Anthropic} for sending messages
-  # and handling tool execution loops. Supports both simple text chat
-  # and multi-turn tool calling via the Anthropic tool use protocol.
+  # Convenience layer over {Providers::Anthropic} for phantom sessions
+  # (Mneme, Melete, Mneme::L2Runner) that need a multi-round tool-use
+  # loop driven from plain Ruby objects rather than the main drain
+  # pipeline.
   #
-  # @example Simple chat (no tools)
-  #   client = LLM::Client.new
-  #   client.chat([{role: "user", content: "Say hello"}])
-  #   # => "Hello! How can I help you today?"
+  # The main agent loop does NOT use this class — {DrainJob} talks to
+  # the provider directly and emits {Events::LLMResponded} for
+  # {Events::Subscribers::LLMResponseHandler} to process. The tool loop
+  # here is deliberately minimal: no events, no AASM transitions, no
+  # interrupt handling — phantom sessions don't interact with those
+  # machineries.
   #
-  # @example Chat with tools
+  # @example
   #   registry = Tools::Registry.new
-  #   registry.register(Tools::WebGet)
-  #   client.chat_with_tools(messages, registry: registry, session_id: session.id)
+  #   registry.register(Tools::SaveSnapshot)
+  #   client.chat_with_tools(messages, registry: registry)
   class Client
-    # Synthetic tool_result when a tool is skipped because the human pressed Escape.
+    # Synthetic tool_result text shown when a tool run is aborted by the
+    # user's Escape press. Mirrored into the interrupt subsystem so both
+    # the bash tool and any future interrupt handler share the phrasing.
     INTERRUPT_MESSAGE = "Your human wants your attention"
 
     # @return [Providers::Anthropic] the underlying API provider
@@ -39,86 +44,52 @@ module LLM
       @logger = logger
     end
 
-    # Send messages to the LLM and return the assistant's text response.
+    # Runs a minimal multi-round tool-use cycle: call the LLM, execute
+    # any requested tools, feed results back, repeat until the LLM
+    # produces a final text response.
     #
-    # @param messages [Array<Hash>] conversation messages, each with +:role+ and +:content+
-    # @param options [Hash] additional API parameters (e.g. +system:+, +temperature:+)
-    # @return [String] the assistant's response text
-    # @raise [Providers::Anthropic::Error] on API errors
-    # @raise [Providers::Anthropic::AuthenticationError] on auth failures
-    def chat(messages, **options)
-      response = provider.create_message(
-        model: model,
-        messages: messages,
-        max_tokens: max_tokens,
-        **options
-      )
-
-      extract_text(response)
-    end
-
-    # Send messages with tool support. Runs the full tool execution loop:
-    # call LLM, execute any requested tools, feed results back, repeat
-    # until the LLM produces a final text response.
-    #
-    # Emits {Events::ToolCall} and {Events::ToolResponse} events for each
-    # tool interaction so they're persisted and visible in the event stream.
-    #
-    # When the user interrupts via Escape, remaining tools receive synthetic
-    # "Your human wants your attention" results and the loop exits without another LLM call.
+    # Intended for phantom sessions (Mneme, Melete). No events are
+    # emitted and no persistence happens — the caller is responsible
+    # for capturing whatever state the tool runs produce.
     #
     # @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
+    # @return [Hash] +:text+ (String) and +:api_metrics+ (Hash)
     # @raise [Providers::Anthropic::Error] on API errors
-    def chat_with_tools(messages, registry:, session_id:, first_response: nil, **options)
+    def chat_with_tools(messages, registry:, **options)
       messages = messages.dup
       rounds = 0
+      last_api_metrics = nil
 
       loop do
         rounds += 1
         max_rounds = Anima::Settings.max_tool_rounds
         if rounds > max_rounds
-          return "[Tool loop exceeded #{max_rounds} rounds — halting]"
+          return {text: "[Tool loop exceeded #{max_rounds} rounds — halting]", api_metrics: last_api_metrics}
         end
 
-        response = if first_response && rounds == 1
-          first_response
-        else
-          broadcast_session_state(session_id, "llm_generating")
-          provider.create_message(
-            model: model,
-            messages: messages,
-            max_tokens: max_tokens,
-            tools: registry.schemas,
-            **options
-          )
-        end
+        response = provider.create_message(
+          model: model,
+          messages: messages,
+          max_tokens: max_tokens,
+          tools: registry.schemas,
+          include_metrics: true,
+          **options
+        )
+
+        last_api_metrics = response.api_metrics if response.respond_to?(:api_metrics)
 
         log(:debug, "stop_reason=#{response["stop_reason"]} content_types=#{(response["content"] || []).map { |b| b["type"] }.join(",")}")
 
         if response["stop_reason"] == "tool_use"
-          tool_results = execute_tools(response, registry, session_id)
-
+          tool_results = execute_tools(response, registry)
           messages += [
             {role: "assistant", content: response["content"]},
             {role: "user", content: tool_results}
           ]
-
-          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)
+          return {text: extract_text(response), api_metrics: last_api_metrics}
         end
       end
     end
@@ -131,7 +102,6 @@ module LLM
 
     def extract_text(response)
       content = response["content"] || []
-
       content
         .select { |block| block["type"] == "text" }
         .map { |block| block["text"] }
@@ -143,157 +113,36 @@ module LLM
       content.select { |block| block["type"] == "tool_use" }
     end
 
-    # Executes all tool_use blocks from a response, emitting events for each.
-    # Checks for user interrupt between tools — remaining tools receive
-    # synthetic results to satisfy the Anthropic API's tool_use/tool_result
-    # pairing requirement (a missing result permanently breaks the conversation).
-    #
-    # @param response [Hash] Anthropic API response with tool_use content blocks
-    # @param registry [Tools::Registry] tool registry for dispatch
-    # @param session_id [Integer, String] session ID for events
-    # @return [Array<Hash>] tool_result content blocks for the next API call
-    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|
-        # 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
-        end
-        results << execute_single_tool(tool_use, registry, session_id)
-      end
-
-      results
-    end
-
-    # 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
-    # @return [Array<Hash>] tool_result content blocks
-    def interrupt_remaining_tools(tool_uses, session_id)
-      tool_uses.map { |tool_use| interrupt_tool(tool_use, session_id) }
+    # Executes every +tool_use+ block from the response and returns
+    # matching +tool_result+ blocks. Always emits a result — a missing
+    # result permanently corrupts the Anthropic conversation history.
+    def execute_tools(response, registry)
+      extract_tool_uses(response).map { |tool_use| execute_single_tool(tool_use, registry) }
     end
 
-    # Executes a single tool and always returns a tool_result — even if the
-    # tool raises. Per the Anthropic tool-use protocol, every tool_use must
-    # have a matching tool_result; a missing result permanently corrupts the
-    # conversation history and breaks the session.
-    #
-    # Falls back to SecureRandom.uuid when Anthropic omits the tool_use id,
-    # ensuring the ToolCall/ToolResponse pair always shares a valid identifier.
-    def execute_single_tool(tool_use, registry, session_id)
+    def execute_single_tool(tool_use, registry)
       name = tool_use["name"]
       id = tool_use["id"] || SecureRandom.uuid
       input = tool_use["input"] || {}
-      timeout = input["timeout"] || Anima::Settings.tool_timeout
 
       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,
-        session_id: session_id
-      ))
-
       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(
-        content: result_content, tool_name: name, tool_use_id: id,
-        success: !result.is_a?(Hash) || !result.key?(:error),
-        session_id: session_id
-      ))
+      log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
 
       {type: "tool_result", tool_use_id: id, content: result_content}
     rescue => error
       error_detail = "#{error.class}: #{error.message}"
       Rails.logger.error("Tool #{name} raised #{error_detail}")
-      error_content = format_tool_result(error: error_detail)
-
-      # Emission can fail (e.g. encoding errors in ActionCable/SQLite),
-      # but losing the tool_result would permanently corrupt the session.
-      begin
-        Events::Bus.emit(Events::ToolResponse.new(
-          content: error_content, tool_name: name, tool_use_id: id,
-          success: false, session_id: session_id
-        ))
-      rescue => emit_error
-        Rails.logger.error("ToolResponse emission failed: #{emit_error.class}: #{emit_error.message}")
-      end
-
-      {type: "tool_result", tool_use_id: id, content: error_content}
-    end
-
-    # 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.
-    #
-    # @param tool_use [Hash] Anthropic tool_use content block
-    # @param session_id [Integer, String] session ID for events
-    # @return [Hash] tool_result content block
-    def interrupt_tool(tool_use, session_id)
-      name = tool_use["name"]
-      id = tool_use["id"] || SecureRandom.uuid
-      input = tool_use["input"] || {}
-
-      Events::Bus.emit(Events::ToolCall.new(
-        content: "Skipped #{name} — your human wants your attention", tool_name: name,
-        tool_input: input, tool_use_id: id, session_id: session_id
-      ))
-
-      Events::Bus.emit(Events::ToolResponse.new(
-        content: INTERRUPT_MESSAGE, tool_name: name, tool_use_id: id,
-        success: false, session_id: session_id
-      ))
-
-      {type: "tool_result", tool_use_id: id, content: INTERRUPT_MESSAGE}
-    end
-
-    # Checks whether the session has a pending interrupt flag.
-    #
-    # @param session_id [Integer, String] session to check
-    # @return [Boolean] true when interrupt is pending
-    def interrupt_requested?(session_id)
-      Session.where(id: session_id, interrupt_requested: true).exists?
-    end
-
-    # 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 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 broadcast_session_state(session_id, state, tool: nil)
-      Session.find_by(id: session_id)&.broadcast_session_state(state, tool: tool)
+      {type: "tool_result", tool_use_id: id, content: format_tool_result(error: error_detail)}
     end
 
     def log(level, message)
       return unless @logger
-
       @logger.public_send(level, message)
     end
 
@@ -301,8 +150,6 @@ module LLM
       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