anima-core 1.0.2 → 1.1.1

data/lib/anima/cli.rb

@@ -20,13 +20,17 @@ module Anima
       Installer.new.run
     end
 
-    desc "update", "Upgrade gem and migrate config"
+    desc "update", "Upgrade gem, migrate config, and restart service"
     option :migrate_only, type: :boolean, default: false, desc: "Skip gem upgrade, only migrate config"
     def update
+      require_relative "spinner"
+
       unless options[:migrate_only]
-        say "Upgrading anima-core gem..."
-        unless system("gem", "update", "anima-core")
-          say "Gem update failed.", :red
+        success = Spinner.run("Upgrading anima-core gem...") do
+          system("gem", "update", "anima-core", out: File::NULL, err: File::NULL)
+        end
+        unless success
+          say "Run manually for details: gem update anima-core", :red
           exit 1
         end
 
@@ -34,22 +38,24 @@ module Anima
         exec(File.join(Gem.bindir, "anima"), "update", "--migrate-only")
       end
 
-      say "Migrating configuration..."
       require_relative "config_migrator"
-      result = Anima::ConfigMigrator.new.run
+      result = Spinner.run("Migrating configuration...") do
+        Anima::ConfigMigrator.new.run
+      end
 
       case result.status
       when :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."
+        say "  Config is already up to date."
       when :updated
         result.additions.each do |addition|
           say "  added [#{addition.section}] #{addition.key} = #{addition.value.inspect}"
         end
-        say "Config updated. Changes take effect immediately — no restart needed."
       end
+
+      restart_service_if_active
     end
 
     # Start the Anima brain server (Puma + Solid Queue) via Foreman.
@@ -78,6 +84,7 @@ module Anima
 
     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"
     def tui
       require "ratatui_ruby"
       require_relative "../tui/app"
@@ -89,7 +96,7 @@ module Anima
       cable_client = TUI::CableClient.new(host: host)
       cable_client.connect
 
-      TUI::App.new(cable_client: cable_client).run
+      TUI::App.new(cable_client: cable_client, debug: options[:debug]).run
     end
 
     desc "version", "Show version"
@@ -103,5 +110,21 @@ module Anima
     subcommand "mcp", Mcp
 
     private
+
+    # 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).
+    #
+    # @return [void]
+    def restart_service_if_active
+      return unless system("systemctl", "--user", "is-active", "--quiet", "anima.service")
+
+      success = Spinner.run("Restarting anima service...") do
+        system("systemctl", "--user", "restart", "anima.service")
+      end
+      unless success
+        say "  Run manually: systemctl --user restart anima.service", :red
+      end
+    end
   end
 end

data/lib/anima/installer.rb

@@ -30,7 +30,6 @@ module Anima
       say "Installing Anima to #{anima_home}..."
       create_directories
       create_soul_file
-      create_config_file
       create_settings_config
       create_mcp_config
       generate_credentials
@@ -60,17 +59,6 @@ module Anima
       say "  created #{soul_path}"
     end
 
-    def create_config_file
-      config_path = anima_home.join("config", "anima.yml")
-      return if config_path.exist?
-
-      config_path.write(<<~YAML)
-        # Anima configuration
-        # See https://github.com/hoblin/anima for documentation
-      YAML
-      say "  created #{config_path}"
-    end
-
     def create_settings_config
       config_path = anima_home.join("config.toml")
       return if config_path.exist?
@@ -115,19 +103,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
@@ -153,16 +144,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

@@ -102,6 +102,11 @@ module Anima
       # @return [Integer] seconds
       def web_request_timeout = get("timeouts", "web_request")
 
+      # Per-tool-call timeout. Used as the default deadline for orphan detection
+      # and as the default value for the tool's `timeout` input parameter.
+      # @return [Integer] seconds
+      def tool_timeout = get("timeouts", "tool")
+
       # ─── Shell ──────────────────────────────────────────────────────
 
       # Maximum bytes of command output before truncation.
@@ -128,6 +133,19 @@ module Anima
 
       # ─── Session ────────────────────────────────────────────────────
 
