anima-core 1.0.1 → 1.1.0

data/lib/anima/config_migrator.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+require "pathname"
+
+module Anima
+  # Merges new default settings into an existing config.toml without
+  # overwriting user-customized values.
+  #
+  # Preserves the user's formatting and comments by extracting text blocks
+  # from the template and appending them to the config file. Missing entire
+  # sections are appended with their separator comments; missing keys within
+  # existing sections are inserted at the end of the section.
+  #
+  # @example
+  #   result = ConfigMigrator.new.run
+  #   result.status    #=> :updated
+  #   result.additions #=> [#<Addition section="paths" key="soul" value="/home/...">]
+  class ConfigMigrator
+    ANIMA_HOME = File.expand_path("~/.anima")
+    TEMPLATE_PATH = File.expand_path("../../templates/config.toml", __dir__).freeze
+
+    # A single config key that was added during migration.
+    # @!attribute [r] section [String] TOML section name
+    # @!attribute [r] key [String] key name within the section
+    # @!attribute [r] value [Object] default value from the template
+    Addition = Data.define(:section, :key, :value)
+
+    # Outcome of a migration run.
+    # @!attribute [r] status [Symbol] :not_found, :up_to_date, or :updated
+    # @!attribute [r] additions [Array<Addition>] keys that were added
+    Result = Data.define(:status, :additions)
+
+    # Section separator pattern used in the template (e.g. "# ─── LLM ───...").
+    SEPARATOR_PATTERN = /^# ─── /
+
+    # @param config_path [String] path to the user's config.toml
+    # @param template_path [String] path to the default config template
+    # @param anima_home [String] expanded path to ~/.anima (for template interpolation)
+    def initialize(config_path: File.join(ANIMA_HOME, "config.toml"),
+      template_path: TEMPLATE_PATH,
+      anima_home: ANIMA_HOME)
+      @config_path = Pathname.new(config_path)
+      @template_path = Pathname.new(template_path)
+      @anima_home = anima_home
+    end
+
+    # Merge missing settings from the template into the user's config.
+    #
+    # @return [Result] status (:not_found, :up_to_date, :updated) and additions list
+    def run
+      return Result.new(status: :not_found, additions: []) unless @config_path.exist?
+
+      template_text = resolve_template
+      template_config = TomlRB.parse(template_text)
+      user_config = TomlRB.load_file(@config_path.to_s)
+
+      additions = find_additions(user_config, template_config)
+      return Result.new(status: :up_to_date, additions: []) if additions.empty?
+
+      apply_additions(additions, template_text)
+      Result.new(status: :updated, additions: additions)
+    end
+
+    private
+
+    # Replace template placeholders with actual paths.
+    def resolve_template
+      File.read(@template_path.to_s).gsub("{{ANIMA_HOME}}") { @anima_home }
+    end
+
+    # Compare user config against template defaults.
+    # Returns additions for keys present in template but absent from user config.
+    def find_additions(user, template)
+      template.flat_map do |section, keys|
+        missing_keys_in_section(user, section, keys)
+      end
+    end
+
+    def missing_keys_in_section(user, section, keys)
+      keys.filter_map do |key, value|
+        next if user.key?(section) && user[section].key?(key)
+
+        Addition.new(section: section, key: key, value: value)
+      end
+    end
+
+    # Write missing settings into the user's config file, preserving existing content.
+    def apply_additions(additions, template_text)
+      user_text = @config_path.read
+      template_blocks = parse_section_blocks(template_text)
+
+      missing_sections, missing_keys = additions.partition do |addition|
+        !user_text.match?(/^\[#{Regexp.escape(addition.section)}\]/)
+      end
+
+      user_text = append_missing_sections(user_text, missing_sections, template_blocks)
+      user_text = insert_missing_keys(user_text, missing_keys, template_text)
+
+      @config_path.write(user_text)
+    end
+
+    def append_missing_sections(user_text, missing_sections, template_blocks)
+      missing_sections.map(&:section).uniq.each do |section|
+        block = template_blocks[section]
+        next unless block
+
+        user_text = "#{user_text.rstrip}\n\n#{block.rstrip}\n"
+      end
+      user_text
+    end
+
+    def insert_missing_keys(user_text, missing_keys, template_text)
+      missing_keys.each do |addition|
+        section = addition.section
+        key_block = extract_key_block(template_text, section, addition.key)
+        next unless key_block
+
+        user_text = insert_key_in_section(user_text, section, key_block)
+      end
+      user_text
+    end
+
+    # Split template into section blocks keyed by TOML section name.
+    # Each block spans from its separator comment to the next separator (exclusive).
+    def parse_section_blocks(template_text)
+      lines = template_text.lines
+      separator_indices = lines.each_index.select { |idx| lines[idx].match?(SEPARATOR_PATTERN) }
+      block_ranges = build_block_ranges(separator_indices, lines.length)
+
+      block_ranges.each_with_object({}) do |(start_idx, end_idx), blocks|
+        block_lines = lines[start_idx..end_idx]
+        section_name = extract_section_name(block_lines)
+        blocks[section_name] = block_lines.join if section_name
+      end
+    end
+
+    # Find the TOML section name (e.g. "llm") within a block of lines.
+    def extract_section_name(block_lines)
+      header = block_lines.find { |line| line.match?(/^\[\w+\]/) }
+      header&.match(/^\[(\w+)\]/)&.[](1)
+    end
+
+    # Build [start, end] pairs from separator indices.
+    def build_block_ranges(separator_indices, total_lines)
+      separator_indices.each_with_index.map do |start_idx, position|
+        next_pos = position + 1
+        end_idx = (next_pos < separator_indices.length) ? separator_indices[next_pos] - 1 : total_lines - 1
+        [start_idx, end_idx]
+      end
+    end
+
+    # Extract a single key and its preceding comment lines from the template.
+    def extract_key_block(template_text, section, key)
+      lines = template_text.lines
+      in_section = false
+
+      lines.each_with_index do |line, line_idx|
+        if line.match?(/^\[#{Regexp.escape(section)}\]/)
+          in_section = true
+        elsif line.match?(/^\[/) && in_section
+          break
+        elsif in_section && line.match?(/^#{Regexp.escape(key)}\s*=/)
+          return build_key_block(lines, line_idx)
+        end
+      end
+      nil
+    end
+
+    # Walk backward from a key line to collect preceding comment lines.
+    def build_key_block(lines, key_idx)
+      comment_start = key_idx
+      scan_idx = key_idx - 1
+      while scan_idx >= 0 && lines[scan_idx].match?(/^#/)
+        comment_start = scan_idx
+        scan_idx -= 1
+      end
+      "\n#{lines[comment_start..key_idx].join}"
+    end
+
+    # Insert a key block at the end of an existing section
+    # (before the next separator comment or EOF).
+    def insert_key_in_section(user_text, section, key_block)
+      lines = user_text.lines
+      insert_at = find_section_end(lines, section)
+      insert_at -= 1 while insert_at > 0 && lines[insert_at - 1].strip.empty?
+
+      lines.insert(insert_at, key_block)
+      lines.join
+    end
+
+    # Find the line index where a section ends (next separator or section header).
+    def find_section_end(lines, section)
+      in_section = false
+      lines.each_with_index do |line, line_idx|
+        if line.match?(/^\[#{Regexp.escape(section)}\]/)
+          in_section = true
+        elsif in_section && (line.match?(SEPARATOR_PATTERN) || line.match?(/^\[/))
+          return line_idx
+        end
+      end
+      lines.length
+    end
+  end
+end

data/lib/anima/installer.rb

@@ -75,124 +75,8 @@ module Anima
       config_path = anima_home.join("config.toml")
       return if config_path.exist?
 
-      config_path.write(<<~TOML)
-        # Anima Configuration
-        #
-        # Edit settings below to customize Anima's behavior.
-        # Changes take effect immediately — no restart needed.
-
-        # ─── LLM ───────────────────────────────────────────────────────
-
-        [llm]
-
-        # Primary model for conversations.
-        model = "claude-sonnet-4-20250514"
-
-        # Lightweight model for fast tasks (e.g. session naming).
-        fast_model = "claude-haiku-4-5"
-
-        # Maximum tokens per LLM response.
-        max_tokens = 8192
-
-        # Maximum consecutive tool execution rounds per request.
-        max_tool_rounds = 25
-
-        # Context window budget — tokens reserved for conversation history.
-        # Set this based on your model's context window minus system prompt.
-        token_budget = 190_000
-
-        # ─── Timeouts (seconds) ─────────────────────────────────────────
-
-        [timeouts]
-
-        # LLM API request timeout.
-        api = 30
-
-        # Shell command execution timeout.
-        command = 30
-
-        # MCP server response timeout.
-        mcp_response = 60
-
-        # Web fetch request timeout.
-        web_request = 10
-
-        # ─── Shell ──────────────────────────────────────────────────────
-
-        [shell]
-
-        # Maximum bytes of command output before truncation.
-        max_output_bytes = 100_000
-
-        # ─── Tools ──────────────────────────────────────────────────────
-
-        [tools]
-
-        # Maximum file size for read/edit operations (bytes).
-        max_file_size = 10_485_760
-
-        # Maximum lines returned by the read tool.
-        max_read_lines = 2_000
-
-        # Maximum bytes returned by the read tool.
-        max_read_bytes = 50_000
-
-        # Maximum bytes from web GET responses.
-        max_web_response_bytes = 100_000
-
-        # ─── Environment ──────────────────────────────────────────────
-
-        [environment]
-
-        # Files to scan for in the working directory (at root and up to project_files_max_depth subdirectories deep).
-        project_files = ["CLAUDE.md", "AGENTS.md", "README.md", "CONTRIBUTING.md"]
-
-        # Maximum directory depth for project file scanning.
-        project_files_max_depth = 3
-
-        # ─── GitHub ─────────────────────────────────────────────────────
-
-        [github]
-
-        # Repository for agent feature requests (owner/repo format).
-        # Falls back to parsing git remote origin when unset.
-        repo = "hoblin/anima"
-
-        # Label applied to agent-created feature request issues.
-        label = "anima-wants"
-
-        # ─── Paths ─────────────────────────────────────────────────────
-
-        [paths]
-
-        # The agent's self-authored identity file.
-        soul = "#{anima_home.join("soul.md")}"
-
-        # ─── Session ────────────────────────────────────────────────────
-
-        [session]
-
-        # Regenerate session name every N messages.
-        name_generation_interval = 30
-
-        # ─── Analytical Brain ─────────────────────────────────────────
-
-        [analytical_brain]
-
-        # Maximum tokens per analytical brain response.
-        # Must accommodate multiple tool calls (rename + goals + skills + ready).
-        max_tokens = 4096
-
-        # Run the analytical brain synchronously before the main agent on user messages.
-        # Ensures activated skills are available for the current response.
-        blocking_on_user_message = true
-
-        # Run the analytical brain asynchronously after the main agent completes.
-        blocking_on_agent_message = false
-
-        # Number of recent events to include in the analytical brain's context window.
-        event_window = 20
-      TOML
+      template = File.read(File.join(TEMPLATE_DIR, "config.toml"))
+      config_path.write(template.gsub("{{ANIMA_HOME}}") { anima_home.to_s })
       say "  created #{config_path}"
     end
 
@@ -231,19 +115,22 @@ module Anima
 
         next if key_path.exist? && content_path.exist?
 
+        content_str = content_path.to_s
+        key_str = key_path.to_s
+
         key = ActiveSupport::EncryptedFile.generate_key
         key_path.write(key)
-        File.chmod(0o600, key_path.to_s)
+        File.chmod(0o600, key_str)
 
         config = ActiveSupport::EncryptedConfiguration.new(
-          config_path: content_path.to_s,
-          key_path: key_path.to_s,
+          config_path: content_str,
+          key_path: key_str,
           env_key: "RAILS_MASTER_KEY",
           raise_if_missing_key: true
         )
 
         config.write("secret_key_base: #{SecureRandom.hex(64)}\n")
-        File.chmod(0o600, content_path.to_s)
+        File.chmod(0o600, content_str)
         say "  created credentials for #{env}"
       end
     end
@@ -269,16 +156,12 @@ module Anima
         WantedBy=default.target
       UNIT
 
-      if service_path.exist?
-        if service_path.read == unit_content
-          say "  anima.service unchanged"
-        else
-          service_path.write(unit_content)
-          say "  updated #{service_path}"
-        end
+      already_exists = service_path.exist?
+      if already_exists && service_path.read == unit_content
+        say "  anima.service unchanged"
       else
         service_path.write(unit_content)
-        say "  created #{service_path}"
+        say "  #{already_exists ? "updated" : "created"} #{service_path}"
       end
 
       system("systemctl", "--user", "daemon-reload", err: File::NULL, out: File::NULL)

data/lib/anima/settings.rb

@@ -177,6 +177,47 @@ module Anima
       # @return [Integer]
       def analytical_brain_event_window = get("analytical_brain", "event_window")
 
+      # ─── Mneme (Memory Department) ────────────────────────────────
+
+      # Maximum tokens per Mneme LLM response.
+      # @return [Integer]
+      def mneme_max_tokens = get("mneme", "max_tokens")
+
+      # Fraction of the main viewport token budget allocated to Mneme's viewport.
+      # @return [Float]
+      def mneme_viewport_fraction = get("mneme", "viewport_fraction")
+
+      # Fraction of the main viewport token budget reserved for L1 snapshots.
+      # @return [Float]
+      def mneme_l1_budget_fraction = get("mneme", "l1_budget_fraction")
+
+      # Fraction of the main viewport token budget reserved for L2 snapshots.
+      # @return [Float]
+      def mneme_l2_budget_fraction = get("mneme", "l2_budget_fraction")
+
+      # Number of uncovered L1 snapshots that triggers L2 compression.
+      # @return [Integer]
+      def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")
+
+      # Fraction of the main viewport token budget reserved for pinned events.
+      # Pinned events appear between snapshots and the sliding window.
+      # @return [Float]
+      def mneme_pinned_budget_fraction = get("mneme", "pinned_budget_fraction")
+
+      # ─── Recall (Associative Memory) ────────────────────────────
+
+      # Maximum search results returned per FTS5 query.
+      # @return [Integer]
+      def recall_max_results = get("recall", "max_results")
+
+      # Fraction of the main viewport token budget reserved for recalled memories.
+      # @return [Float]
+      def recall_budget_fraction = get("recall", "budget_fraction")
+
+      # Maximum tokens per individual recall snippet.
+      # @return [Integer]
+      def recall_max_snippet_tokens = get("recall", "max_snippet_tokens")
+
       private
 
       # Reads a setting from the config file.
@@ -191,7 +232,7 @@ module Anima
         value = config.dig(section, key)
         if value.nil?
           raise MissingSettingError,
-            "[#{section}] #{key} is not set in #{config_path}. Run `anima install` to create the config file."
+            "[#{section}] #{key} is not set in #{config_path}. Run `anima update` to add missing settings."
         end
         value
       end

data/lib/anima/version.rb

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

data/lib/events/bounce_back.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Events
+  # Transient failure event emitted when LLM delivery fails inside the
+  # Bounce Back transaction. The user event record is rolled back, and
+  # this event notifies clients to remove the phantom message and
+  # restore the text to the input field.
+  #
+  # Not persisted — not included in {Event::TYPES}.
+  class BounceBack < Base
+    TYPE = "bounce_back"
+
+    # @return [String] human-readable error description
+    attr_reader :error
+
+    # @return [Integer, nil] database ID of the rolled-back event (for client-side removal)
+    attr_reader :event_id
+
+    # @param content [String] original user message text to restore to input
+    # @param error [String] error description for the flash message
+    # @param session_id [Integer] session the message was intended for
+    # @param event_id [Integer, nil] ID of the event that was broadcast optimistically
+    def initialize(content:, error:, session_id:, event_id: nil)
+      super(content: content, session_id: session_id)
+      @error = error
+      @event_id = event_id
+    end
+
+    def type
+      TYPE
+    end
+
+    def to_h
+      super.merge(error: error, event_id: event_id)
+    end
+  end
+end

data/lib/events/subscribers/agent_dispatcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Reacts to non-pending {Events::UserMessage} emissions by scheduling
+    # {AgentRequestJob}. This is the event-driven bridge between the
+    # channel (which emits the intent) and the job (which persists and
+    # delivers the message).
+    #
+    # Pending messages are skipped — they are picked up by the running
+    # agent loop after it finishes the current turn.
+    class AgentDispatcher
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+        return unless payload[:type] == "user_message"
+        return if payload[:status] == Event::PENDING_STATUS
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        AgentRequestJob.perform_later(session_id, content: payload[:content])
+      end
+    end
+  end
+end

data/lib/events/subscribers/persister.rb

@@ -27,6 +27,12 @@ module Events
       end
 
       # Receives a Rails.event notification hash and persists it.
+      #
+      # Skips non-pending user messages — those are persisted by
+      # {AgentRequestJob} inside a transaction with LLM delivery
+      # (Bounce Back, #236). Also skips event types not in {Event::TYPES}
+      # (transient events like {Events::BounceBack}).
+      #
       # @param event [Hash] with :payload containing event data
       def emit(event)
         payload = event[:payload]
@@ -34,6 +40,8 @@ module Events
 
         event_type = payload[:type]
         return if event_type.nil?
+        return unless Event::TYPES.include?(event_type)
+        return if persisted_by_job?(event_type, payload)
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
@@ -52,6 +60,15 @@ module Events
       def session=(new_session)
         @mutex.synchronize { @session = new_session }
       end
+
+      private
+
+      # Non-pending user messages are persisted by {AgentRequestJob} inside
+      # a transaction with LLM delivery. Pending messages are still
+      # auto-persisted here because they queue while the session is busy.
+      def persisted_by_job?(event_type, payload)
+        event_type == "user_message" && payload[:status] != Event::PENDING_STATUS
+      end
     end
   end
 end

data/lib/events/subscribers/subagent_message_router.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Routes text messages between parent and child sessions, enabling
+    # 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}.
+    #
+    # **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.
+    #
+    # This replaces the +return_result+ tool — sub-agents communicate
+    # through natural text messages instead of structured tool calls.
+    class SubagentMessageRouter
+      include Events::Subscriber
+
+      # Attribution prefix format for messages routed from child to parent.
+      # @example "[sub-agent @loop-sleuth]: Here's what I found..."
+      ATTRIBUTION_FORMAT = "[sub-agent @%s]: %s"
+
+      # Regex to extract @mention names from parent agent messages.
+      MENTION_PATTERN = /@(\w[\w-]*)/
+
+      # Routes agent text messages between parent and child sessions.
+      #
+      # For sub-agent sessions: forwards to parent with attribution prefix.
+      # For parent sessions: scans for @mentions and routes to matching children.
+      #
+      # @param event [Hash] Rails.event notification hash with +:payload+ containing
+      #   an +agent_message+ event (type, session_id, content)
+      # @return [void]
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+        return unless payload[:type] == "agent_message"
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        content = payload[:content].to_s
+        return if content.empty?
+
+        session = Session.find_by(id: session_id)
+        return unless session
+
+        if session.sub_agent?
+          route_to_parent(session, content)
+        else
+          route_mentions_to_children(session, content)
+        end
+      end
+
+      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.
+      #
+      # @param child [Session] the sub-agent session
+      # @param content [String] the sub-agent's message text
+      def route_to_parent(child, content)
+        parent = child.parent_session
+        return unless parent
+
+        name = child.name || "agent-#{child.id}"
+        attributed = format(ATTRIBUTION_FORMAT, name, content)
+
+        parent.create_user_event(attributed)
+        AgentRequestJob.perform_later(parent.id)
+      end
+
+      # Scans a parent agent's message for @mentions and routes the message
+      # to each mentioned child session.
+      #
+      # @param parent [Session] the parent session
+      # @param content [String] the parent agent's message text
+      def route_mentions_to_children(parent, content)
+        mentioned_names = content.scan(MENTION_PATTERN).flatten.uniq
+        return if mentioned_names.empty?
+
+        active_children = parent.child_sessions.where.not(name: nil).index_by(&:name)
+        return if active_children.empty?
+
+        mentioned_names.each do |name|
+          child = active_children[name]
+          next unless child
+
+          child.create_user_event(content)
+          AgentRequestJob.perform_later(child.id)
+        end
+      end
+    end
+  end
+end

data/lib/events/subscribers/transient_broadcaster.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Bridges transient (non-persisted) events to ActionCable so clients
+    # receive them over WebSocket. Persisted events reach clients via
+    # {Event::Broadcasting} callbacks; this subscriber handles events
+    # that never touch the database.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::TransientBroadcaster.new)
+    class TransientBroadcaster
+      include Events::Subscriber
+
+      # Event types that are broadcast without persistence.
+      TRANSIENT_TYPES = [Events::BounceBack::TYPE].freeze
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+
+        event_type = payload[:type]
+        return unless TRANSIENT_TYPES.include?(event_type)
+
+        session_id = payload[:session_id]
+        return unless session_id
+
+        ActionCable.server.broadcast(
+          "session_#{session_id}",
+          payload.transform_keys(&:to_s)
+        )
+      end
+    end
+  end
+end