anima-core 1.2.0 → 1.4.0

data/lib/anima/cli.rb

@@ -39,21 +39,29 @@ module Anima
       end
 
       require_relative "config_migrator"
-      result = Spinner.run("Migrating configuration...") do
+
+      result = Spinner.run("Migrating brain configuration...") do
         Anima::ConfigMigrator.new.run
       end
-
-      case result.status
-      when :not_found
+      if result.status == :not_found
         say "Config file not found. Run 'anima install' first.", :red
         exit 1
-      when :up_to_date
-        say "  Config is already up to date."
-      when :updated
-        result.additions.each do |addition|
-          say "  added [#{addition.section}] #{addition.key} = #{addition.value.inspect}"
-        end
       end
+      report_migration("Config", result)
+
+      tui_config_path = File.join(Anima::ConfigMigrator::ANIMA_HOME, "tui.toml")
+      tui_template = File.expand_path("../../templates/tui.toml", __dir__)
+      unless File.exist?(tui_config_path)
+        File.write(tui_config_path, File.read(tui_template))
+        say "  created #{tui_config_path} (new in this version)"
+      end
+      tui_result = Spinner.run("Migrating TUI configuration...") do
+        Anima::ConfigMigrator.new(
+          config_path: tui_config_path,
+          template_path: tui_template
+        ).run
+      end
+      report_migration("TUI config", tui_result)
 
       restart_service_if_active
     end
@@ -83,13 +91,15 @@ module Anima
     end
 
     desc "tui", "Launch the Anima terminal interface"
-    option :host, desc: "Brain server address (default: #{DEFAULT_HOST})"
-    option :debug, type: :boolean, default: false, desc: "Enable performance logging to log/tui_performance.log"
+    option :host, desc: "Brain server address (default: from tui.toml or #{DEFAULT_HOST})"
+    option :debug, type: :boolean, default: false, desc: "Enable performance logging"
     def tui
       require "ratatui_ruby"
+      require_relative "../tui/settings"
       require_relative "../tui/app"
 
-      host = options[:host] || DEFAULT_HOST
+      TUI::Settings.load!
+      host = options[:host] || TUI::Settings.connection_default_host
 
       say "Connecting to brain at #{host}...", :cyan
 
@@ -111,6 +121,24 @@ module Anima
 
     private
 
+    # Reports the outcome of a config migration to the user.
+    #
+    # @param label [String] human-readable config name (e.g. "Config", "TUI config")
+    # @param result [Anima::ConfigMigrator::Result] migration outcome
+    # @return [void]
+    def report_migration(label, result)
+      case result.status
+      when :not_found
+        say "#{label} file not found. Run 'anima install' first.", :red
+      when :up_to_date
+        say "  #{label} is already up to date."
+      when :updated
+        result.additions.each do |addition|
+          say "  added [#{addition.section}] #{addition.key} = #{addition.value.inspect}"
+        end
+      end
+    end
+
     # Restarts the systemd user service so updated code takes effect.
     # Without this, the service continues running the old gem version
     # until manually restarted (see #269).

data/lib/anima/installer.rb

@@ -31,6 +31,7 @@ module Anima
       create_directories
       create_soul_file
       create_settings_config
+      create_tui_config
       create_mcp_config
       generate_credentials
       create_systemd_service
@@ -68,6 +69,18 @@ module Anima
       say "  created #{config_path}"
     end
 
+    # Creates ~/.anima/tui.toml — TUI-specific presentation settings.
+    # Separate from config.toml because the TUI is a standalone client
+    # process with no Rails dependency.
+    def create_tui_config
+      config_path = anima_home.join("tui.toml")
+      return if config_path.exist?
+
+      template = File.read(File.join(TEMPLATE_DIR, "tui.toml"))
+      config_path.write(template)
+      say "  created #{config_path}"
+    end
+
     def create_mcp_config
       config_path = anima_home.join("mcp.toml")
       return if config_path.exist?
@@ -117,7 +130,13 @@ module Anima
           raise_if_missing_key: true
         )
 
-        config.write("secret_key_base: #{SecureRandom.hex(64)}\n")
+        config.write(<<~YAML)
+          secret_key_base: #{SecureRandom.hex(64)}
+          active_record_encryption:
+            primary_key: #{SecureRandom.base64(32)}
+            deterministic_key: #{SecureRandom.base64(32)}
+            key_derivation_salt: #{SecureRandom.base64(32)}
+        YAML
         File.chmod(0o600, content_str)
         say "  created credentials for #{env}"
       end

data/lib/anima/settings.rb

@@ -91,6 +91,20 @@ module Anima
       # @return [Integer]
       def token_budget = get("llm", "token_budget")
 
