anima-core 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19dbc9d1eaa160cc21e98ad347f86968ad4ce5cb31f2bc3024844a1e0cd3c8e4
-  data.tar.gz: 280f6848271d0c97958dddc467543bb4b747c5a1e8a2e417f0c88e21b9612f4e
+  metadata.gz: 583896eaa09036e71d6e6b6ee013a021965acc193340ba735e4c0a0a6be6e6dc
+  data.tar.gz: f1f173f5129c37785a01119daa3cce27a0b935e0fdac256ffb0b412aad87483c
 SHA512:
-  metadata.gz: 9c43ec74eabd07e8ce2be3f8961e67f16858f2de20e828730f10b00dafe9cf2e3e9f3e96ed018718283d2093ae20bd0933931ce9807c29959b95b1f8c2a9a17c
-  data.tar.gz: 6bcb6b84581afb310b98899a40d2aa04d87cbcbd7790970fa9053c817886580eab5fe73f39a37944c7421ef9c190e5be26ffd2abac28a0afd7306dae5e2f19da
+  metadata.gz: 312effa8e79b480bd33a78093f192d6a6997fc0430aac6fe09528da0c95461feade771b3ecbcd13c0b7ad036d8a1c4cd2e6a443da61332baf3a8b34c57626ca5
+  data.tar.gz: 7c3578adb7158f0c32caa7f26ec3ea4d8189502e0bab27b0070f7a98a6423c6d311ddcd429edb7d451dadecd4282b5c7e874b6ce302fccdd1337103034eee1d2

data/.reek.yml

@@ -39,6 +39,10 @@ detectors:
       - "Tools::SubagentPrompts#assign_nickname_via_brain"
       # Validation methods naturally reference the validated value more than self.
       - "AnalyticalBrain::Tools::AssignNickname#validate"
+      # Tool execute methods naturally reference input hash and shell result hash.
+      - "Tools::Bash#execute"
+      - "Tools::Bash#execute_single"
+      - "Tools::Bash#execute_batch"
       # Delivery method orchestrates session, event, and agent_loop — inherent.
       - "AgentRequestJob#deliver_persisted_event"
   # Private helpers don't need instance state to be valid.
@@ -77,9 +81,11 @@ detectors:
       # Runner checks session type to compose responsibilities — the core dispatch.
       - "AnalyticalBrain::Runner"
   # EventDecorator holds shared rendering constants (icons, markers, dispatch maps).
+  # Event model holds domain type constants (TYPES, CONTEXT_TYPES, SPAWN_TOOLS, etc.).
   TooManyConstants:
     exclude:
       - "EventDecorator"
+      - "Event"
   # encode_utf8 is descriptive — the digit triggers a false positive.
   UncommunicativeMethodName:
     exclude:

data/app/channels/session_channel.rb

@@ -51,6 +51,7 @@ class SessionChannel < ApplicationCable::Channel
   # until the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
+  # @see Session#enqueue_user_message
   def speak(data)
     content = data["content"].to_s.strip
     return if content.empty?
@@ -58,12 +59,7 @@ class SessionChannel < ApplicationCable::Channel
     session = Session.find_by(id: @current_session_id)
     return unless session
 
-    if session.processing?
-      Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id, status: Event::PENDING_STATUS))
-    else
-      event = session.create_user_event(content)
-      AgentRequestJob.perform_later(session.id, event_id: event.id)
-    end
+    session.enqueue_user_message(content, bounce_back: true)
   end
 
   # Recalls the most recent pending message for editing. Deletes the

data/app/models/event.rb

@@ -14,7 +14,9 @@
 # @!attribute token_count
 #   @return [Integer] cached token count for this event's payload (0 until counted)
 # @!attribute tool_use_id
-#   @return [String, nil] Anthropic-assigned ID correlating tool_call and tool_response
+#   @return [String] ID correlating tool_call and tool_response events
+#     (Anthropic-assigned, or a SecureRandom.uuid fallback when the API returns nil;
+#     required for tool_call and tool_response events)
 class Event < ApplicationRecord
   include Event::Broadcasting
 
@@ -23,8 +25,12 @@ class Event < ApplicationRecord
   CONTEXT_TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   CONVERSATION_TYPES = %w[user_message agent_message system_message].freeze
   THINK_TOOL = "think"
+  SPAWN_TOOLS = %w[spawn_subagent spawn_specialist].freeze
   PENDING_STATUS = "pending"
 
+  # Event types that require a tool_use_id to pair call with response.
+  TOOL_TYPES = %w[tool_call tool_response].freeze
+
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
 
   # Heuristic: average bytes per token for English prose.
