anima-core 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dca02bfff536637c003d5f3bbce8dbe20992b7eeb25e6c51bdb4991a2803b538
-  data.tar.gz: ead68cc1bd03306a9eef644db2f15a81b7dbfd74bbe1f059e3f57bcfc0aaf77a
+  metadata.gz: 161b7dfde73fa61f7656427c0af3c5919e1a1cc50d6b1a2d201f5a45ce79c561
+  data.tar.gz: 880538d54fbc682b61bbeb6d63b38aa066e86327c778fefce8e60091c6ad816d
 SHA512:
-  metadata.gz: 45f7f927d4f931b624db684e5f500c436cac44cf9dd9a004400b7219f1167e932b181dddac3793d4cd8f1885cf6401855ba6ca681c99d7cd902af8784e49cee2
-  data.tar.gz: 78e532c99e39f09732c9abe9588e467a96fb38cddaf7d1b8ba526971de1c890e73efd157876cb570eabad0cb0eb7c1f93faeef68c7128f7806f972ff98e2351c
+  metadata.gz: f0ee765c1a125e26b9f10b5cc97f41e857ec17562ef4ba116dd53bf97b9b26fb3781d9f292c6296c1c408089d155d9d8a24e4165d58f57ead64e72595f833ae8
+  data.tar.gz: 86c95c9f103cb0c6c4b37ef3452662274205da97ef04d3f846f7f2d041ff0c94f375208b60d245f454aa73abb2c144113f9d6691cc99a0124f43971fcfb62ae1

data/.reek.yml

@@ -39,6 +39,8 @@ detectors:
       - "Tools::SubagentPrompts#assign_nickname_via_brain"
       # Validation methods naturally reference the validated value more than self.
       - "AnalyticalBrain::Tools::AssignNickname#validate"
+      # Delivery method orchestrates session, event, and agent_loop — inherent.
+      - "AgentRequestJob#deliver_persisted_event"
   # Private helpers don't need instance state to be valid.
   # ActiveJob#perform is always a utility function by design.
   # No-op tools (Think, EverythingIsReady) don't need instance state — by design.
@@ -90,6 +92,8 @@ detectors:
       - "Tools::Remember"
       # Nickname validation checks parent_session for existence then queries — two calls, one guard.
       - "AnalyticalBrain::Tools::AssignNickname#sibling_nickname_taken?"
+      # Delivery method references session.id for lookup, BounceBack, and auth broadcast.
+      - "AgentRequestJob#deliver_persisted_event"
   # Method length is enforced by code review, not arbitrary line counts
   # build_sections passes context through to sub-methods — inherent to assembly.
   LongParameterList:

data/README.md

@@ -132,8 +132,7 @@ State directory (`~/.anima/`):
 ├── config.toml      # Main settings (hot-reloadable)
 ├── mcp.toml         # MCP server configuration
 ├── config/
-│   ├── credentials/ # Rails encrypted credentials per environment
-│   └── anima.yml    # Placeholder config
+│   └── credentials/ # Rails encrypted credentials per environment
 ├── agents/          # User-defined specialist agents (override built-ins)
 ├── skills/          # User-defined skills (override built-ins)
 ├── workflows/       # User-defined workflows (override built-ins)
@@ -142,7 +141,7 @@ State directory (`~/.anima/`):
 └── tmp/
 ```
 
-Updates: `anima update` — upgrades the gem and merges new config settings into your existing `config.toml` without overwriting customized values. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
+Updates: `anima update` — upgrades the gem, merges new config settings into your existing `config.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
 
 ### Authentication Setup
 
@@ -300,6 +299,7 @@ blocking_on_user_message = true
 event_window = 20
 
 [session]