+      # Maximum character length for the Think tool's thoughts parameter.
+      # Sub-agents receive half this budget (their tasks are less complex).
+      # @return [Integer]
+      def thinking_budget = get("llm", "thinking_budget")
+
+      # Model for sub-agent sessions. Sonnet is cost-effective for focused tasks.
+      # @return [String] Anthropic model identifier
+      def subagent_model = get("llm", "subagent_model")
+
+      # Context window budget for sub-agent sessions.
+      # Smaller than main to keep sub-agents out of the "dumb zone".
+      # @return [Integer]
+      def subagent_token_budget = get("llm", "subagent_token_budget")
+
       # ─── Timeouts (seconds) ────────────────────────────────────────
 
       # LLM API request timeout.
@@ -114,6 +128,13 @@ module Anima
       # @return [Integer] seconds
       def tool_timeout = get("timeouts", "tool")
 
+      # Polling interval for user interrupt checks during long-running commands.
+      # Enforces a 0.5s floor to prevent busy-polling from misconfiguration.
+      # @return [Numeric] seconds (minimum 0.5)
+      def interrupt_check_interval
+        [get("timeouts", "interrupt_check"), 0.5].max
+      end
+
       # ─── Shell ──────────────────────────────────────────────────────
 
       # Maximum bytes of command output before truncation.
@@ -126,11 +147,11 @@ module Anima
       # @return [Integer]
       def max_file_size = get("tools", "max_file_size")
 
-      # Maximum lines returned by the read tool.
+      # Maximum lines returned by the read_file tool.
       # @return [Integer]
       def max_read_lines = get("tools", "max_read_lines")
 
-      # Maximum bytes returned by the read tool.
+      # Maximum bytes returned by the read_file tool.
       # @return [Integer]
       def max_read_bytes = get("tools", "max_read_bytes")
 
@@ -142,6 +163,16 @@ module Anima
       # @return [Integer]
       def min_web_content_chars = get("tools", "min_web_content_chars")
 
+      # Maximum characters of tool output before head+tail truncation.
+      # Full output saved to a temp file for paginated reading.
+      # @return [Integer]
+      def max_tool_response_chars = get("tools", "max_tool_response_chars")
+
+      # Maximum characters of sub-agent result before head+tail truncation.
+      # Higher than tool threshold because sub-agent output is already curated.
+      # @return [Integer]
+      def max_subagent_response_chars = get("tools", "max_subagent_response_chars")
+
       # ─── Session ────────────────────────────────────────────────────
 
       # View mode applied to new sessions: "basic", "verbose", or "debug".
@@ -228,6 +259,10 @@ module Anima
       # @return [Integer]
       def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")
 
+      # Fraction of the viewport to evict in batch when Mneme runs.
+      # @return [Float]
+      def mneme_eviction_fraction = get("mneme", "eviction_fraction")
+
       # Fraction of the main viewport token budget reserved for pinned messages.
       # Pinned messages appear between snapshots and the sliding window.
       # @return [Float]

data/lib/anima/version.rb

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

data/lib/anima.rb

@@ -12,7 +12,7 @@ module Anima
   end
 
   # Boots Rails when CLI commands need access to Rails-managed resources
-  # like encrypted credentials. No-op if Rails is already loaded.
+  # like the encrypted secrets table. No-op if Rails is already loaded.
   def self.boot_rails!
     return if defined?(Rails)
 

data/lib/credential_store.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Low-level read/write operations on Rails encrypted credentials.
-# Wraps the merge-and-write pattern used by {SessionChannel#write_anthropic_token}
-# in a reusable helper. All namespacing (e.g. +mcp+, +anthropic+) is the
-# caller's responsibility — this class operates on raw top-level keys.
+# Read/write operations for runtime secrets (API tokens, MCP credentials).
+# Backed by the {Secret} model with Active Record Encryption — values are
+# encrypted at rest and always fresh (no caching, no file-path issues in
+# forked Solid Queue workers).
+#
+# All namespacing (e.g. +mcp+, +anthropic+) is the caller's responsibility.
 #
 # @example Writing a nested credential
 #   CredentialStore.write("mcp", "linear_api_key" => "sk-xxx")
@@ -13,91 +15,40 @@
 class CredentialStore
   class << self
     # Writes one or more key-value pairs under a top-level namespace.
-    # Merges into existing credentials, preserving sibling keys.
+    # Upserts: existing keys are updated, new keys are created.
     #
