anima-core 1.2.0 → 1.4.0

data/lib/llm/client.rb

@@ -2,21 +2,15 @@
 
 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.
+  # and handling tool execution loops.
   #
-  # @example Simple chat (no tools)
-  #   client = LLM::Client.new
-  #   client.chat([{role: "user", content: "Say hello"}])
-  #   # => "Hello! How can I help you today?"
-  #
-  # @example Chat with tools
+  # @example
   #   registry = Tools::Registry.new
   #   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
@@ -39,24 +33,6 @@ module LLM
       @logger = logger
     end
 
-    # Send messages to the LLM and return the assistant's 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.
@@ -65,7 +41,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
@@ -73,54 +49,89 @@ module LLM
     # @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 between_rounds [#call, nil] callback invoked after each tool
+    #   round completes, before the next LLM request. Must return an
+    #   +Array<String>+ of message contents to inject (e.g. promoted
+    #   pending messages). Injected as +text+ blocks alongside
+    #   +tool_result+ blocks so the LLM sees them in the next round.
     # @param options [Hash] additional API parameters (e.g. +system:+)
-    # @return [String, nil] the assistant's final text response, or nil when interrupted
+    # @return [Hash, nil] +:text+ (String) and +:api_metrics+ (Hash), or nil when interrupted
     # @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:, session_id:, first_response: nil, between_rounds: nil, **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,
+            include_metrics: true,
             **options
           )
         end
 
+        # Capture api_metrics from ApiResponse wrapper (nil for pre-fetched first_response)
+        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)
+          promoted = promote_between_rounds(between_rounds)
+
+          # Dual injection: user messages go as text blocks within the current
+          # tool_results turn (same speaker); sub-agent messages append as
+          # separate assistant→user turn pairs (distinct tool invocations).
+          promoted[:texts].each { |text| tool_results << {type: "text", text: text} }
 
           messages += [
             {role: "assistant", content: response["content"]},
             {role: "user", content: tool_results}
           ]
 
-          if interrupted?(session_id)
-            clear_interrupt!(session_id)
-            return nil
-          end
+          messages.concat(promoted[:pairs])
+
+          return nil if handle_interrupt!(session_id)
         else
-          return extract_text(response)
+          # 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 {text: extract_text(response), api_metrics: last_api_metrics}
         end
       end
     end
 
     private
 
+    # Invokes the between_rounds callback and returns promoted messages
+    # split by injection strategy.
+    #
+    # @param between_rounds [#call, nil] callback returning
+    #   +{texts: Array<String>, pairs: Array<Hash>}+
+    # @return [Hash{Symbol => Array}] +:texts+ for user messages (text blocks
+    #   in current tool_results), +:pairs+ for sub-agent messages (separate
+    #   conversation turns)
+    def promote_between_rounds(between_rounds)
+      return {texts: [], pairs: []} unless between_rounds
+      between_rounds.call
+    end
+
     def build_provider(provider)
       provider || Providers::Anthropic.new
     end
@@ -151,9 +162,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 +178,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 +202,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 +213,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 +242,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 +255,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 +267,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 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 clear
+    # @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 +307,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

@@ -52,12 +52,16 @@ module Mneme
     private
 
     # Fetches messages within token budget, starting from from_message_id.
-    # Selects newest-first until budget exhausted, returns chronological.
+    # Walks oldest-first from the boundary so Mneme processes the eviction
+    # zone (oldest messages) rather than the recent zone. This ensures
+    # {Mneme::Runner#advance_boundary} advances past only the oldest third,
+    # preserving recent conversation context in the main viewport.
+    #
     # Caches per-message token costs in @message_costs for reuse by split_into_zones.
     #
-    # @return [Array<Message>]
+    # @return [Array<Message>] chronologically ordered (oldest first)
     def fetch_messages
-      scope = @session.messages.context_messages.deliverable
+      scope = @session.messages.context_messages
 
       if @from_message_id
         scope = scope.where("id >= ?", @from_message_id)
@@ -67,7 +71,7 @@ module Mneme
       @message_costs = {}
       remaining = @token_budget
 
-      scope.reorder(id: :desc).each do |message|
+      scope.reorder(id: :asc).each do |message|
         cost = message_token_cost(message)
         break if cost > remaining && selected.any?
 
@@ -76,7 +80,7 @@ module Mneme
         remaining -= cost
       end
 
-      selected.reverse
+      selected
     end
 
     # Splits messages into three zones by token count.

data/lib/mneme/passive_recall.rb

@@ -2,38 +2,41 @@
 
 module Mneme
   # Passive recall — automatic memory surfacing triggered by Goal updates.
-  # When goals are created or updated, searches event history for related
-  # context and caches the results on the session for viewport injection.
+  # When goals are created or updated, searches message history for related
+  # context and enqueues phantom tool_call/tool_response pairs via the
+  # PendingMessage pipeline.
   #
-  # The agent never calls a tool; relevant memories appear automatically
-  # in the viewport between snapshots and the sliding window. This mirrors
-  # recognition memory in humans — context surfaces without conscious effort.
+  # Phantom pairs are promoted into real Message records by
+  # {Session#promote_pending_messages!} between agent loop rounds, then
+  # ride the conveyor belt like regular messages — cached as part of the
+  # stable prefix, compressed by Mneme on eviction.
   #
   # @example Trigger after a goal update
   #   Mneme::PassiveRecall.new(session).call
   class PassiveRecall
+    # Estimated token overhead for a tool_use wrapper (name + input fields).
+    TOOL_PAIR_OVERHEAD_TOKENS = 50
+
     # @param session [Session] the session whose goals drive recall
     def initialize(session)
       @session = session
     end
 
