anima-core 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161b7dfde73fa61f7656427c0af3c5919e1a1cc50d6b1a2d201f5a45ce79c561
-  data.tar.gz: 880538d54fbc682b61bbeb6d63b38aa066e86327c778fefce8e60091c6ad816d
+  metadata.gz: 583896eaa09036e71d6e6b6ee013a021965acc193340ba735e4c0a0a6be6e6dc
+  data.tar.gz: f1f173f5129c37785a01119daa3cce27a0b935e0fdac256ffb0b412aad87483c
 SHA512:
-  metadata.gz: f0ee765c1a125e26b9f10b5cc97f41e857ec17562ef4ba116dd53bf97b9b26fb3781d9f292c6296c1c408089d155d9d8a24e4165d58f57ead64e72595f833ae8
-  data.tar.gz: 86c95c9f103cb0c6c4b37ef3452662274205da97ef04d3f846f7f2d041ff0c94f375208b60d245f454aa73abb2c144113f9d6691cc99a0124f43971fcfb62ae1
+  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,15 @@ 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:
+      - "ToolDecorator#self.encode_utf8"
   # Abstract base class methods declare parameters for the subclass contract.
   UnusedParameters:
     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/decorators/tool_decorator.rb

@@ -21,19 +21,74 @@ class ToolDecorator
     "web_get" => "WebGetToolDecorator"
   }.freeze
 
-  # Factory: dispatches to the tool-specific decorator or passes through.
+  # Factory: dispatches to the tool-specific decorator, then sanitizes
+  # the result for safe LLM consumption.
+  #
+  # Sanitization guarantees the final string is UTF-8 encoded, free of
+  # ANSI escape codes, and stripped of control characters that carry no
+  # meaning for an LLM. This is the single gate — no tool or decorator
+  # subclass needs to think about encoding or terminal noise.
   #
   # @param tool_name [String] registered tool name
   # @param result [String, Hash] raw tool execution result
-  # @return [String, Hash] decorated result (String) or original error Hash
+  # @return [String, Hash] sanitized result (String) or original error Hash
   def self.call(tool_name, result)
     return result if result.is_a?(Hash) && result.key?(:error)
 
     klass_name = DECORATOR_MAP[tool_name]
-    return result unless klass_name
+    result = klass_name.constantize.new.call(result) if klass_name
+
+    sanitize_for_llm(result)
+  end
+
+  # Ensures a tool result string is safe for LLM consumption by
+  # composing {encode_utf8}, {strip_ansi}, and {strip_control_chars}.
+  #
+  # Non-string results pass through unchanged.
+  #
+  # @param result [String, Object] tool output to sanitize
+  # @return [String, Object] sanitized string or original object
+  def self.sanitize_for_llm(result)
+    return result unless result.is_a?(String)
+
+    strip_control_chars(strip_ansi(encode_utf8(result)))
+  end
+  private_class_method :sanitize_for_llm
 
-    klass_name.constantize.new.call(result)
+  # Force-encodes a string to UTF-8, replacing invalid or undefined
+  # bytes with the Unicode replacement character (U+FFFD).
+  #
+  # @param str [String] input in any encoding (commonly ASCII-8BIT from PTY)
+  # @return [String] valid UTF-8 string
+  def self.encode_utf8(str)
+    str.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\uFFFD")
+  end
+  private_class_method :encode_utf8
+
+  # CSI (colors, cursor, DEC private modes), OSC (terminal title),
+  # charset designation, single-char commands
+  ANSI_ESCAPE = /\e\[[?>=<0-9;]*[A-Za-z]|\e\][^\a\e]*(?:\a|\e\\)|\e[()][0-9A-Za-z]|\e[>=<78NOMDEHcn]/
+  private_constant :ANSI_ESCAPE
+
+  # Strips ANSI escape sequences that are meaningless noise to an LLM
+  # but can dominate terminal output payloads.
+  #
+  # @param str [String] UTF-8 string possibly containing escape codes
+  # @return [String] cleaned string
+  def self.strip_ansi(str)
+    str.gsub(ANSI_ESCAPE, "")
+  end
+  private_class_method :strip_ansi
+
+  # Strips C0 control characters (NUL, BEL, BS, CR, etc.) that carry
+  # no meaning for an LLM. Preserves newline (\n) and tab (\t).
+  #
+  # @param str [String] UTF-8 string possibly containing control chars
+  # @return [String] cleaned string
+  def self.strip_control_chars(str)
+    str.gsub(/[\x00-\x08\x0B-\x0D\x0E-\x1F\x7F]/, "")
   end
+  private_class_method :strip_control_chars
 
   # Subclasses override to transform the raw tool result.
   #

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.1"
+  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
 
@@ -191,13 +194,7 @@ module LLM
         session_id: session_id
       ))
 
-      result = begin
-        registry.execute(name, input)
-      rescue => error
-        Rails.logger.error("Tool #{name} raised #{error.class}: #{error.message}")
-        {error: "#{error.class}: #{error.message}"}
-      end
-
+      result = registry.execute(name, input)
       result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
@@ -209,6 +206,23 @@ module LLM
       ))
 
       {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 "Stopped by user" result for a tool that was not
@@ -220,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/shell_session.rb

@@ -390,10 +390,11 @@ class ShellSession
 
   def truncate(output)
     max_bytes = @max_output_bytes
+    output = output.dup.force_encoding("UTF-8").scrub
+
     return output if output.bytesize <= max_bytes
 
     output.byteslice(0, max_bytes)
-      .force_encoding("UTF-8")
       .scrub +
       "\n\n[Truncated: output exceeded #{max_bytes} bytes]"
   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.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Yevhenii Hurin