-    # @param namespace [String] top-level YAML key (e.g. "mcp", "anthropic")
+    # @param namespace [String] top-level grouping key (e.g. "mcp", "anthropic")
     # @param pairs [Hash<String, String>] key-value pairs to store
     # @return [void]
     def write(namespace, pairs)
-      existing = load_credentials
-      section = existing[namespace] ||= {}
-      section.merge!(pairs)
-      save_credentials(existing)
+      Secret.write(namespace, pairs)
     end
 
     # Reads a single credential value from a namespace.
-    # Busts the Rails credentials cache first so cross-process writes
-    # (e.g. token saved in the web process, read in the SolidQueue worker)
-    # are always visible.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key within the namespace
     # @return [String, nil] credential value or nil if not found
     def read(namespace, key)
-      bust_credentials_cache!
-      Rails.application.credentials.dig(namespace.to_sym, key.to_sym)
+      Secret.read(namespace, key)
     end
 
-    # Lists all keys under a namespace.
+    # Lists all keys under a namespace (not values).
     #
-    # @param namespace [String] top-level YAML key
-    # @return [Array<String>] credential keys (not values)
+    # @param namespace [String] top-level grouping key
+    # @return [Array<String>] credential keys
     def list(namespace)
-      section = Rails.application.credentials.dig(namespace.to_sym)
-      return [] unless section.is_a?(Hash)
-
-      section.keys.map(&:to_s)
+      Secret.list(namespace)
     end
 
     # Removes a single key from a namespace.
     # No-op if the key does not exist.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key to remove
     # @return [void]
     def remove(namespace, key)
-      existing = load_credentials
-      section = existing[namespace]
-      return unless section.is_a?(Hash)
-      return unless section.key?(key)
-
-      section.delete(key)
-      existing.delete(namespace) if section.empty?
-      save_credentials(existing)
-    end
-
-    private
-
-    # Reads and parses the raw YAML from encrypted credentials.
-    # Returns an empty hash when the credentials file does not exist yet.
-    #
-    # @return [Hash] parsed credentials
-    def load_credentials
-      creds = Rails.application.credentials
-      YAML.safe_load(creds.read) || {}
-    rescue ActiveSupport::EncryptedFile::MissingContentError
-      {}
-    end
-
-    # Writes the full credentials hash back to the encrypted file and
-    # invalidates the Rails memoization cache so subsequent reads see
-    # fresh data.
-    #
-    # @param data [Hash] complete credentials hash to persist
-    # @return [void]
-    def save_credentials(data)
-      creds = Rails.application.credentials
-      creds.write(data.to_yaml)
-      bust_credentials_cache!
-    end
-
-    # Clears the Rails credentials in-memory cache so the next access
-    # re-reads and decrypts from disk. Required because Rails memoizes
-    # the decrypted config in @config per-process.
-    #
-    # @return [void]
-    def bust_credentials_cache!
-      Rails.application.credentials.instance_variable_set(:@config, nil)
+      Secret.remove(namespace, key)
     end
   end
 end

data/lib/events/agent_message.rb

@@ -4,8 +4,22 @@ module Events
   class AgentMessage < Base
     TYPE = "agent_message"
 
+    attr_reader :api_metrics
+
+    # @param content [String] assistant response text
+    # @param session_id [Integer, String] session identifier
+    # @param api_metrics [Hash, nil] rate limits and usage from API response
+    def initialize(content:, session_id: nil, api_metrics: nil)
+      super(content: content, session_id: session_id)
+      @api_metrics = api_metrics
+    end
+
     def type
       TYPE
     end
+
+    def to_h
+      super.merge(api_metrics: api_metrics)
+    end
   end
 end

data/lib/events/base.rb

@@ -16,7 +16,7 @@ module Events
     def initialize(content:, session_id: nil)
       @content = content
       @session_id = session_id
-      @timestamp = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      @timestamp = Time.current.to_ns
     end
 
     # @return [String] event type identifier

data/lib/events/subscribers/persister.rb

@@ -9,6 +9,11 @@ module Events
     # session. When initialized without one (global mode), the session is
     # looked up from the event's session_id payload field.
     #
+    # User messages are NOT persisted here — they are created directly by
+    # their callers ({SessionChannel#speak}, {AgentLoop#run}) so the
+    # message ID is available for bounce-back cleanup. Pending user
+    # messages live in the {PendingMessage} table, outside the event bus.
+    #
     # @example Session-scoped
     #   persister = Events::Subscribers::Persister.new(session)
     #   Events::Bus.subscribe(persister)
@@ -28,10 +33,10 @@ module Events
 
       # Receives a Rails.event notification hash and persists it.
       #
