anima-core 0.0.1 → 0.2.0

data/db/queue_schema.rb

@@ -0,0 +1,141 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema[8.1].define(version: 1) do
+  create_table "solid_queue_blocked_executions", force: :cascade do |t|
+    t.string "concurrency_key", null: false
+    t.datetime "created_at", null: false
+    t.datetime "expires_at", null: false
+    t.bigint "job_id", null: false
+    t.integer "priority", default: 0, null: false
+    t.string "queue_name", null: false
+    t.index ["concurrency_key", "priority", "job_id"], name: "index_solid_queue_blocked_executions_for_release"
+    t.index ["expires_at", "concurrency_key"], name: "index_solid_queue_blocked_executions_for_maintenance"
+    t.index ["job_id"], name: "index_solid_queue_blocked_executions_on_job_id", unique: true
+  end
+
+  create_table "solid_queue_claimed_executions", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.bigint "job_id", null: false
+    t.bigint "process_id"
+    t.index ["job_id"], name: "index_solid_queue_claimed_executions_on_job_id", unique: true
+    t.index ["process_id", "job_id"], name: "index_solid_queue_claimed_executions_on_process_id_and_job_id"
+  end
+
+  create_table "solid_queue_failed_executions", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.text "error"
+    t.bigint "job_id", null: false
+    t.index ["job_id"], name: "index_solid_queue_failed_executions_on_job_id", unique: true
+  end
+
+  create_table "solid_queue_jobs", force: :cascade do |t|
+    t.string "active_job_id"
+    t.text "arguments"
+    t.string "class_name", null: false
+    t.string "concurrency_key"
+    t.datetime "created_at", null: false
+    t.datetime "finished_at"
+    t.integer "priority", default: 0, null: false
+    t.string "queue_name", null: false
+    t.datetime "scheduled_at"
+    t.datetime "updated_at", null: false
+    t.index ["active_job_id"], name: "index_solid_queue_jobs_on_active_job_id"
+    t.index ["class_name"], name: "index_solid_queue_jobs_on_class_name"
+    t.index ["finished_at"], name: "index_solid_queue_jobs_on_finished_at"
+    t.index ["queue_name", "finished_at"], name: "index_solid_queue_jobs_for_filtering"
+    t.index ["scheduled_at", "finished_at"], name: "index_solid_queue_jobs_for_alerting"
+  end
+
+  create_table "solid_queue_pauses", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.string "queue_name", null: false
+    t.index ["queue_name"], name: "index_solid_queue_pauses_on_queue_name", unique: true
+  end
+
+  create_table "solid_queue_processes", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.string "hostname"
+    t.string "kind", null: false
+    t.datetime "last_heartbeat_at", null: false
+    t.text "metadata"
+    t.string "name", null: false
+    t.integer "pid", null: false
+    t.bigint "supervisor_id"
+    t.index ["last_heartbeat_at"], name: "index_solid_queue_processes_on_last_heartbeat_at"
+    t.index ["name", "supervisor_id"], name: "index_solid_queue_processes_on_name_and_supervisor_id", unique: true
+    t.index ["supervisor_id"], name: "index_solid_queue_processes_on_supervisor_id"
+  end
+
+  create_table "solid_queue_ready_executions", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.bigint "job_id", null: false
+    t.integer "priority", default: 0, null: false
+    t.string "queue_name", null: false
+    t.index ["job_id"], name: "index_solid_queue_ready_executions_on_job_id", unique: true
+    t.index ["priority", "job_id"], name: "index_solid_queue_poll_all"
+    t.index ["queue_name", "priority", "job_id"], name: "index_solid_queue_poll_by_queue"
+  end
+
+  create_table "solid_queue_recurring_executions", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.bigint "job_id", null: false
+    t.datetime "run_at", null: false
+    t.string "task_key", null: false
+    t.index ["job_id"], name: "index_solid_queue_recurring_executions_on_job_id", unique: true
+    t.index ["task_key", "run_at"], name: "index_solid_queue_recurring_executions_on_task_key_and_run_at", unique: true
+  end
+
+  create_table "solid_queue_recurring_tasks", force: :cascade do |t|
+    t.text "arguments"
+    t.string "class_name"
+    t.string "command", limit: 2048
+    t.datetime "created_at", null: false
+    t.text "description"
+    t.string "key", null: false
+    t.integer "priority", default: 0
+    t.string "queue_name"
+    t.string "schedule", null: false
+    t.boolean "static", default: true, null: false
+    t.datetime "updated_at", null: false
+    t.index ["key"], name: "index_solid_queue_recurring_tasks_on_key", unique: true
+    t.index ["static"], name: "index_solid_queue_recurring_tasks_on_static"
+  end
+
+  create_table "solid_queue_scheduled_executions", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.bigint "job_id", null: false
+    t.integer "priority", default: 0, null: false
+    t.string "queue_name", null: false
+    t.datetime "scheduled_at", null: false
+    t.index ["job_id"], name: "index_solid_queue_scheduled_executions_on_job_id", unique: true
+    t.index ["scheduled_at", "priority", "job_id"], name: "index_solid_queue_dispatch_all"
+  end
+
+  create_table "solid_queue_semaphores", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.datetime "expires_at", null: false
+    t.string "key", null: false
+    t.datetime "updated_at", null: false
+    t.integer "value", default: 1, null: false
+    t.index ["expires_at"], name: "index_solid_queue_semaphores_on_expires_at"
+    t.index ["key", "value"], name: "index_solid_queue_semaphores_on_key_and_value"
+    t.index ["key"], name: "index_solid_queue_semaphores_on_key", unique: true
+  end
+
+  add_foreign_key "solid_queue_blocked_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_claimed_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_failed_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_ready_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_recurring_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_scheduled_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+end