@@ -36,6 +42,8 @@ class Event < ApplicationRecord
   validates :event_type, presence: true, inclusion: {in: TYPES}
   validates :payload, presence: true
   validates :timestamp, presence: true
+  # Anthropic requires every tool_use to have a matching tool_result with the same ID
+  validates :tool_use_id, presence: true, if: -> { event_type.in?(TOOL_TYPES) }
 
   after_create :schedule_token_count, if: :llm_message?
 
@@ -60,6 +68,17 @@ class Event < ApplicationRecord
   #   @return [ActiveRecord::Relation]
   scope :deliverable, -> { where(status: nil) }
 
+  # @!method self.excluding_spawn_events
+  #   Excludes spawn_subagent/spawn_specialist tool_call and tool_response events.
+  #   Used when building parent context for sub-agents — spawn events cause role
+  #   confusion because the sub-agent sees sibling spawn results and mistakes
+  #   itself for the parent.
+  #   @return [ActiveRecord::Relation]
+  scope :excluding_spawn_events, -> {
+    where.not("event_type IN (?) AND json_extract(payload, '$.tool_name') IN (?)",
+      TOOL_TYPES, SPAWN_TOOLS)
+  }
+
   # Maps event_type to the Anthropic Messages API role.
   # @return [String] "user" or "assistant"
   def api_role
@@ -94,7 +113,7 @@ class Event < ApplicationRecord
   #
   # @return [Integer] estimated token count (at least 1)
   def estimate_tokens
-    text = if event_type.in?(%w[tool_call tool_response])
+    text = if event_type.in?(TOOL_TYPES)
       payload.to_json
     else
       payload["content"].to_s

data/app/models/session.rb

@@ -294,8 +294,8 @@ class Session < ApplicationRecord
   # @return [Integer] number of synthetic responses created
   def heal_orphaned_tool_calls!
     now_ns = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
-    responded_ids = events.where(event_type: "tool_response").where.not(tool_use_id: nil).select(:tool_use_id)
-    unresponded = events.where(event_type: "tool_call").where.not(tool_use_id: nil)
+    responded_ids = events.where(event_type: "tool_response").select(:tool_use_id)
+    unresponded = events.where(event_type: "tool_call")
       .where.not(tool_use_id: responded_ids)
 
     healed = 0
@@ -321,8 +321,35 @@ class Session < ApplicationRecord
     healed
   end
 
-  # Creates a user message event record directly (bypasses EventBus+Persister).
-  # Used by {SessionChannel#speak} (immediate display), {AgentLoop#process},
+  # Delivers a user message respecting the session's processing state.
+  #
+  # When idle, persists the event directly and enqueues {AgentRequestJob}
+  # to process it. When mid-turn ({#processing?}), emits a pending
+  # {Events::UserMessage} via {Events::Bus} so it queues until the
+  # current agent loop completes — preventing interleaving between
+  # tool_use/tool_result pairs.
+  #
+  # @param content [String] user message text
+  # @param bounce_back [Boolean] when true, passes +event_id+ to the job
+  #   so failed LLM delivery triggers a {Events::BounceBack} (used by
+  #   {SessionChannel#speak} for immediate-display messages)
+  # @return [void]
+  def enqueue_user_message(content, bounce_back: false)
+    if processing?
+      Events::Bus.emit(Events::UserMessage.new(
+        content: content, session_id: id,
+        status: Event::PENDING_STATUS
+      ))
+    else
+      event = create_user_event(content)
+      job_args = bounce_back ? {event_id: event.id} : {}
+      AgentRequestJob.perform_later(id, **job_args)
+    end
+  end
+
+  # Persists a user message event directly, bypassing the pending queue.
+  #
+  # Used by {#enqueue_user_message} (idle path), {AgentLoop#process},
   # and sub-agent spawn tools ({Tools::SpawnSubagent}, {Tools::SpawnSpecialist})
   # because the global {Events::Subscribers::Persister} skips non-pending user
   # messages — these callers own the persistence lifecycle.
@@ -501,9 +528,14 @@ class Session < ApplicationRecord
   end
 
   # Scopes parent events created before this session's fork point.
+  # Excludes spawn tool events — sub-agents don't need to see sibling
+  # spawn pairs, which cause role confusion (the sub-agent mistakes
+  # itself for the parent when it sees "Specialist @sibling spawned...").
   # @return [ActiveRecord::Relation]
   def parent_event_scope(include_pending)
-    scope = parent_session.events.context_events.where(created_at: ...created_at)
+    scope = parent_session.events.context_events
+      .excluding_spawn_events
+      .where(created_at: ...created_at)
     include_pending ? scope : scope.deliverable
   end
 

