anima-core 1.0.1 → 1.1.0

data/lib/llm/client.rb

@@ -15,6 +15,9 @@ module LLM
   #   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"
+
     # @return [Providers::Anthropic] the underlying API provider
     attr_reader :provider
 
@@ -61,13 +64,19 @@ module LLM
     # 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
+    # "Stopped by user" 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
     # @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] the assistant's final text response
+    # @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
 
@@ -78,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(",")}")
 
@@ -95,6 +108,11 @@ module LLM
             {role: "assistant", content: response["content"]},
             {role: "user", content: tool_results}
           ]
+
+          if interrupted?(session_id)
+            clear_interrupt!(session_id)
+            return nil
+          end
         else
           return extract_text(response)
         end
@@ -122,20 +140,43 @@ module LLM
     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)
-      extract_tool_uses(response).map do |tool_use|
-        execute_single_tool(tool_use, registry, session_id)
+      tool_uses = extract_tool_uses(response)
+      results = []
+
+      tool_uses.each_with_index do |tool_use, index|
+        if interrupted?(session_id)
+          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
 
-    # Executes a single tool and always returns a tool_result — even if
-    # the tool raises. The LLM requires every tool_use to have a matching
-    # tool_result; a missing result breaks the conversation permanently.
+    # Creates synthetic "Stopped by user" 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) }
+    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.
     def execute_single_tool(tool_use, registry, session_id)
       name = tool_use["name"]
       id = tool_use["id"]
@@ -155,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)}")
 
@@ -167,6 +209,49 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: result_content}
     end
 
+    # Creates a synthetic "Stopped by user" 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"]
+      input = tool_use["input"] || {}
+
+      Events::Bus.emit(Events::ToolCall.new(
+        content: "Skipped #{name} (interrupted)", 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 the database for a pending interrupt flag on the session.
+    #
+    # @param session_id [Integer, String] session to check
+    # @return [Boolean] whether the session has a pending interrupt request
+    def interrupted?(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.
+    #
+    # @param session_id [Integer, String] session to clear
+    # @return [void]
+    def clear_interrupt!(session_id)
+      Session.where(id: session_id).update_all(interrupt_requested: false)
+    end
+
     def log(level, message)
       return unless @logger
 

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

data/lib/mneme/passive_recall.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # 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.
+  #
+  # @example Trigger after a goal update
+  #   Mneme::PassiveRecall.new(session).call
+  class PassiveRecall
+    # @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.
+    #
+    # @return [Array<Mneme::Search::Result>] deduplicated, relevance-sorted
+    def call
+      goals = @session.goals.active.root.includes(:sub_goals)
+      return [] if goals.empty?
+
+      search_terms = build_search_terms(goals)
+      return [] if search_terms.blank?
+
+      results = Mneme::Search.query(search_terms, limit: Anima::Settings.recall_max_results)
+
+      # Exclude events from the current session's viewport — no point recalling
+      # what the agent already sees.
+      viewport_ids = @session.viewport_event_ids.to_set
+      results.reject { |result| viewport_ids.include?(result.event_id) }
+    end
+
+    private
+
+    STOP_WORDS = Set.new(%w[
+      a an the is are was were be been being do does did
+      have has had in on at to for of and or but not with
+      this that it its by from as up out if about into
+      fix add create update remove implement check set get
+    ]).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
+    def build_search_terms(goals)
+      descriptions = goals.flat_map { |goal|
+        [goal.description] + goal.sub_goals.reject(&:completed?).map(&:description)
+      }
+
+      words = descriptions.join(" ")
+        .gsub(/[^a-zA-Z0-9\s-]/, "")
+        .downcase
+        .split
+        .uniq
+        .reject { |word| STOP_WORDS.include?(word) || word.length < 3 }
+
+      words.join(" OR ").truncate(500)
+    end
+  end
+end