data/db/seeds.rb

@@ -0,0 +1 @@
+# frozen_string_literal: true

data/exe/anima

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/anima/cli"
+
+Anima::CLI.start(ARGV)

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

@@ -0,0 +1,110 @@
+# 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
+    end
+
+    desc "install", "Set up ~/.anima/ with databases, credentials, and systemd service"
+    def install
+      require_relative "installer"
+      Installer.new.run
+    end
+
+    # 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.fetch("RAILS_ENV", "development")
+      unless VALID_ENVIRONMENTS.include?(env)
+        say "Invalid environment: #{env}. Must be one of: #{VALID_ENVIRONMENTS.join(", ")}", :red
+        exit 1
+      end
+
+      ENV["RAILS_ENV"] = env
+
+      unless File.directory?(File.expand_path("~/.anima"))
+        say "Anima is not installed. Run 'anima install' first.", :red
+        exit 1
+      end
+
+      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"
+      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"
+    map %w[-v --version] => :version
+    def version
+      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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+require "pathname"
+
+module Anima
+  class Installer
+    DIRECTORIES = %w[
+      db
+      config/credentials
+      log
+      tmp
+      tmp/pids
+      tmp/cache
+    ].freeze
+
+    ANIMA_HOME = Pathname.new(File.expand_path("~/.anima")).freeze
+
+    attr_reader :anima_home
+
+    def initialize(anima_home: ANIMA_HOME)
+      @anima_home = anima_home
+    end
+
+    def run
+      say "Installing Anima to #{anima_home}..."
+      create_directories
+      create_config_file
+      generate_credentials
+      create_systemd_service
+      say "Installation complete. Brain is running. Connect with 'anima tui'."
+    end
+
+    def create_directories
+      DIRECTORIES.each do |dir|
+        path = anima_home.join(dir)
+        next if path.directory?
+
+        FileUtils.mkdir_p(path)
+        say "  created #{path}"
+      end
+    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 generate_credentials
+      require "active_support"
+      require "active_support/encrypted_configuration"
+
+      %w[production development test].each do |env|
+        content_path = anima_home.join("config", "credentials", "#{env}.yml.enc")
+        key_path = anima_home.join("config", "credentials", "#{env}.key")
+
+        next if key_path.exist? && content_path.exist?
+
+        key = ActiveSupport::EncryptedFile.generate_key
+        key_path.write(key)
+        File.chmod(0o600, key_path.to_s)
+
+        config = ActiveSupport::EncryptedConfiguration.new(
+          config_path: content_path.to_s,
+          key_path: key_path.to_s,
+          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)
+        say "  created credentials for #{env}"
+      end
+    end
+
+    def create_systemd_service
+      service_dir = Pathname.new(File.expand_path("~/.config/systemd/user"))
+      service_path = service_dir.join("anima.service")
+
+      return if service_path.exist?
+
+      FileUtils.mkdir_p(service_dir)
+      anima_bin = File.join(Gem.bindir, "anima")
+
+      service_path.write(<<~UNIT)
+        [Unit]
+        Description=Anima - Personal AI Agent
+        After=network.target
+
+        [Service]
+        Type=simple
+        ExecStart=#{anima_bin} start -e production
+        Restart=on-failure
+        RestartSec=5
+
+        [Install]
+        WantedBy=default.target
+      UNIT
+
+      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
+
+    def say(message)
+      $stdout.puts message
+    end
+  end
+end