data/lib/agent_loop.rb

@@ -129,6 +129,11 @@ class AgentLoop
   # @return [Array<Class<Tools::Base>>]
   STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember].freeze
 
+  # Tools that bypass {Session#granted_tools} filtering.
+  # The agent's reasoning depends on these regardless of task scope.
+  # @return [Array<Class<Tools::Base>>]
+  ALWAYS_GRANTED_TOOLS = [Tools::Think].freeze
+
   # Name-to-class mapping for tool restriction validation and registry building.
   # @return [Hash{String => Class<Tools::Base>}]
   STANDARD_TOOLS_BY_NAME = STANDARD_TOOLS.index_by(&:tool_name).freeze
@@ -194,12 +199,15 @@ class AgentLoop
 
   # Standard tools available to this session.
   # Returns all when {Session#granted_tools} is nil (no restriction).
-  # Returns only matching tools when granted_tools is an array.
+  # Returns only matching tools when granted_tools is an array,
+  # always including {ALWAYS_GRANTED_TOOLS}.
   #
   # @return [Array<Class<Tools::Base>>] tool classes to register
   def granted_standard_tools
-    return STANDARD_TOOLS unless @session.granted_tools
+    granted = @session.granted_tools
+    return STANDARD_TOOLS unless granted
 
-    @session.granted_tools.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+    explicitly_granted = granted.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+    (ALWAYS_GRANTED_TOOLS + explicitly_granted).uniq
   end
 end

data/lib/agents/registry.rb

@@ -37,7 +37,7 @@ module Agents
     # @return [self]
     def load_all
       load_directory(BUILTIN_DIR)
-      load_directory(USER_DIR)
+      load_directory(USER_DIR) unless Rails.env.test?
       self
     end
 

data/lib/anima/settings.rb

@@ -236,6 +236,10 @@ module Anima
       # @return [Integer]
       def recall_max_snippet_tokens = get("recall", "max_snippet_tokens")
 
+      # Recency decay factor for search ranking (0.0 = pure relevance).
+      # @return [Float]
+      def recall_recency_decay = get("recall", "recency_decay")
+
       private
 
       # Reads a setting from the config file.

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "1.1.2"
+  VERSION = "1.1.3"
 end

data/lib/events/subscribers/subagent_message_router.rb

@@ -6,16 +6,19 @@ module Events
     # bidirectional @mention communication.
     #
     # **Child → Parent:** When a sub-agent emits an {Events::AgentMessage},
-    # the router persists a {Events::UserMessage} in the parent session
-    # with attribution prefix, then wakes the parent via {AgentRequestJob}.
+    # 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}.
     #
     # **Parent → Child:** When a parent agent emits an {Events::AgentMessage}
     # containing `@name` mentions, the router persists the message in each
     # matching child session and wakes them via {AgentRequestJob}.
     #
-    # Both directions use direct persistence + job enqueue (same pattern as
-    # {Tools::SpawnSubagent#spawn_child}) to avoid conflicts with the global
-    # {Persister} which skips non-pending user messages.
+    # 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.
     #
     # This replaces the +return_result+ tool — sub-agents communicate
     # through natural text messages instead of structured tool calls.
@@ -60,9 +63,8 @@ module Events
 
       private
 
-      # Forwards a sub-agent's text message to its parent session.
-      # Persists directly and enqueues a job so the parent agent wakes
-      # up to process the message.
+      # Forwards a sub-agent's text message to its parent session
+      # via {Session#enqueue_user_message}.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text
@@ -73,8 +75,7 @@ module Events
         name = child.name || "agent-#{child.id}"
         attributed = format(ATTRIBUTION_FORMAT, name, content)
 
-        parent.create_user_event(attributed)
-        AgentRequestJob.perform_later(parent.id)
+        parent.enqueue_user_message(attributed)
       end
 
       # Scans a parent agent's message for @mentions and routes the message
@@ -93,8 +94,7 @@ module Events
           child = active_children[name]
           next unless child
 
-          child.create_user_event(content)
-          AgentRequestJob.perform_later(child.id)
+          child.enqueue_user_message(content)
         end
       end
     end

data/lib/llm/client.rb

@@ -177,9 +177,12 @@ module LLM
     # 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)
       name = tool_use["name"]
-      id = tool_use["id"]
+      id = tool_use["id"] || SecureRandom.uuid
       input = tool_use["input"] || {}
       timeout = input["timeout"] || Anima::Settings.tool_timeout
 