+      # View mode applied to new sessions: "basic", "verbose", or "debug".
+      # Changing this setting only affects sessions created afterwards.
+      # @return [String]
+      # @raise [MissingSettingError] if the value is not a valid view mode
+      def default_view_mode
+        value = get("session", "default_view_mode")
+        unless Session::VIEW_MODES.include?(value)
+          raise MissingSettingError,
+            "[session] default_view_mode must be one of: #{Session::VIEW_MODES.join(", ")} (got #{value.inspect})"
+        end
+        value
+      end
+
       # Regenerate session name every N messages.
       # @return [Integer]
       def name_generation_interval = get("session", "name_generation_interval")
@@ -177,6 +195,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.

data/lib/anima/spinner.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Anima
+  # Braille spinner for long-running CLI operations.
+  # Animates in a background thread while a block executes in the
+  # calling thread, then shows a success/failure indicator.
+  #
+  # @example
+  #   result = Spinner.run("Installing...") { system("make install") }
+  class Spinner
+    FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+    FRAME_DELAY = 0.08
+    SUCCESS_ICON = "\u2713"
+    FAILURE_ICON = "\u2717"
+    JOIN_TIMEOUT = 2
+
+    # Run a block with an animated spinner beside a status message.
+    #
+    # @param message [String] status text shown beside the spinner
+    # @param output [IO] output stream (defaults to $stdout)
+    # @yield the operation to run
+    # @return [Object] the block's return value
+    def self.run(message, output: $stdout, &block)
+      new(message, output: output).run(&block)
+    end
+
+    # @param message [String] status text shown beside the spinner
+    # @param output [IO] output stream
+    def initialize(message, output: $stdout)
+      @message = message
+      @output = output
+      @mutex = Mutex.new
+      @running = false
+    end
+
+    # @yield operation to run while the spinner animates
+    # @return [Object] the block's return value
+    def run
+      thread = start_animation
+      result = yield
+      stop_animation(thread, success: !!result)
+      result
+    rescue
+      stop_animation(thread, success: false)
+      raise
+    end
+
+    private
+
+    def running?
+      @mutex.synchronize { @running }
+    end
+
+    def start_animation
+      @mutex.synchronize { @running = true }
+      Thread.new do
+        idx = 0
+        while running?
+          @output.print "\r#{FRAMES[idx % FRAMES.size]} #{@message}"
+          @output.flush
+          idx += 1
+          sleep FRAME_DELAY
+        end
+      end
+    end
+
+    def stop_animation(thread, success:)
+      @mutex.synchronize { @running = false }
+      thread.join(JOIN_TIMEOUT)
+      icon = success ? SUCCESS_ICON : FAILURE_ICON
+      @output.print "\r#{icon} #{@message}\n"
+      @output.flush
+    end
+  end
+end

data/lib/anima/version.rb

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

data/lib/environment_probe.rb

@@ -123,7 +123,7 @@ class EnvironmentProbe
   # @return [Hash{Symbol => String}, nil] keys: :remote, :repo_name, :branch,
   #   and optionally :pr_number (Integer) and :pr_state (String); nil when not in a repo
   def detect_git
-    _, status = Open3.capture2("git", "-C", @pwd, "rev-parse", "--is-inside-work-tree")
+    _, status = Open3.capture2("git", "-C", @pwd, "rev-parse", "--is-inside-work-tree", err: File::NULL)
     return unless status.success?
 
     info = {}
@@ -136,7 +136,7 @@ class EnvironmentProbe
 
   # Populates :remote and :repo_name on the info hash.
   def detect_git_remote(info)
-    remote, = Open3.capture2("git", "-C", @pwd, "remote", "get-url", "origin")
+    remote, = Open3.capture2("git", "-C", @pwd, "remote", "get-url", "origin", err: File::NULL)
     remote = remote.strip
     return unless remote.present?
 
@@ -146,7 +146,7 @@ class EnvironmentProbe
 
   # Populates :branch, :pr_number, and :pr_state on the info hash.
   def detect_git_branch(info)
-    branch, = Open3.capture2("git", "-C", @pwd, "rev-parse", "--abbrev-ref", "HEAD")
+    branch, = Open3.capture2("git", "-C", @pwd, "rev-parse", "--abbrev-ref", "HEAD", err: File::NULL)
     branch = branch.strip
     return unless branch.present?
 