data/lib/anima/version.rb

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

data/lib/anima.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require "pathname"
 require_relative "anima/version"
 
 module Anima
   class Error < StandardError; end
+
+  def self.gem_root
+    @gem_root ||= Pathname.new(File.expand_path("..", __dir__))
+  end
 end

data/lib/events/agent_message.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Events
+  class AgentMessage < Base
+    TYPE = "agent_message"
+
+    def type
+      TYPE
+    end
+  end
+end

data/lib/events/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Events
+  # Base class for all Anima events. Subclasses must implement #type
+  # returning a string identifier (e.g. "user_message").
+  #
+  # Events are POROs — they carry typed payloads through the event bus.
+  # Persistence is a separate concern handled by ActiveRecord models.
+  #
+  # @abstract Subclass and implement {#type}
+  class Base
+    attr_reader :content, :session_id, :timestamp
+
+    # @param content [String] event payload content
+    # @param session_id [String, nil] optional session identifier
+    def initialize(content:, session_id: nil)
+      @content = content
+      @session_id = session_id
+      @timestamp = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+    end
+
+    # @return [String] event type identifier
+    # @raise [NotImplementedError] if subclass does not implement
+    def type
+      raise NotImplementedError, "#{self.class} must implement #type"
+    end
+
+    # @return [String] namespaced event name for Rails.event (e.g. "anima.user_message")
+    def event_name
+      "#{Bus::NAMESPACE}.#{type}"
+    end
+
+    # @return [Hash] serialized event payload
+    def to_h
+      {type: type, content: content, session_id: session_id, timestamp: timestamp}
+    end
+  end
+end

data/lib/events/bus.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Events
+  # Central event bus built on Rails Structured Event Reporter.
+  # All Anima events flow through here — subsystems emit events and
+  # subscribers react independently without coupling.
+  #
+  # Subscribers must implement the {Subscriber} interface (#emit method).
+  # Rails.event wraps payloads: subscribers receive a Hash with :name,
+  # :payload (the event's to_h), and :timestamp keys.
+  #
+  # @example Emitting an event
+  #   Events::Bus.emit(Events::UserMessage.new(content: "Hello"))
+  #
+  # @example Subscribing
+  #   subscriber = MySubscriber.new  # must implement #emit(event_hash)
+  #   Events::Bus.subscribe(subscriber)
+  module Bus
+    NAMESPACE = "anima"
+
+    class << self
+      # @param event [Events::Base] the event to broadcast
+      def emit(event)
+        Rails.event.notify(event.event_name, event.to_h)
+      end
+
+      # @param subscriber [#emit] object implementing the Subscriber interface
+      # @param filter [Proc] optional filter block passed to Rails.event
+      def subscribe(subscriber, &filter)
+        Rails.event.subscribe(subscriber, &filter)
+      end
+
+      # @param subscriber [#emit] previously subscribed object
+      def unsubscribe(subscriber)
+        Rails.event.unsubscribe(subscriber)
+      end
+    end
+  end
+end

data/lib/events/subscriber.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Events
+  # Interface for event bus subscribers. Include this module and implement
+  # #emit to receive Rails.event notifications.
+  #
+  # The #emit method receives a Hash from Rails Structured Event Reporter:
+  #   { name: "anima.user_message",
+  #     payload: { type: "user_message", content: "hello", ... },
+  #     timestamp: <nanosecond Integer> }
+  #
+  # @example
+  #   class MySubscriber
+  #     include Events::Subscriber
+  #
+  #     def emit(event)
+  #       content = event.dig(:payload, :content)
+  #       # handle event...
+  #     end
+  #   end
+  module Subscriber
+    def emit(event)
+      raise NotImplementedError, "#{self.class} must implement #emit"
+    end
+  end
+end

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