@@ -231,7 +234,7 @@ module LLM
     # @return [Hash] tool_result content block
     def interrupt_tool(tool_use, session_id)
       name = tool_use["name"]
-      id = tool_use["id"]
+      id = tool_use["id"] || SecureRandom.uuid
       input = tool_use["input"] || {}
 
       Events::Bus.emit(Events::ToolCall.new(

data/lib/mneme/search.rb

@@ -21,7 +21,7 @@ module Mneme
     # @!attribute session_id [Integer] the session owning this event
     # @!attribute snippet [String] highlighted excerpt from the matching content
     # @!attribute rank [Float] FTS5 relevance score (lower = more relevant)
-    # @!attribute event_type [String] one of Event::TYPES
+    # @!attribute event_type [String] friendly label: human, anima, system, or thought
     Result = Struct.new(:event_id, :session_id, :snippet, :rank, :event_type, keyword_init: true)
 
     # Searches event history for the given terms.
@@ -38,6 +38,7 @@ module Mneme
       @terms = sanitize_query(terms)
       @session_id = session_id
       @limit = limit
+      @recency_decay = Anima::Settings.recall_recency_decay
     end
 
     # @return [Array<Result>] ranked by relevance (best first)
@@ -55,15 +56,23 @@ module Mneme
     #
     # @return [Array<Hash>] raw database rows
     def execute_fts_query
-      if @session_id
-        connection.select_all(scoped_sql, "Mneme::Search", [@terms, @session_id, @limit]).to_a
+      sql = if @session_id
+        Arel.sql(scoped_sql, @recency_decay, @terms, @session_id, @limit)
       else
-        connection.select_all(global_sql, "Mneme::Search", [@terms, @limit]).to_a
+        Arel.sql(global_sql, @recency_decay, @terms, @limit)
       end
+
+      connection.select_all(sql, "Mneme::Search").to_a
     end
 
     # FTS5 query across all sessions.
     # Contentless FTS5 can't use snippet() — extract content from events directly.
+    #
+    # Ranking blends BM25 relevance with recency: rank is negative (more
+    # negative = better match), so dividing by a factor > 1 for older events
+    # moves them closer to zero (less relevant). At decay 0.3, a one-year-old
+    # result needs ~30% better keyword relevance to beat an identical match
+    # from today.
     def global_sql
       <<~SQL
         SELECT
@@ -76,7 +85,7 @@ module Mneme
             WHEN e.event_type = 'tool_call'
               THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
           END AS snippet,
-          rank
+          rank / (1.0 + ? * (julianday('now') - julianday(e.created_at)) / 365.0) AS rank
         FROM events_fts
         JOIN events e ON e.id = events_fts.rowid
         WHERE events_fts MATCH ?
@@ -98,7 +107,7 @@ module Mneme
             WHEN e.event_type = 'tool_call'
               THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
           END AS snippet,
-          rank
+          rank / (1.0 + ? * (julianday('now') - julianday(e.created_at)) / 365.0) AS rank
         FROM events_fts
         JOIN events e ON e.id = events_fts.rowid
         WHERE events_fts MATCH ?
@@ -108,17 +117,25 @@ module Mneme
       SQL
     end
 
+    FRIENDLY_EVENT_TYPES = {
+      "user_message" => "human",
+      "agent_message" => "anima",
+      "system_message" => "system",
+      "tool_call" => "thought"
+    }.freeze
+
     # Builds a Result from a raw database row.
     #
     # @param row [Hash]
     # @return [Result]
     def build_result(row)
+      raw_type = row["event_type"]
       Result.new(
         event_id: row["event_id"],
         session_id: row["session_id"],
         snippet: row["snippet"],
         rank: row["rank"],
-        event_type: row["event_type"]
+        event_type: FRIENDLY_EVENT_TYPES.fetch(raw_type, raw_type)
       )
     end
 

data/lib/skills/registry.rb

@@ -40,7 +40,7 @@ module Skills
     # @return [self]
     def load_all
       load_directory(BUILTIN_DIR)
-      load_directory(USER_DIR)
+      load_directory(USER_DIR) unless Rails.env.test?
       self
     end
 

data/lib/tools/bash.rb

@@ -6,19 +6,42 @@ module Tools
   # conversation. Output is truncated and timeouts are enforced by the
   # underlying session.
   #
+  # Supports two modes:
+  # - Single command via +command+ (string) — backward compatible
+  # - Batch via +commands+ (array) with +mode+ controlling error handling
+  #
   # @see ShellSession#run
   class Bash < Base
     def self.tool_name = "bash"
 
-    def self.description = "Execute a bash command. Working directory and environment persist across calls within a conversation."
+    def self.description
+      <<~DESC.squish
+        Execute a bash command. Working directory and environment persist across calls within a conversation.
+        Accepts either `command` (string) for a single command, or `commands` (array of strings) to run
+        multiple commands as a batch — each command gets its own timeout and result. Batch `mode` controls
+        error handling: "sequential" (default) stops on the first failure, "parallel" runs all regardless.
+      DESC
+    end
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          command: {type: "string", description: "The bash command to execute"}
-        },
-        required: ["command"]
+          command: {
+            type: "string",
+            description: "The bash command to execute"
+          },
+          commands: {
+            type: "array",
+            items: {type: "string"},
+            description: "Array of bash commands to execute as a batch. Each runs independently with its own timeout and result."
+          },
+          mode: {
+            type: "string",
+            enum: ["sequential", "parallel"],
+            description: 'Batch error handling: "sequential" (default) stops on first non-zero exit; "parallel" runs all commands regardless of failures.'
+          }
+        }
       }
     end
 