-    # Searches event history using active goal descriptions as queries.
-    # Returns recall results suitable for viewport injection.
+    # Searches message history using active goal descriptions as queries.
+    # Enqueues phantom recall pairs for new results not already recalled.
     #
-    # @return [Array<Mneme::Search::Result>] deduplicated, relevance-sorted
+    # @return [Integer] number of pending messages created
     def call
       goals = @session.goals.active.root.includes(:sub_goals)
-      return [] if goals.empty?
+      return 0 if goals.empty?
 
       search_terms = build_search_terms(goals)
-      return [] if search_terms.blank?
+      return 0 if search_terms.blank?
 
       results = Mneme::Search.query(search_terms, limit: Anima::Settings.recall_max_results)
+      results = filter_duplicates(results)
 
-      # Exclude events from the current session's viewport — no point recalling
-      # what the agent already sees.
-      viewport_ids = @session.viewport_message_ids.to_set
-      results.reject { |result| viewport_ids.include?(result.message_id) }
+      enqueue_pending_messages(results)
     end
 
     private
@@ -46,8 +49,6 @@ module Mneme
     ]).freeze
 
     # Extracts meaningful keywords from active goals and joins with OR.
-    # Stop words and generic verbs are stripped — they're too common to
-    # produce useful recall results.
     #
     # @param goals [ActiveRecord::Relation<Goal>]
     # @return [String] FTS5 OR-joined keywords
@@ -65,5 +66,73 @@ module Mneme
 
       words.join(" OR ").truncate(500)
     end
+
+    # Excludes results already in the viewport or already recalled (pending or promoted).
+    #
+    # @param results [Array<Mneme::Search::Result>]
+    # @return [Array<Mneme::Search::Result>]
+    def filter_duplicates(results)
+      viewport_ids = @session.viewport_message_ids.to_set
+
+      existing_recall_ids = @session.messages
+        .where(message_type: "tool_call")
+        .where("payload ->> 'tool_name' = ?", PendingMessage::RECALL_MEMORY_TOOL)
+        .pluck(:tool_use_id)
+        .to_set
+
+      pending_recall_ids = @session.pending_messages
+        .where(source_type: "recall")
+        .pluck(:source_name)
+        .map { |name| "recall_#{name}" }
+        .to_set
+
+      known_ids = existing_recall_ids | pending_recall_ids
+
+      results.reject { |result|
+        viewport_ids.include?(result.message_id) ||
+          known_ids.include?("recall_#{result.message_id}")
+      }
+    end
+
+    # Creates PendingMessages for each recall result.
+    #
+    # @param results [Array<Mneme::Search::Result>]
+    # @return [Integer] number of pending messages created
+    def enqueue_pending_messages(results)
+      messages_by_id = Message.where(id: results.map(&:message_id))
+        .includes(:session).index_by(&:id)
+
+      count = 0
+      remaining = (Anima::Settings.token_budget * Anima::Settings.recall_budget_fraction).to_i
+
+      results.each do |result|
+        snippet = format_snippet(result, messages_by_id)
+        cost = Message.estimate_token_count(snippet.bytesize) + TOOL_PAIR_OVERHEAD_TOKENS
+        break if cost > remaining && count > 0
+
+        @session.pending_messages.create!(
+          content: snippet,
+          source_type: "recall",
+          source_name: result.message_id.to_s
+        )
+
+        remaining -= cost
+        count += 1
+      end
+
+      count
+    end
+
+    # Formats a search result as a compact snippet.
+    #
+    # @param result [Mneme::Search::Result]
+    # @param messages_by_id [Hash{Integer => Message}] pre-fetched messages
+    # @return [String]
+    def format_snippet(result, messages_by_id)
+      msg = messages_by_id[result.message_id]
+      session_label = msg&.session&.name || "session ##{result.session_id}"
+      content = result.snippet.truncate(Anima::Settings.recall_max_snippet_tokens * Message::BYTES_PER_TOKEN)
+      "message #{result.message_id} (#{session_label}): #{content}"
+    end
   end
 end

data/lib/mneme/runner.rb

@@ -148,13 +148,15 @@ module Mneme
       registry
     end
 
-    # Advances the terminal message pointer after Mneme completes.
+    # Advances the terminal message pointer past the zone Mneme just processed.
     # Runs unconditionally — even when the LLM called `everything_ok` (no snapshot
     # needed), the zone was reviewed and should be advanced past. Without this,
     # Mneme would re-examine the same mechanical-only content on every trigger.
     #
-    # Sets it to the last conversation message in the viewport, ensuring
-    # the boundary is always a message/think message, never a tool_call/tool_response.
+    # Sets the boundary to the first conversation/think message AFTER Mneme's
+    # viewport — the start of the remaining context. This creates the batch
+    # eviction cycle: the next Mneme trigger fires only after this boundary
+    # message itself falls out of the main viewport (~1/3 turnover later).
     # Also updates the snapshot range pointers.
     #
     # @param viewport [Mneme::CompressedViewport]
@@ -162,7 +164,16 @@ module Mneme
       viewport_messages = viewport.messages
       return if viewport_messages.empty?
 
-      new_boundary = viewport_messages.reverse_each.find { |message| conversation_or_think?(message) }
+      last_processed_id = viewport_messages.last.id
+      new_boundary = @session.messages
+        .where("id > ?", last_processed_id)
+        .where(message_type: Message::CONVERSATION_TYPES + ["tool_call"])
+        .order(:id)
+        .find_each { |msg| break msg if conversation_or_think?(msg) }
+
+      # Fall back to the last message in Mneme's viewport when no conversation
+      # messages exist beyond it (e.g. session went quiet after the zone).
+      new_boundary ||= viewport_messages.reverse_each.find { |msg| conversation_or_think?(msg) }
       return unless new_boundary
 
       boundary_id = new_boundary.id