anima-core 0.1.0 → 0.2.0

data/config/database.yml

@@ -13,6 +13,10 @@ development:
     <<: *default
     database: <%= File.join(anima_home, "db", "development_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "development_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate
 
 test:
   primary:
@@ -22,6 +26,10 @@ test:
     <<: *default
     database: <%= File.join(anima_home, "db", "test_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "test_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate
 
 production:
   primary:
@@ -31,3 +39,7 @@ production:
     <<: *default
     database: <%= File.join(anima_home, "db", "production_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "production_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate

data/config/initializers/event_subscribers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Registers global EventBus subscribers at boot time.
+# Subscribers registered here receive all events regardless of which
+# process emitted them (brain server, background job, etc.).
+Rails.application.config.after_initialize do
+  # Global persister handles events from all sessions (brain server, background jobs).
+  # Skipped in test — specs manage their own persisters for isolation.
+  Events::Bus.subscribe(Events::Subscribers::Persister.new) unless Rails.env.test?
+  Events::Bus.subscribe(Events::Subscribers::ActionCableBridge.instance)
+end

data/config/puma.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Anima brain server — serves Action Cable WebSocket connections
+# and health check endpoint. Port 42134 by default.
+
+threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)
+threads threads_count, threads_count
+
+port ENV.fetch("PORT", 42134)
+
+pidfile ENV.fetch("PIDFILE", File.expand_path("~/.anima/tmp/pids/puma.pid"))
+
+plugin :tmp_restart

data/config/routes.rb

@@ -1,4 +1,12 @@
 # frozen_string_literal: true
 
 Rails.application.routes.draw do
+  mount ActionCable.server => "/cable"
+  get "up", to: "rails/health#show", as: :rails_health_check
+
+  namespace :api do
+    resources :sessions, only: [:create] do
+      get :current, on: :collection
+    end
+  end
 end

data/config.ru

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "config/environment"
+
+run Rails.application

data/db/cable_schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema[8.1].define(version: 1) do
+  create_table "solid_cable_messages", force: :cascade do |t|
+    t.binary "channel", limit: 1024, null: false
+    t.binary "payload", limit: 536870912, null: false
+    t.datetime "created_at", null: false
+    t.integer "channel_hash", limit: 8, null: false
+    t.index ["channel"], name: "index_solid_cable_messages_on_channel"
+    t.index ["channel_hash"], name: "index_solid_cable_messages_on_channel_hash"
+    t.index ["created_at"], name: "index_solid_cable_messages_on_created_at"
+  end
+end

data/lib/agent_loop.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Orchestrates the LLM agent loop: accepts user input, runs the tool-use
+# cycle via {LLM::Client}, and emits events through {Events::Bus}.
+#
+# Extracted from {TUI::Screens::Chat} so the same agent logic can run from
+# the TUI, a background job, or an Action Cable channel.
+#
+# @note Not thread-safe. Callers must serialize concurrent calls to {#process}
+#   (e.g. TUI uses a loading flag, future callers should use session-level locks).
+#
+# @example Basic usage
+#   loop = AgentLoop.new(session: session)
+#   loop.process("What files are in the current directory?")
+#   loop.finalize
+#
+# @example With dependency injection (testing)
+#   loop = AgentLoop.new(session: session, client: mock_client, registry: mock_registry)
+#   loop.process("hello")
+#
+# @example Background job usage (retry-safe)
+#   loop = AgentLoop.new(session: session)
+#   loop.run  # processes persisted session messages without emitting UserMessage
+#   loop.finalize
+class AgentLoop
+  # @return [Session] the conversation session this loop operates on
+  attr_reader :session
+
+  # @param session [Session] the conversation session
+  # @param shell_session [ShellSession, nil] injectable persistent shell;
+  #   created automatically if not provided
+  # @param client [LLM::Client, nil] injectable LLM client;
+  #   created lazily on first {#process} call if not provided
+  # @param registry [Tools::Registry, nil] injectable tool registry;
+  #   built lazily on first {#process} call if not provided
+  def initialize(session:, shell_session: nil, client: nil, registry: nil)
+    @session = session
+    @shell_session = shell_session || ShellSession.new(session_id: session.id)
+    @client = client
+    @registry = registry
+  end
+
+  # Runs the agent loop for a single user input.
+  #
+  # Emits {Events::UserMessage} immediately, then delegates to {#run}.
+  # On error emits {Events::AgentMessage} with the error text.
+  #
+  # @param input [String] raw user input
+  # @return [String, nil] the agent's response text, or nil for blank input
+  def process(input)
+    text = input.to_s.strip
+    return if text.empty?
+
+    Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
+    run
+  rescue => error
+    error_message = "#{error.class}: #{error.message}"
+    Events::Bus.emit(Events::AgentMessage.new(content: error_message, session_id: @session.id))
+    error_message
+  end
+
+  # Runs the LLM tool-use loop on persisted session messages.
+  #
+  # Unlike {#process}, does not emit {Events::UserMessage} and lets errors
+  # propagate — designed for callers like {AgentRequestJob} that handle
+  # retries and need errors to bubble up.
+  #
+  # @return [String] the agent's response text
+  # @raise [Providers::Anthropic::TransientError] on retryable network/server errors
+  # @raise [Providers::Anthropic::AuthenticationError] on auth failures
+  def run
+    @client ||= LLM::Client.new
+    @registry ||= build_tool_registry
+
+    messages = @session.messages_for_llm
+    response = @client.chat_with_tools(messages, registry: @registry, session_id: @session.id)
+    Events::Bus.emit(Events::AgentMessage.new(content: response, session_id: @session.id))
+    response
+  end
+
+  # Clean up the underlying {ShellSession} PTY and resources.
+  # Safe to call multiple times — subsequent calls are no-ops.
+  def finalize
+    @shell_session&.finalize
+  end
+
+  private
+
+  # Builds the default tool registry with all available tools.
+  # @return [Tools::Registry] registry with Bash and WebGet tools
+  def build_tool_registry
+    registry = Tools::Registry.new(context: {shell_session: @shell_session})
+    registry.register(Tools::WebGet)
+    registry.register(Tools::Bash)
+    registry
+  end
+end

data/lib/anima/cli.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require "thor"
+require_relative "../anima"
 
 module Anima
   class CLI < Thor
     VALID_ENVIRONMENTS = %w[development test production].freeze
+    DEFAULT_PORT = 42134
+    DEFAULT_HOST = "localhost:#{DEFAULT_PORT}"
 
     def self.exit_on_failure?
       true
@@ -16,10 +19,13 @@ module Anima
       Installer.new.run
     end
 
-    desc "start", "Boot Anima (runs pending migrations, then exits)"
-    option :environment, aliases: "-e", default: "development", desc: "Rails environment"
+    # Start the Anima brain server (Puma + Solid Queue) via Foreman.
+    # Environment precedence: -e flag > RAILS_ENV env var > "development".
+    # Requires prior installation (~/.anima must exist).
+    desc "start", "Start Anima (web + workers)"
+    option :environment, aliases: "-e", desc: "Rails environment (default: $RAILS_ENV or development)"
     def start
-      env = options[:environment]
+      env = options[:environment] || ENV.fetch("RAILS_ENV", "development")
       unless VALID_ENVIRONMENTS.include?(env)
         say "Invalid environment: #{env}. Must be one of: #{VALID_ENVIRONMENTS.join(", ")}", :red
         exit 1
@@ -32,17 +38,29 @@ module Anima
         exit 1
       end
 
-      system(Anima.gem_root.join("bin/rails").to_s, "db:prepare") || abort("db:prepare failed")
-      say "Anima booted successfully (#{env}).", :green
+      gem_root = Anima.gem_root
+      system(gem_root.join("bin/rails").to_s, "db:prepare", chdir: gem_root.to_s) || abort("db:prepare failed")
+      exec("foreman", "start", "-f", gem_root.join("Procfile").to_s, "-p", DEFAULT_PORT.to_s, chdir: gem_root.to_s)
     end
 
     desc "tui", "Launch the Anima terminal interface"
+    option :host, desc: "Brain server address (default: #{DEFAULT_HOST})"
     def tui
       require "ratatui_ruby"
-      ENV["RAILS_ENV"] ||= "development"
-      require_relative "../../config/environment"
-      ActiveRecord::Tasks::DatabaseTasks.prepare_all
-      TUI::App.new.run
+      require "net/http"
+      require "json"
+      require_relative "../tui/app"
+
+      host = options[:host] || DEFAULT_HOST
+
+      say "Connecting to brain at #{host}...", :cyan
+      session_id = fetch_current_session_with_retry(host)
+      say "Session ##{session_id} — starting TUI", :cyan
+
+      cable_client = TUI::CableClient.new(host: host, session_id: session_id)
+      cable_client.connect
+
+      TUI::App.new(cable_client: cable_client).run
     end
 
     desc "version", "Show version"
@@ -51,5 +69,42 @@ module Anima
       require_relative "version"
       say "anima #{Anima::VERSION}"
     end
+
+    private
+
+    MAX_SESSION_FETCH_ATTEMPTS = 10
+    SESSION_FETCH_DELAY = 2 # seconds between retries
+
+    # Fetches the current session ID from the brain's REST API.
+    # Retries up to {MAX_SESSION_FETCH_ATTEMPTS} times if the brain is not running.
+    #
+    # @param host [String] brain server address
+    # @return [Integer] session ID
+    def fetch_current_session_with_retry(host)
+      attempts = 0
+      begin
+        fetch_current_session(host)
+      rescue Errno::ECONNREFUSED, Net::ReadTimeout, Net::OpenTimeout, SocketError => error
+        attempts += 1
+        if attempts >= MAX_SESSION_FETCH_ATTEMPTS
+          say "Cannot connect to brain after #{MAX_SESSION_FETCH_ATTEMPTS} attempts", :red
+          exit 1
+        end
+        say "Brain not available (#{error.class.name.split("::").last}). " \
+            "Retrying #{attempts}/#{MAX_SESSION_FETCH_ATTEMPTS}... (Ctrl+C to cancel)", :yellow
+        sleep SESSION_FETCH_DELAY
+        retry
+      end
+    end
+
+    # Fetches the current session ID from the brain's REST API.
+    # @param host [String] brain server address
+    # @return [Integer] session ID
+    # @raise [RuntimeError] if the brain returns an error response
+    def fetch_current_session(host)
+      uri = URI("http://#{host}/api/sessions/current")
+      body = Net::HTTP.get(uri)
+      JSON.parse(body)["id"]
+    end
   end
 end

data/lib/anima/installer.rb

@@ -29,7 +29,7 @@ module Anima
       create_config_file
       generate_credentials
       create_systemd_service
-      say "Installation complete. Run 'anima start' to begin."
+      say "Installation complete. Brain is running. Connect with 'anima tui'."
     end
 
     def create_directories
@@ -96,10 +96,9 @@ module Anima
 
         [Service]
         Type=simple
-        ExecStart=#{anima_bin} start
+        ExecStart=#{anima_bin} start -e production
         Restart=on-failure
         RestartSec=5
-        Environment=RAILS_ENV=production
 
         [Install]
         WantedBy=default.target
@@ -107,6 +106,8 @@ module Anima
 
       say "  created #{service_path}"
       system("systemctl", "--user", "daemon-reload", err: File::NULL, out: File::NULL)
+      system("systemctl", "--user", "enable", "--now", "anima.service", err: File::NULL, out: File::NULL)
+      say "  enabled and started anima.service"
     end
 
     private

data/lib/anima/version.rb

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

data/lib/anima.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pathname"
 require_relative "anima/version"
 
 module Anima

data/lib/events/subscribers/action_cable_bridge.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Forwards EventBus events to Action Cable, bridging internal pub/sub
+    # to external WebSocket clients. Each event is broadcast to the
+    # session-specific stream (e.g. "session_42"), matching the stream
+    # name used by {SessionChannel}.
+    #
+    # Only events with a valid session_id are broadcast — events without
+    # one have no destination channel and are silently skipped.
+    #
+    # @example
+    #   Events::Bus.subscribe(Events::Subscribers::ActionCableBridge.instance)
+    #   # Now all events with session_id flow to "session_<id>" streams
+    class ActionCableBridge
+      include Events::Subscriber
+      include Singleton
+
+      # Receives a Rails.event notification hash and broadcasts the payload
+      # to the session's Action Cable stream.
+      #
+      # @param event [Hash] with :payload containing event data including :session_id
+      def emit(event)
+        payload = event[:payload]
+        return unless payload.is_a?(Hash)
+
+        session_id = payload[:session_id]
+        return if session_id.nil?
+
+        ActionCable.server.broadcast("session_#{session_id}", payload)
+      end
+    end
+  end
+end

data/lib/events/subscribers/persister.rb

@@ -5,16 +5,23 @@ module Events
     # Persists all events to SQLite as they flow through the event bus.
     # Each event is written as an Event record belonging to the active session.
     #
-    # @example
-    #   session = Session.create!
+    # When initialized with a specific session, all events are saved to that
+    # session. When initialized without one (global mode), the session is
+    # looked up from the event's session_id payload field.
+    #
+    # @example Session-scoped
     #   persister = Events::Subscribers::Persister.new(session)
     #   Events::Bus.subscribe(persister)
+    #
+    # @example Global (persists events for any session)
+    #   persister = Events::Subscribers::Persister.new
+    #   Events::Bus.subscribe(persister)
     class Persister
       include Events::Subscriber
 
       attr_reader :session
 
-      def initialize(session)
+      def initialize(session = nil)
         @session = session
         @mutex = Mutex.new
       end
@@ -28,8 +35,11 @@ module Events
         event_type = payload[:type]
         return if event_type.nil?
 
+        target_session = @session || Session.find_by(id: payload[:session_id])
+        return unless target_session
+
         @mutex.synchronize do
-          @session.events.create!(
+          target_session.events.create!(
             event_type: event_type,
             payload: payload,
             tool_use_id: payload[:tool_use_id],

data/lib/providers/anthropic.rb

@@ -19,6 +19,11 @@ module Providers
     class AuthenticationError < Error; end
     class TokenFormatError < Error; end
 
+    # Transient errors that may succeed on retry (network issues, rate limits, server errors).
+    class TransientError < Error; end
+    class RateLimitError < TransientError; end
+    class ServerError < TransientError; end
+
     class << self
       def validate!
         token = fetch_token
@@ -75,6 +80,8 @@ module Providers
       )
 
       handle_response(response)
+    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => e
+      raise TransientError, "#{e.class}: #{e.message}"
     end
 
     # Count tokens in a message payload without creating a message.
@@ -96,6 +103,8 @@ module Providers
 
       result = handle_response(response)
       result["input_tokens"]
+    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => e
+      raise TransientError, "#{e.class}: #{e.message}"
     end
 
     def validate_credentials!
@@ -147,9 +156,9 @@ module Providers
         raise AuthenticationError,
           "Forbidden (403): #{error_message(response)}"
       when 429
-        raise Error, "Rate limit exceeded: #{error_message(response)}"
+        raise RateLimitError, "Rate limit exceeded: #{error_message(response)}"
       when 500..599
-        raise Error, "Anthropic server error (#{response.code}): #{response.message}"
+        raise ServerError, "Anthropic server error (#{response.code}): #{response.message}"
       else
         raise Error, "Unexpected response (#{response.code}): #{response.message}"
       end

data/lib/tui/app.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "cable_client"
+require_relative "message_store"
 require_relative "screens/chat"
 require_relative "screens/settings"
 require_relative "screens/anthropic"
@@ -19,13 +21,24 @@ module TUI
 
     SIDEBAR_WIDTH = 28
 
+    # Connection status display styles
+    STATUS_STYLES = {
+      disconnected: {label: " DISCONNECTED ", fg: "white", bg: "red"},
+      connecting: {label: " CONNECTING ", fg: "black", bg: "yellow"},
+      connected: {label: " CONNECTED ", fg: "black", bg: "yellow"},
+      subscribed: {label: " CONNECTED ", fg: "black", bg: "green"},
+      reconnecting: {label: " RECONNECTING ", fg: "black", bg: "yellow"}
+    }.freeze
+
     attr_reader :current_screen, :command_mode
 
-    def initialize
+    # @param cable_client [TUI::CableClient] WebSocket client connected to the brain
+    def initialize(cable_client:)
+      @cable_client = cable_client
       @current_screen = :chat
       @command_mode = false
       @screens = {
-        chat: Screens::Chat.new,
+        chat: Screens::Chat.new(cable_client: cable_client),
         settings: Screens::Settings.new,
         anthropic: Screens::Anthropic.new
       }
@@ -36,9 +49,13 @@ module TUI
         loop do
           tui.draw { |frame| render(frame, tui) }
 
-          break if handle_event(tui.poll_event) == :quit
+          event = tui.poll_event(timeout: 0.1)
+          next if event.nil? || event.none?
+          break if handle_event(event) == :quit
         end
       end
+    ensure
+      @cable_client.disconnect
     end
 
     private
@@ -89,16 +106,29 @@ module TUI
     end
 
     def render_info(frame, area, tui)
-      info_text = tui.line(spans: [
-        tui.span(content: "Anima v#{Anima::VERSION}", style: tui.style(fg: "white"))
-      ])
-      hint_text = tui.line(spans: [
-        tui.span(content: "Ctrl+a", style: tui.style(fg: "cyan", modifiers: [:bold])),
-        tui.span(content: " command mode", style: tui.style(fg: "dark_gray"))
-      ])
+      session = @screens[:chat].session_info
+      lines = [
+        tui.line(spans: [
+          tui.span(content: "Anima v#{Anima::VERSION}", style: tui.style(fg: "white"))
+        ]),
+        tui.line(spans: [tui.span(content: "")]),
+        tui.line(spans: [
+          tui.span(content: "Session ", style: tui.style(fg: "dark_gray")),
+          tui.span(content: "##{session[:id]}", style: tui.style(fg: "cyan", modifiers: [:bold]))
+        ]),
+        tui.line(spans: [
+          tui.span(content: "Messages ", style: tui.style(fg: "dark_gray")),
+          tui.span(content: session[:message_count].to_s, style: tui.style(fg: "cyan"))
+        ]),
+        tui.line(spans: [tui.span(content: "")]),
+        tui.line(spans: [
+          tui.span(content: "Ctrl+a", style: tui.style(fg: "cyan", modifiers: [:bold])),
+          tui.span(content: " command mode", style: tui.style(fg: "dark_gray"))
+        ])
+      ]
 
       info = tui.paragraph(
-        text: [info_text, hint_text],
+        text: lines,
         block: tui.block(
           title: "Info",
           borders: [:all],
@@ -118,10 +148,28 @@ module TUI
         tui.span(content: " NORMAL ", style: tui.style(fg: "black", bg: "cyan", modifiers: [:bold]))
       end
 
-      widget = tui.paragraph(text: tui.line(spans: [mode_span]))
+      conn_span = connection_status_span(tui)
+
+      widget = tui.paragraph(text: tui.line(spans: [mode_span, conn_span]))
       frame.render_widget(widget, area)
     end
 
+    def connection_status_span(tui)
+      cable_status = @cable_client.status
+
+      if cable_status == :reconnecting
+        attempt = @cable_client.reconnect_attempt
+        max = CableClient::MAX_RECONNECT_ATTEMPTS
+        label = " RECONNECTING (#{attempt}/#{max}) "
+        style = STATUS_STYLES[:reconnecting]
+      else
+        style = STATUS_STYLES.fetch(cable_status, STATUS_STYLES[:disconnected])
+        label = style[:label]
+      end
+
+      tui.span(content: label, style: tui.style(fg: style[:fg], bg: style[:bg], modifiers: [:bold]))
+    end
+
     def chat_loading?
       @screens[:chat].loading?
     end
@@ -157,6 +205,11 @@ module TUI
     end
 
     def handle_normal_mode(event)
+      if event.mouse?
+        delegate_to_screen(event)
+        return nil
+      end
+
       return nil unless event.key?
 
       if ctrl_a?(event)
@@ -169,9 +222,14 @@ module TUI
         return nil
       end
 
+      delegate_to_screen(event)
+      nil
+    end
+
+    # Forwards an event to the active screen for handling
+    def delegate_to_screen(event)
       screen = @screens[@current_screen]
       screen.handle_event(event) if screen.respond_to?(:handle_event)
-      nil
     end
 
     def ctrl_a?(event)