+default_view_mode = "basic"
 name_generation_interval = 30
 ```
 

data/app/channels/session_channel.rb

@@ -42,14 +42,13 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # Processes user input by emitting a {Events::UserMessage} on the event bus.
+  # Processes user input. For idle sessions, persists the event immediately
+  # so the message appears in the TUI without waiting for the background
+  # job, then schedules {AgentRequestJob} for LLM delivery. If delivery
+  # fails, the job deletes the event and emits a {Events::BounceBack}.
   #
-  # When the session is idle, the emission triggers {Events::Subscribers::AgentDispatcher}
-  # which schedules {AgentRequestJob} to persist the event and deliver it to the LLM
-  # inside a transaction (Bounce Back, #236).
-  #
-  # When the session is already processing, the message is queued as "pending"
-  # and picked up after the current agent loop completes.
+  # For busy sessions, emits a pending {Events::UserMessage} that queues
+  # until the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
   def speak(data)
@@ -62,7 +61,8 @@ class SessionChannel < ApplicationCable::Channel
     if session.processing?
       Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id, status: Event::PENDING_STATUS))
     else
-      Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
+      event = session.create_user_event(content)
+      AgentRequestJob.perform_later(session.id, event_id: event.id)
     end
   end
 

data/app/decorators/tool_call_decorator.rb

@@ -6,7 +6,8 @@ require "toon"
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
-# full untruncated input in TOON format with tool_use_id.
+# full untruncated input with tool_use_id — TOON format for most
+# tools, but write tool content preserves actual newlines.
 #
 # Think tool calls are special: "aloud" thoughts are shown in all
 # view modes (with a thought bubble), while "inner" thoughts are
@@ -41,7 +42,7 @@ class ToolCallDecorator < EventDecorator
     {
       role: :tool_call,
       tool: payload["tool_name"],
-      input: Toon.encode(payload["tool_input"] || {}),
+      input: format_debug_input,
       tool_use_id: payload["tool_use_id"],
       timestamp: timestamp
     }
@@ -90,6 +91,30 @@ class ToolCallDecorator < EventDecorator
     {role: :think, content: thoughts, visibility: visibility, tool_use_id: payload["tool_use_id"], timestamp: timestamp}
   end
 
+  # Full tool input for debug mode. Write tool content is shown with
+  # preserved newlines instead of TOON-escaping them into literal \n.
+  # @return [String] formatted debug input
+  def format_debug_input
+    input = tool_input
+    case payload["tool_name"]
+    when "write" then format_write_content(input)
+    else Toon.encode(input)
+    end
+  end
+
+  # Formats write tool input with file path header and content body.
+  # Content newlines are preserved so the TUI can render them as
+  # separate lines, matching how read tool responses display file content.
+  # @param input [Hash] tool input hash with "file_path" and "content" keys
+  # @return [String] path + content with real newlines, or TOON-encoded hash when content is empty
+  def format_write_content(input)
+    path = input.dig("file_path").to_s
+    content = input.dig("content").to_s
+    return Toon.encode(input) if content.empty?
+
+    "#{path}\n#{content}"
+  end
+
   # Formats tool input for display, with tool-specific formatting for
   # known tools and generic JSON fallback for others.
   # @return [String] formatted input preview

data/app/jobs/agent_request_job.rb

@@ -5,16 +5,18 @@
 #
 # Supports two modes:
 #
-# **Bounce Back (content provided):** Persists the user event and verifies
-# LLM delivery inside a single transaction. If the first API call fails,
-# the transaction rolls back (event never existed) and a {Events::BounceBack}
-# is emitted so clients can restore the text to the input field.
+# **Immediate Persist (event_id provided):** The user event was already
+# persisted and broadcast by the caller (e.g. {SessionChannel#speak}).
+# The job verifies LLM delivery — if the first API call fails, the
+# event is deleted and a {Events::BounceBack} is emitted so clients
+# can restore the text to the input field.
 #
-# **Standard (no content):** Processes already-persisted events (e.g. after
-# pending message promotion). Uses ActiveJob retry/discard for error handling.
+# **Standard (no event_id):** Processes already-persisted events (e.g.
+# after pending message promotion). Uses ActiveJob retry/discard for
+# error handling.
 #
-# @example Bounce Back — event-driven via AgentDispatcher
-#   AgentRequestJob.perform_later(session.id, content: "hello")
+# @example Immediate Persist — event already saved by SessionChannel
+#   AgentRequestJob.perform_later(session.id, event_id: 42)
 #
 # @example Standard — pending message processing
 #   AgentRequestJob.perform_later(session.id)
@@ -24,7 +26,7 @@ class AgentRequestJob < ApplicationJob
   # ActionCable action signaling clients to prompt for an API token.
   AUTH_REQUIRED_ACTION = "authentication_required"
 
-  # Standard path only — bounce back handles its own errors.
+  # Standard path only — immediate persist handles its own errors.
   retry_on Providers::Anthropic::TransientError,
     wait: :polynomially_longer, attempts: 5 do |job, error|
     Events::Bus.emit(Events::SystemMessage.new(
@@ -47,8 +49,8 @@ class AgentRequestJob < ApplicationJob
   end
 
   # @param session_id [Integer] ID of the session to process
-  # @param content [String, nil] user message text (triggers Bounce Back when present)
-  def perform(session_id, content: nil)
+  # @param event_id [Integer, nil] ID of a pre-persisted user event (triggers delivery verification)
+  def perform(session_id, event_id: nil)
     session = Session.find(session_id)
 
     # Atomic: only one job processes a session at a time.
@@ -58,8 +60,8 @@ class AgentRequestJob < ApplicationJob
 
     agent_loop = AgentLoop.new(session: session)
 
-    if content
-      deliver_with_bounce_back(session, content, agent_loop)
+    if event_id
+      deliver_persisted_event(session, event_id, agent_loop)
     else
       agent_loop.run
     end
@@ -80,51 +82,52 @@ class AgentRequestJob < ApplicationJob
 
   private
 
-  # Persists the user event and verifies LLM delivery atomically.
+  # Verifies LLM delivery for a pre-persisted user event.
   #
-  # Inside a transaction: creates the event record, broadcasts it for
-  # optimistic UI, and makes the first LLM API call. If the call fails,
-  # a {Events::BounceBack} is emitted and the exception re-raised to
-  # trigger rollback — the event never existed in the database.
+  # The event was already created and broadcast by the caller, so
+  # the user sees their message immediately. This method makes the
+  # first LLM API call — if it fails, the event is deleted and a
+  # {Events::BounceBack} notifies clients to remove the phantom
+  # message and restore the text to the input field. For
+  # {Providers::Anthropic::AuthenticationError}, an additional
+  # +authentication_required+ broadcast prompts the client to show
+  # the token entry dialog.
   #
-  # After commit: continues the agent loop (tool execution, subsequent
-  # API calls) outside the transaction so tool events broadcast in
-  # real time.
+  # Unlike the standard path (which uses +retry_on+ / +discard_on+),
+  # all errors here are caught and swallowed after emitting a
+  # BounceBack — the job completes normally so ActiveJob does not
+  # retry a message the user will re-send manually.
+  #
+  # After successful delivery, continues the agent loop (tool
+  # execution, subsequent API calls).
   #
   # @param session [Session] the conversation session
-  # @param content [String] user message text
-  # @param agent_loop [AgentLoop] agent loop instance (reused after commit)
-  def deliver_with_bounce_back(session, content, agent_loop)
-    event_id = nil
-
-    ActiveRecord::Base.transaction do
-      event = persist_user_event(session, content)
-      event_id = event.id
-      event.broadcast_now!
-
+  # @param event_id [Integer] database ID of the pre-persisted user event
+  # @param agent_loop [AgentLoop] agent loop instance (reused for continuation)
+  def deliver_persisted_event(session, event_id, agent_loop)
+    event = Event.find_by(id: event_id, session_id: session.id)
+    # Event may have been deleted between SessionChannel#speak and job
+    # execution (e.g. user recalled the message). Exit silently — there
+    # is nothing to deliver or bounce back.
+    return unless event
+
+    content = event.payload["content"]
+
+    begin
       agent_loop.deliver!
     rescue => error
+      event.destroy!
       Events::Bus.emit(Events::BounceBack.new(
         content: content,
         error: error.message,
         session_id: session.id,
         event_id: event_id
       ))
-      raise
+      broadcast_auth_required(session.id, error) if error.is_a?(Providers::Anthropic::AuthenticationError)
+      return
     end
 
-    # Transaction committed — first call succeeded.
-    # Continue processing (tool execution, etc.) outside the transaction.
     agent_loop.run
-  rescue => error
-    # Bounce already emitted inside the transaction rescue.
-    # Also trigger auth popup for authentication errors.
-    broadcast_auth_required(session.id, error) if error.is_a?(Providers::Anthropic::AuthenticationError)
-  end
-
-  # @see Session#create_user_event
-  def persist_user_event(session, content)
-    session.create_user_event(content)
   end
 
   def broadcast_auth_required(session_id, error)

data/app/models/concerns/event/broadcasting.rb

@@ -44,23 +44,9 @@ module Event::Broadcasting
     after_update_commit :broadcast_update
   end
 
-  # Broadcasts this event immediately, bypassing +after_create_commit+.
-  # Used inside a wrapping transaction where +after_create_commit+ is
-  # deferred until the outer transaction commits. Gives clients
-  # optimistic UI — the event appears right away and is removed via
-  # bounce if the transaction rolls back.
-  #
-  # Sets a flag so the deferred +after_create_commit+ callback skips
-  # the duplicate broadcast after the transaction commits.
-  def broadcast_now!
-    @already_broadcast = true
-    broadcast_event(action: ACTION_CREATE)
-  end
-
   private
 
   def broadcast_create
-    return if @already_broadcast
     broadcast_event(action: ACTION_CREATE)
   end
 

data/app/models/session.rb

@@ -11,6 +11,8 @@ class Session < ApplicationRecord
 
   VIEW_MODES = %w[basic verbose debug].freeze
 
+  attribute :view_mode, :string, default: -> { Anima::Settings.default_view_mode }
+
   serialize :granted_tools, coder: JSON
 
   has_many :events, -> { order(:id) }, dependent: :destroy
@@ -251,6 +253,8 @@ class Session < ApplicationRecord
   # @param token_budget [Integer] maximum tokens to include (positive)
   # @return [Array<Hash>] Anthropic Messages API format
   def messages_for_llm(token_budget: Anima::Settings.token_budget)
+    heal_orphaned_tool_calls!
+
     sliding_budget = token_budget
     snapshot_messages = []
     pinned_messages = []
@@ -273,11 +277,52 @@ class Session < ApplicationRecord
       recall_messages = assemble_recall_messages(budget: recall_budget)
     end
 
-    snapshot_messages + pinned_messages + recall_messages + assemble_messages(events)
+    snapshot_messages + pinned_messages + recall_messages + assemble_messages(ensure_atomic_tool_pairs(events))
+  end
+
+  # Detects orphaned tool_call events (those without a matching tool_response
+  # and whose timeout has expired) and creates synthetic error responses.
+  # An orphaned tool_call permanently breaks the session because the
+  # Anthropic API rejects conversations where a tool_use block has no
+  # matching tool_result.
+  #
+  # Respects the per-call timeout stored in the tool_call event payload —
+  # a tool_call is only healed after its deadline has passed. This avoids
+  # prematurely healing long-running tools that the agent intentionally
+  # gave an extended timeout.
+  #
+  # @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)
+      .where.not(tool_use_id: responded_ids)
+
+    healed = 0
+    unresponded.find_each do |orphan|
+      timeout = orphan.payload["timeout"] || Anima::Settings.tool_timeout
+      deadline_ns = orphan.timestamp + (timeout * 1_000_000_000)
+      next if now_ns < deadline_ns
+
+      events.create!(
+        event_type: "tool_response",
+        payload: {
+          "type" => "tool_response",
+          "content" => "Tool execution timed out after #{timeout} seconds — no result was returned.",
+          "tool_name" => orphan.payload["tool_name"],
+          "tool_use_id" => orphan.tool_use_id,
+          "success" => false
+        },
+        tool_use_id: orphan.tool_use_id,
+        timestamp: now_ns
+      )
+      healed += 1
+    end
+    healed
   end
 
   # Creates a user message event record directly (bypasses EventBus+Persister).
-  # Used by {AgentRequestJob} (Bounce Back transaction), {AgentLoop#process},
+  # Used by {SessionChannel#speak} (immediate display), {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.
@@ -497,6 +542,28 @@ class Session < ApplicationRecord
     event_list
   end
 
+  # Ensures every tool_call in the event list has a matching tool_response
+  # (and vice versa) by removing unpaired events. The Anthropic API requires
+  # every tool_use block to have a tool_result — a missing partner causes
+  # a permanent API error. Token budget cutoffs can split pairs when the
+  # boundary falls between a tool_call and its tool_response.
+  #
+  # @param event_list [Array<Event>] chronologically ordered events
+  # @return [Array<Event>] events with unpaired tool events removed
+  def ensure_atomic_tool_pairs(event_list)
+    tool_events = event_list.select { |e| e.tool_use_id.present? }
+    return event_list if tool_events.empty?
+
+    paired = tool_events.group_by(&:tool_use_id)
+    complete_ids = paired.each_with_object(Set.new) do |(id, evts), set|
+      has_call = evts.any? { |e| e.event_type == "tool_call" }
+      has_response = evts.any? { |e| e.event_type == "tool_response" }
+      set << id if has_call && has_response
+    end
+
+    event_list.reject { |e| e.tool_use_id.present? && !complete_ids.include?(e.tool_use_id) }
+  end
+
   # Selects visible snapshots and formats them as Anthropic messages.
   # Snapshots are visible when their source events have fully evicted.
   # L1 snapshots are excluded when covered by an L2 snapshot.

data/bin/jobs

@@ -3,4 +3,9 @@
 require_relative "../config/environment"
 require "solid_queue/cli"
 
+# Run all Solid Queue components (worker, dispatcher, scheduler) as threads
+# in a single process. Fork mode spawns child processes that can outlive
+# the supervisor and run stale code after gem updates (#275).
+ENV["SOLID_QUEUE_SUPERVISOR_MODE"] = "async"
+
 SolidQueue::Cli.start(ARGV)

data/config/initializers/event_subscribers.rb

@@ -6,12 +6,10 @@
 Rails.application.config.after_initialize do
   unless Rails.env.test?
     # Global persister handles events from all sessions (brain server, background jobs).
-    # Skips non-pending user messages — those are persisted by AgentRequestJob.
+    # Skips non-pending user messages — those are persisted by their callers
+    # (SessionChannel#speak for idle sessions, AgentLoop#process for direct usage).
     Events::Bus.subscribe(Events::Subscribers::Persister.new)
 
-    # Schedules AgentRequestJob when a non-pending user message is emitted.
-    Events::Bus.subscribe(Events::Subscribers::AgentDispatcher.new)
-
     # Bridges transient events (e.g. BounceBack) to ActionCable for client delivery.
     Events::Bus.subscribe(Events::Subscribers::TransientBroadcaster.new)
 

data/config/queue.yml

@@ -5,7 +5,6 @@ default: &default
   workers:
     - queues: "*"
       threads: 3
-      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
       polling_interval: 0.1
 
 development:

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.
@@ -104,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?

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")

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.1.0"
+  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/subscribers/persister.rb

@@ -28,10 +28,10 @@ module Events
 
       # 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}).
+      # 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)
@@ -63,9 +63,11 @@ module Events
 
       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.
+      # 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

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

@@ -181,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

data/lib/shell_session.rb

@@ -45,13 +45,15 @@ class ShellSession
   # automatically if the previous session died (timeout, crash, etc.).
   #
   # @param command [String] bash command to execute
+  # @param timeout [Integer, nil] per-call timeout in seconds; overrides
+  #   Settings.command_timeout when provided
   # @return [Hash] with :stdout, :stderr, :exit_code keys on success
   # @return [Hash] with :error key on failure
-  def run(command)
+  def run(command, timeout: nil)
     @mutex.synchronize do
       return {error: "Shell session is not running"} if @finalized
       restart unless @alive
-      execute_in_pty(command)
+      execute_in_pty(command, timeout: timeout)
     end
   rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
     {error: "#{error.class}: #{error.message}"}
@@ -227,10 +229,10 @@ class ShellSession
     end
   end
 
-  def execute_in_pty(command)
+  def execute_in_pty(command, timeout: nil)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
-    timeout = Anima::Settings.command_timeout
+    timeout ||= Anima::Settings.command_timeout
     deadline = monotonic_now + timeout
 
     @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"

data/lib/tools/base.rb

@@ -49,7 +49,8 @@ module Tools
     def initialize(**) = nil
 
     # Execute the tool with the given input.
-    # @param input [Hash] parsed input matching {.input_schema}
+    # @param input [Hash] parsed input matching {.input_schema}. May include
+    #   a "timeout" key (seconds) for tools that support per-call timeout overrides.
     # @return [String, Hash] result content; Hash with :error key signals failure
     def execute(input)
       raise NotImplementedError, "#{self.class} must implement #execute"

data/lib/tools/bash.rb

@@ -27,14 +27,16 @@ module Tools
       @shell_session = shell_session
     end
 
-    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
+    #   Supports optional "timeout" key (seconds) to override the global
+    #   command_timeout setting for long-running operations.
     # @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
       return {error: "Command cannot be blank"} if command.strip.empty?
 
-      result = @shell_session.run(command)
+      result = @shell_session.run(command, timeout: input["timeout"])
       return result if result.key?(:error)
 
       format_result(result[:stdout], result[:stderr], result[:exit_code])

data/lib/tools/registry.rb

@@ -30,16 +30,21 @@ module Tools
       @tools[tool.tool_name] = tool
     end
 
-    # @return [Array<Hash>] schema array for the Anthropic tools API parameter
+    # @return [Array<Hash>] schema array for the Anthropic tools API parameter.
+    #   Each schema includes an optional `timeout` parameter (seconds) injected
+    #   by the registry. The agent can override the default per call for
+    #   long-running operations.
     def schemas
-      @tools.values.map(&:schema)
+      default = Anima::Settings.tool_timeout
+      @tools.values.map { |tool| inject_timeout(tool.schema, default) }
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
     # context; instances are called directly.
     #
     # @param name [String] registered tool name
-    # @param input [Hash] tool input parameters
+    # @param input [Hash] tool input parameters (may include "timeout" for
+    #   tools that support per-call timeout overrides)
     # @return [String, Hash] tool execution result
     # @raise [UnknownToolError] if no tool is registered with the given name
     def execute(name, input)
@@ -58,5 +63,19 @@ module Tools
     def any?
       @tools.any?
     end
+
+    private
+
+    # Injects an optional `timeout` parameter into the tool's input schema.
+    def inject_timeout(schema, default)
+      s = schema.deep_dup
+      s[:input_schema] ||= {type: "object", properties: {}}
+      s[:input_schema][:properties] ||= {}
+      s[:input_schema][:properties]["timeout"] = {
+        type: "integer",
+        description: "Max execution seconds (default: #{default}). Increase for long-running operations."
+      }
+      s
+    end
   end
 end

data/lib/tools/request_feature.rb

@@ -71,7 +71,9 @@ module Tools
 
     # @return [String, nil] owner/repo parsed from +git remote get-url origin+
     def git_remote_repo
-      url, _status = Open3.capture2("git", "remote", "get-url", "origin")
+      url, status = Open3.capture2("git", "remote", "get-url", "origin", err: File::NULL)
+      return unless status.success?
+
       parse_owner_repo(url.strip)
     rescue Errno::ENOENT
       nil

data/lib/tools/web_get.rb

@@ -27,17 +27,19 @@ module Tools
       }
     end
 
-    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
+    #   Supports optional "timeout" key (seconds) to override the global
+    #   web_request_timeout setting.
     # @return [Hash] `{body: String, content_type: String}` on success
     # @return [Hash] `{error: String}` on failure
     def execute(input)
-      validate_and_fetch(input["url"].to_s)
+      validate_and_fetch(input["url"].to_s, timeout: input["timeout"])
     end
 
     private
 
-    def validate_and_fetch(url)
-      timeout = Anima::Settings.web_request_timeout
+    def validate_and_fetch(url, timeout: nil)
+      timeout ||= Anima::Settings.web_request_timeout
       scheme = URI.parse(url).scheme
 
       unless %w[http https].include?(scheme)

data/lib/tui/message_store.rb

@@ -14,6 +14,11 @@ module TUI
   # rendered content fall back to existing behavior: tool events aggregate
   # into counters, messages store role and content.
   #
+  # Entries with event IDs are maintained in ID order (ascending)
+  # regardless of arrival order, preventing misordering from race
+  # conditions between live broadcasts and viewport replays.
+  # Duplicate IDs are deduplicated by updating the existing entry.
+  #
   # Tool counters aggregate per agent turn: a new counter starts when a
   # tool_call arrives after a message entry. Consecutive tool events
   # increment the same counter until the next message breaks the chain.
@@ -183,16 +188,79 @@ module TUI
       event_data.dig("rendered")&.values&.compact&.first
     end
 
+    # Inserts a rendered entry at the correct chronological position.
+    # System prompt entries (no ID) are always placed at position 0.
     def record_rendered(data, event_type: nil, id: nil)
       @mutex.synchronize do
         entry = {type: :rendered, data: data, event_type: event_type, id: id}
-        @entries << entry
-        @entries_by_id[id] = entry if id
+        insert_ordered(entry)
         @version += 1
       end
       true
     end
 
+    # Inserts an entry in event-ID order. Entries without an ID are
+    # appended. If an entry with the same ID already exists, updates
+    # it in-place (deduplication for live/viewport replay races).
+    # System prompt entries are always placed at position 0.
+    #
+    # @param entry [Hash] the entry to insert
+    # @return [void]
+    def insert_ordered(entry)
+      if entry[:event_type] == "system_prompt"
+        @entries.unshift(entry)
+        return
+      end
+
+      id = entry[:id]
+      unless id
+        @entries << entry
+        return
+      end
+
+      existing = @entries_by_id[id]
+      if existing
+        existing[:data] = entry[:data] if entry.key?(:data)
+        existing[:content] = entry[:content] if entry.key?(:content)
+        existing[:event_type] = entry[:event_type] if entry.key?(:event_type)
+        return
+      end
+
+      insert_sorted_by_id(entry)
+      @entries_by_id[id] = entry
+    end
+
+    # Inserts an entry in sorted order by event ID. Optimized for the
+    # common case where events arrive in order (appends without scanning).
+    # Entries without IDs (tool counters, etc.) are skipped during the
+    # sort scan and don't affect insertion position.
+    #
+    # @param entry [Hash] entry with a non-nil +:id+
+    # @return [void]
+    def insert_sorted_by_id(entry)
+      id = entry[:id]
+
+      # Fast path: entry belongs at the end (typical during live streaming)
+      last_id = last_entry_id
+      if last_id.nil? || last_id < id
+        @entries << entry
+        return
+      end
+
+      # Out-of-order arrival: insert before the first entry with a higher ID
+      insert_pos = @entries.index { |e| e[:id] && e[:id] > id } || @entries.size
+      @entries.insert(insert_pos, entry)
+    end
+
+    # Returns the highest event ID in the entries array, scanning from the
+    # end for efficiency (entries with IDs are typically at the tail).
+    #
+    # @return [Integer, nil] the highest event ID, or nil if no entries have IDs
+    def last_entry_id
+      @entries.reverse_each { |e| return e[:id] if e[:id] }
+      nil
+    end
+
     def record_tool_call
       @mutex.synchronize do
         current = current_tool_counter
@@ -221,12 +289,9 @@ module TUI
       content = event_data["content"]
       return false if content.nil?
 
-      event_id = event_data["id"]
-
       @mutex.synchronize do
-        entry = {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content, id: event_id}
-        @entries << entry
-        @entries_by_id[event_id] = entry if event_id
+        entry = {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content, id: event_data["id"]}
+        insert_ordered(entry)
         @version += 1
       end
       true

data/templates/config.toml

@@ -39,6 +39,10 @@ mcp_response = 60
 # Web fetch request timeout.
 web_request = 10
 
+# Per-tool-call timeout. The agent can override per call via the timeout parameter.
+# Also used as the default deadline for orphan detection in heal_orphaned_tool_calls!.
+tool = 180
+
 # ─── Shell ──────────────────────────────────────────────────────
 
 [shell]
@@ -94,6 +98,9 @@ soul = "{{ANIMA_HOME}}/soul.md"
 
 [session]
 
+# View mode for new sessions: "basic", "verbose", or "debug".
+default_view_mode = "basic"
+
 # Regenerate session name every N messages.
 name_generation_interval = 30
 

data/templates/soul.md

@@ -17,7 +17,7 @@ config, credentials, skills, workflows, agents.
 Find your source code README:
 
 ```bash
-cat $(bundle show anima-core)/README.md
+cat $(gem contents anima-core | grep README.md)
 ```
 
 ## What to do first

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -348,6 +348,7 @@ files:
 - lib/anima/config_migrator.rb
 - lib/anima/installer.rb
 - lib/anima/settings.rb
+- lib/anima/spinner.rb
 - lib/anima/version.rb
 - lib/credential_store.rb
 - lib/environment_probe.rb
@@ -356,7 +357,6 @@ files:
 - lib/events/bounce_back.rb
 - lib/events/bus.rb
 - lib/events/subscriber.rb
-- lib/events/subscribers/agent_dispatcher.rb
 - lib/events/subscribers/message_collector.rb
 - lib/events/subscribers/persister.rb
 - lib/events/subscribers/subagent_message_router.rb

data/lib/events/subscribers/agent_dispatcher.rb

@@ -1,29 +0,0 @@
-# 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