-      # Skips non-pending user messages — those are persisted by their
-      # callers ({SessionChannel#speak} for idle sessions,
-      # {AgentLoop#process} for direct usage). Also skips event types
-      # not in {Message::TYPES} (transient events like {Events::BounceBack}).
+      # Skips user messages — those are persisted by their callers
+      # ({SessionChannel#speak}, {AgentLoop#run}). Also skips event
+      # types not in {Message::TYPES} (transient events like
+      # {Events::BounceBack}).
       #
       # @param event [Hash] with :payload containing event data
       def emit(event)
@@ -41,7 +46,7 @@ module Events
         event_type = payload[:type]
         return if event_type.nil?
         return unless Message::TYPES.include?(event_type)
-        return if persisted_by_job?(event_type, payload)
+        return if event_type == "user_message"
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
@@ -50,9 +55,9 @@ module Events
           target_session.messages.create!(
             message_type: event_type,
             payload: payload,
-            status: payload[:status],
             tool_use_id: payload[:tool_use_id],
-            timestamp: payload[:timestamp] || Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+            timestamp: payload[:timestamp] || Time.current.to_ns,
+            api_metrics: payload[:api_metrics]
           )
         end
       end
@@ -60,17 +65,6 @@ module Events
       def session=(new_session)
         @mutex.synchronize { @session = new_session }
       end
-
-      private
-
-      # Non-pending user messages are persisted by their callers
-      # ({SessionChannel#speak}, {AgentLoop#process}) so the message ID
-      # is available for bounce-back cleanup if LLM delivery fails.
-      # 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] != Message::PENDING_STATUS
-      end
     end
   end
 end

data/lib/events/subscribers/subagent_message_router.rb

@@ -14,7 +14,8 @@ module Events
     #
     # **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}.
+    # matching child session with a +[from parent]:+ origin label and wakes
+    # them via {AgentRequestJob}.
     #
     # Both directions delegate to {Session#enqueue_user_message}, which
     # respects the target session's processing state — persisting directly
@@ -25,9 +26,9 @@ module Events
     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"
+      # Origin label for messages routed from parent agent to sub-agent.
+      # Lets the sub-agent distinguish delegated work from direct user input.
+      PARENT_ATTRIBUTION_FORMAT = "[from parent]: %s"
 
       # Regex to extract @mention names from parent agent messages.
       MENTION_PATTERN = /@(\w[\w-]*)/
@@ -64,7 +65,9 @@ module Events
       private
 
       # Forwards a sub-agent's text message to its parent session
-      # via {Session#enqueue_user_message}.
+      # via {Session#enqueue_user_message} with source metadata.
+      # The parent's {PendingMessage} (or idle-path message) owns the
+      # attribution formatting — the router passes raw content.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text
@@ -73,13 +76,17 @@ module Events
         return unless parent
 
         name = child.name || "agent-#{child.id}"
-        attributed = format(ATTRIBUTION_FORMAT, name, content)
+        truncated = Tools::ResponseTruncator.truncate(
+          content,
+          threshold: Anima::Settings.max_subagent_response_chars,
+          reason: "sub-agent output displays first/last #{Tools::ResponseTruncator::HEAD_LINES} lines"
+        )
 
-        parent.enqueue_user_message(attributed)
+        parent.enqueue_user_message(truncated, source_type: "subagent", source_name: name)
       end
 
       # Scans a parent agent's message for @mentions and routes the message
-      # to each mentioned child session.
+      # to each mentioned child session with origin attribution.
       #
       # @param parent [Session] the parent session
       # @param content [String] the parent agent's message text
@@ -90,11 +97,13 @@ module Events
         active_children = parent.child_sessions.where.not(name: nil).index_by(&:name)
         return if active_children.empty?
 
+        attributed = format(PARENT_ATTRIBUTION_FORMAT, content)
+
         mentioned_names.each do |name|
           child = active_children[name]
           next unless child
 
-          child.enqueue_user_message(content)
+          child.enqueue_user_message(attributed)
         end
       end
     end

data/lib/events/user_message.rb

@@ -4,25 +4,14 @@ module Events
   class UserMessage < Base
     TYPE = "user_message"
 
-    # @return [String, nil] "pending" when queued during active processing, nil otherwise
-    attr_reader :status
-
     # @param content [String] message text
     # @param session_id [Integer, nil] session identifier
-    # @param status [String, nil] "pending" when queued during active agent processing
-    def initialize(content:, session_id: nil, status: nil)
-      super(content: content, session_id: session_id)
-      @status = status
+    def initialize(content:, session_id: nil)
+      super
     end
 
     def type
       TYPE
     end
-
-    def to_h
-      h = super
-      h[:status] = status if status
-      h
-    end
   end
 end