@@ -33,16 +56,76 @@ module Tools
     # @return [String] formatted output with stdout, stderr, and exit code
     # @return [Hash] with :error key on failure
     def execute(input)
-      command = input["command"].to_s
+      timeout = input["timeout"]
+      has_command = input.key?("command")
+      has_commands = input.key?("commands")
+
+      if has_command && has_commands
+        {error: "Provide either 'command' or 'commands', not both"}
+      elsif has_commands
+        execute_batch(input["commands"], mode: input.fetch("mode", "sequential"), timeout: timeout)
+      elsif has_command
+        execute_single(input["command"], timeout: timeout)
+      else
+        {error: "Either 'command' (string) or 'commands' (array of strings) is required"}
+      end
+    end
+
+    private
+
+    # Executes a single command — the original code path, preserved for backward compatibility.
+    def execute_single(command, timeout: nil)
+      command = command.to_s
       return {error: "Command cannot be blank"} if command.strip.empty?
 
-      result = @shell_session.run(command, timeout: input["timeout"])
+      result = @shell_session.run(command, timeout: timeout)
       return result if result.key?(:error)
 
       format_result(result[:stdout], result[:stderr], result[:exit_code])
     end
 
-    private
+    # Executes an array of commands, returning a combined result string.
+    # @param commands [Array<String>] commands to execute
+    # @param mode [String] "sequential" (stop on first failure) or "parallel" (run all)
+    # @param timeout [Integer, nil] per-command timeout override
+    # @return [String] combined results with per-command headers
+    # @return [Hash] with :error key if commands array is invalid
+    def execute_batch(commands, mode:, timeout: nil)
+      return {error: "Commands array cannot be empty"} unless commands.is_a?(Array) && commands.any?
+
+      total = commands.size
+      results = []
+      failed = false
+
+      commands.each_with_index do |command, index|
+        position = "[#{index + 1}/#{total}]"
+
+        if failed && mode == "sequential"
+          results << "#{position} $ #{command}\n(skipped)"
+          next
+        end
+
+        command = command.to_s
+        if command.strip.empty?
+          results << "#{position} $ (blank)\n(skipped — blank command)"
+          next
+        end
+
+        result = @shell_session.run(command, timeout: timeout)
+
+        if result.key?(:error)
+          results << "#{position} $ #{command}\n#{result[:error]}"
+          failed = true
+        else
+          exit_code = result[:exit_code]
+          output = format_result(result[:stdout], result[:stderr], exit_code)
+          results << "#{position} $ #{command}\n#{output}"
+          failed = true if exit_code != 0
+        end
+      end
+
+      results.join("\n\n")
+    end
 
     def format_result(stdout, stderr, exit_code)
       parts = []

data/lib/workflows/registry.rb

@@ -37,7 +37,7 @@ module Workflows
     # @return [self]
     def load_all
       load_directory(BUILTIN_DIR)
-      load_directory(USER_DIR)
+      load_directory(USER_DIR) unless Rails.env.test?
       self
     end
 

data/templates/config.toml

@@ -161,3 +161,9 @@ budget_fraction = 0.05
 
 # Maximum tokens per individual recall snippet.
 max_snippet_tokens = 512
+
+# Recency decay factor for search ranking. Blends FTS5 relevance with event
+# age so recent memories win ties. 0.0 = pure relevance, higher = stronger
+# recency bias. At 0.3 a one-year-old result needs ~30% better keyword
+# relevance to beat an identical match from today.
+recency_decay = 0.3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
 platform: ruby
 authors:
 - Yevhenii Hurin