@@ -181,7 +181,7 @@ class EnvironmentProbe
       output, status = Open3.capture2(
         "gh", "pr", "list", "--head", branch,
         "--json", "number,state", "--limit", "1",
-        chdir: @pwd
+        chdir: @pwd, err: File::NULL
       )
       return unless status.success?
 

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/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 their
+      # callers ({SessionChannel#speak} for idle sessions,
+      # {AgentLoop#process} for direct usage). 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,17 @@ 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 event 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] != 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

data/lib/events/tool_call.rb

@@ -4,18 +4,20 @@ module Events
   class ToolCall < Base
     TYPE = "tool_call"
 
-    attr_reader :tool_name, :tool_input, :tool_use_id
+    attr_reader :tool_name, :tool_input, :tool_use_id, :timeout
 
     # @param content [String] human-readable description of the tool call
     # @param tool_name [String] registered tool name (e.g. "web_get")
     # @param tool_input [Hash] arguments passed to the tool
     # @param tool_use_id [String] Anthropic-assigned ID for correlating call/result
+    # @param timeout [Integer] maximum seconds before the call is considered orphaned
     # @param session_id [String, nil] optional session identifier
-    def initialize(content:, tool_name:, tool_input: {}, tool_use_id: nil, session_id: nil)
+    def initialize(content:, tool_name:, tool_input: {}, tool_use_id: nil, timeout: nil, session_id: nil)
       super(content: content, session_id: session_id)
       @tool_name = tool_name
       @tool_input = tool_input
       @tool_use_id = tool_use_id
+      @timeout = timeout
     end
 
     def type
@@ -23,7 +25,7 @@ module Events
     end
 
     def to_h
-      super.merge(tool_name: tool_name, tool_input: tool_input, tool_use_id: tool_use_id)
+      super.merge(tool_name: tool_name, tool_input: tool_input, tool_use_id: tool_use_id, timeout: timeout)
     end
   end
 end

data/lib/llm/client.rb

@@ -70,10 +70,13 @@ module LLM
     # @param messages [Array<Hash>] conversation messages in Anthropic format
     # @param registry [Tools::Registry] registered tools to make available
     # @param session_id [Integer, String] session ID for emitted events
+    # @param first_response [Hash, nil] pre-fetched first API response from
+    #   {AgentLoop#deliver!}. Skips the first API call when provided so
+    #   the Bounce Back transaction doesn't duplicate work.
     # @param options [Hash] additional API parameters (e.g. +system:+)
     # @return [String, nil] the assistant's final text response, or nil when interrupted
     # @raise [Providers::Anthropic::Error] on API errors
-    def chat_with_tools(messages, registry:, session_id:, **options)
+    def chat_with_tools(messages, registry:, session_id:, first_response: nil, **options)
       messages = messages.dup
       rounds = 0
 
@@ -84,13 +87,17 @@ module LLM
           return "[Tool loop exceeded #{max_rounds} rounds — halting]"
         end
 
-        response = provider.create_message(
-          model: model,
-          messages: messages,
-          max_tokens: max_tokens,
-          tools: registry.schemas,
-          **options
-        )
+        response = if first_response && rounds == 1
+          first_response
+        else
+          provider.create_message(
+            model: model,
+            messages: messages,
+            max_tokens: max_tokens,
+            tools: registry.schemas,
+            **options
+          )
+        end
 
         log(:debug, "stop_reason=#{response["stop_reason"]} content_types=#{(response["content"] || []).map { |b| b["type"] }.join(",")}")
 
@@ -174,12 +181,14 @@ module LLM
       name = tool_use["name"]
       id = tool_use["id"]
       input = tool_use["input"] || {}
+      timeout = input["timeout"] || Anima::Settings.tool_timeout
 
       log(:debug, "tool_call: #{name}(#{input.to_json})")
 
       Events::Bus.emit(Events::ToolCall.new(
         content: "Calling #{name}", tool_name: name,
-        tool_input: input, tool_use_id: id, session_id: session_id
+        tool_input: input, tool_use_id: id, timeout: timeout,
+        session_id: session_id
       ))
 
       result = begin
@@ -189,6 +198,7 @@ module LLM
         {error: "#{error.class}: #{error.message}"}
       end
 
+      result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")