anima-core 0.3.0 → 1.0.0

data/lib/anima/installer.rb

@@ -7,6 +7,8 @@ require "pathname"
 module Anima
   class Installer
     DIRECTORIES = %w[
+      agents
+      skills
       db
       config/credentials
       log
@@ -16,6 +18,7 @@ module Anima
     ].freeze
 
     ANIMA_HOME = Pathname.new(File.expand_path("~/.anima")).freeze
+    TEMPLATE_DIR = File.expand_path("../../templates", __dir__).freeze
 
     attr_reader :anima_home
 
@@ -26,7 +29,10 @@ module Anima
     def run
       say "Installing Anima to #{anima_home}..."
       create_directories
+      create_soul_file
       create_config_file
+      create_settings_config
+      create_mcp_config
       generate_credentials
       create_systemd_service
       say "Installation complete. Brain is running. Connect with 'anima tui'."
@@ -42,6 +48,18 @@ module Anima
       end
     end
 
+    # Copies the soul template to ~/.anima/soul.md — the agent's
+    # self-authored identity file. Skips if the file already exists
+    # so agent-written content is never overwritten.
+    def create_soul_file
+      soul_path = anima_home.join("soul.md")
+      return if soul_path.exist?
+
+      template = File.join(TEMPLATE_DIR, "soul.md")
+      soul_path.write(File.read(template))
+      say "  created #{soul_path}"
+    end
+
     def create_config_file
       config_path = anima_home.join("config", "anima.yml")
       return if config_path.exist?
@@ -53,6 +71,156 @@ module Anima
       say "  created #{config_path}"
     end
 
+    def create_settings_config
+      config_path = anima_home.join("config.toml")
+      return if config_path.exist?
+
+      config_path.write(<<~TOML)
+        # Anima Configuration
+        #
+        # Edit settings below to customize Anima's behavior.
+        # Changes take effect immediately — no restart needed.
+
+        # ─── LLM ───────────────────────────────────────────────────────
+
+        [llm]
+
+        # Primary model for conversations.
+        model = "claude-sonnet-4-20250514"
+
+        # Lightweight model for fast tasks (e.g. session naming).
+        fast_model = "claude-haiku-4-5"
+
+        # Maximum tokens per LLM response.
+        max_tokens = 8192
+
+        # Maximum consecutive tool execution rounds per request.
+        max_tool_rounds = 25
+
+        # Context window budget — tokens reserved for conversation history.
+        # Set this based on your model's context window minus system prompt.
+        token_budget = 190_000
+
+        # ─── Timeouts (seconds) ─────────────────────────────────────────
+
+        [timeouts]
+
+        # LLM API request timeout.
+        api = 30
+
+        # Shell command execution timeout.
+        command = 30
+
+        # MCP server response timeout.
+        mcp_response = 60
+
+        # Web fetch request timeout.
+        web_request = 10
+
+        # ─── Shell ──────────────────────────────────────────────────────
+
+        [shell]
+
+        # Maximum bytes of command output before truncation.
+        max_output_bytes = 100_000
+
+        # ─── Tools ──────────────────────────────────────────────────────
+
+        [tools]
+
+        # Maximum file size for read/edit operations (bytes).
+        max_file_size = 10_485_760
+
+        # Maximum lines returned by the read tool.
+        max_read_lines = 2_000
+
+        # Maximum bytes returned by the read tool.
+        max_read_bytes = 50_000
+
+        # Maximum bytes from web GET responses.
+        max_web_response_bytes = 100_000
+
+        # ─── Environment ──────────────────────────────────────────────
+
+        [environment]
+
+        # Files to scan for in the working directory (at root and up to project_files_max_depth subdirectories deep).
+        project_files = ["CLAUDE.md", "AGENTS.md", "README.md", "CONTRIBUTING.md"]
+
+        # Maximum directory depth for project file scanning.
+        project_files_max_depth = 3
+
+        # ─── GitHub ─────────────────────────────────────────────────────
+
+        [github]
+
+        # Repository for agent feature requests (owner/repo format).
+        # Falls back to parsing git remote origin when unset.
+        repo = "hoblin/anima"
+
+        # Label applied to agent-created feature request issues.
+        label = "anima-wants"
+
+        # ─── Paths ─────────────────────────────────────────────────────
+
+        [paths]
+
+        # The agent's self-authored identity file.
+        soul = "#{anima_home.join("soul.md")}"
+
+        # ─── Session ────────────────────────────────────────────────────
+
+        [session]
+
+        # Regenerate session name every N messages.
+        name_generation_interval = 30
+
+        # ─── Analytical Brain ─────────────────────────────────────────
+
+        [analytical_brain]
+
+        # Maximum tokens per analytical brain response.
+        # Must accommodate multiple tool calls (rename + goals + skills + ready).
+        max_tokens = 4096
+
+        # Run the analytical brain synchronously before the main agent on user messages.
+        # Ensures activated skills are available for the current response.
+        blocking_on_user_message = true
+
+        # Run the analytical brain asynchronously after the main agent completes.
+        blocking_on_agent_message = false
+
+        # Number of recent events to include in the analytical brain's context window.
+        event_window = 20
+      TOML
+      say "  created #{config_path}"
+    end
+
+    def create_mcp_config
+      config_path = anima_home.join("mcp.toml")
+      return if config_path.exist?
+
+      config_path.write(<<~TOML)
+        # MCP server configuration
+        # Declare MCP servers here. Anima connects on startup and
+        # registers their tools alongside built-in ones.
+        #
+        # HTTP transport:
+        # [servers.example]
+        # transport = "http"
+        # url = "http://localhost:3000/mcp/v2"
+        # headers = { Authorization = "Bearer ${API_KEY}" }
+        #
+        # Stdio transport:
+        # [servers.example]
+        # transport = "stdio"
+        # command = "my-mcp-server"
+        # args = ["--verbose"]
+        # env = { API_KEY = "${API_KEY}" }
+      TOML
+      say "  created #{config_path}"
+    end
+
     def generate_credentials
       require "active_support"
       require "active_support/encrypted_configuration"

data/lib/anima/settings.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+
+module Anima
+  # User-facing configuration backed by +~/.anima/config.toml+ with hot-reload.
+  #
+  # Reads the TOML config file on each access, re-parsing only when the file's
+  # mtime has changed. The config file is created by the installer with all
+  # values set — it is the single source of truth for all settings.
+  #
+  # Settings are grouped into sections that mirror the TOML file structure:
+  #
+  #   [llm]       — Model selection and response limits
+  #   [timeouts]  — Network and execution timeouts (seconds)
+  #   [shell]     — Shell command output limits
+  #   [tools]     — File and web tool limits
+  #   [session]   — Conversation behavior
+  #
+  # @example Reading a setting
+  #   Anima::Settings.model          #=> "claude-sonnet-4-20250514"
+  #   Anima::Settings.api_timeout    #=> 30
+  #
+  # @example Hot-reload (no restart needed)
+  #   Anima::Settings.model  #=> "claude-sonnet-4-20250514"
+  #   # user edits ~/.anima/config.toml: model = "claude-haiku-4-5"
+  #   Anima::Settings.model  #=> "claude-haiku-4-5"
+  #
+  # @see Anima::Installer#create_settings_config creates the config file
+  module Settings
+    DEFAULT_PATH = File.expand_path("~/.anima/config.toml")
+
+    class MissingConfigError < StandardError; end
+    class MissingSettingError < StandardError; end
+
+    @config_path = nil
+    @config_cache = nil
+    @config_mtime = nil
+    @cache_mutex = Mutex.new
+
+    class << self
+      # Override config file path (for testing).
+      # Resets the cache so the next access reads from the new location.
+      #
+      # @param path [String, nil] custom path, or +nil+ to restore default
+      def config_path=(path)
+        @config_path = path
+        @config_cache = nil
+        @config_mtime = nil
+      end
+
+      # @return [String] active config file path
+      def config_path
+        @config_path || DEFAULT_PATH
+      end
+
+      # Resets to default path and clears cached config.
+      # Useful in test teardown.
+      def reset!
+        self.config_path = nil
+      end
+
+      # ─── LLM ───────────────────────────────────────────────────────
+
+      # Primary model for conversations.
+      # @return [String] Anthropic model identifier
+      def model = get("llm", "model")
+
+      # Lightweight model for fast tasks (e.g. session naming).
+      # @return [String] Anthropic model identifier
+      def fast_model = get("llm", "fast_model")
+
+      # Maximum tokens per LLM response.
+      # @return [Integer]
+      def max_tokens = get("llm", "max_tokens")
+
+      # Maximum consecutive tool execution rounds per LLM message.
+      # Prevents runaway tool loops.
+      # @return [Integer]
+      def max_tool_rounds = get("llm", "max_tool_rounds")
+
+      # Context window budget — tokens reserved for conversation history.
+      # Set this based on your model's context window minus system prompt.
+      # @return [Integer]
+      def token_budget = get("llm", "token_budget")
+
+      # ─── Timeouts (seconds) ────────────────────────────────────────
+
+      # LLM API request timeout.
+      # @return [Integer] seconds
+      def api_timeout = get("timeouts", "api")
+
+      # Shell command execution timeout.
+      # @return [Integer] seconds
+      def command_timeout = get("timeouts", "command")
+
+      # MCP server response timeout.
+      # @return [Integer] seconds
+      def mcp_response_timeout = get("timeouts", "mcp_response")
+
+      # Web fetch request timeout.
+      # @return [Integer] seconds
+      def web_request_timeout = get("timeouts", "web_request")
+
+      # ─── Shell ──────────────────────────────────────────────────────
+
+      # Maximum bytes of command output before truncation.
+      # @return [Integer]
+      def max_output_bytes = get("shell", "max_output_bytes")
+
+      # ─── Tools ──────────────────────────────────────────────────────
+
+      # Maximum file size for read/edit operations (bytes).
+      # @return [Integer]
+      def max_file_size = get("tools", "max_file_size")
+
+      # Maximum lines returned by the read tool.
+      # @return [Integer]
+      def max_read_lines = get("tools", "max_read_lines")
+
+      # Maximum bytes returned by the read tool.
+      # @return [Integer]
+      def max_read_bytes = get("tools", "max_read_bytes")
+
+      # Maximum bytes from web GET responses.
+      # @return [Integer]
+      def max_web_response_bytes = get("tools", "max_web_response_bytes")
+
+      # ─── Session ────────────────────────────────────────────────────
+
+      # Regenerate session name every N messages.
+      # @return [Integer]
+      def name_generation_interval = get("session", "name_generation_interval")
+
+      # ─── Paths ───────────────────────────────────────────────────────
+
+      # Path to the soul file — the agent's self-authored identity.
+      # @return [String] absolute path
+      def soul_path = get("paths", "soul")
+
+      # ─── Environment ──────────────────────────────────────────────
+
+      # Filenames to scan for in the working directory.
+      # @return [Array<String>]
+      def project_files_whitelist = get("environment", "project_files")
+
+      # Maximum directory depth for project file scanning.
+      # @return [Integer]
+      def project_files_max_depth = get("environment", "project_files_max_depth")
+
+      # ─── GitHub ─────────────────────────────────────────────────────
+
+      # Repository for feature requests (+owner/repo+ format).
+      # Falls back to parsing git remote origin when unset.
+      # @return [String]
+      def github_repo = get("github", "repo")
+
+      # Label applied to agent-created feature request issues.
+      # @return [String]
+      def github_label = get("github", "label")
+
+      # ─── Analytical Brain ─────────────────────────────────────────
+
+      # Maximum tokens per analytical brain response.
+      # @return [Integer]
+      def analytical_brain_max_tokens = get("analytical_brain", "max_tokens")
+
+      # Run the analytical brain synchronously before the main agent on user messages.
+      # @return [Boolean]
+      def analytical_brain_blocking_on_user_message = get("analytical_brain", "blocking_on_user_message")
+
+      # Run the analytical brain asynchronously after the main agent completes.
+      # @return [Boolean]
+      def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")
+
+      # Number of recent events to include in the analytical brain's context window.
+      # @return [Integer]
+      def analytical_brain_event_window = get("analytical_brain", "event_window")
+
+      private
+
+      # Reads a setting from the config file.
+      # Raises if the config file is missing or the key is not defined.
+      #
+      # @param section [String] TOML section name (e.g. "llm")
+      # @param key [String] setting key within the section (e.g. "model")
+      # @return [Object] the configured value
+      # @raise [MissingConfigError] when config.toml does not exist
+      # @raise [MissingSettingError] when the requested key is not in config
+      def get(section, key)
+        value = config.dig(section, key)
+        if value.nil?
+          raise MissingSettingError,
+            "[#{section}] #{key} is not set in #{config_path}. Run `anima install` to create the config file."
+        end
+        value
+      end
+
+      # Loads the TOML config with mtime-based caching.
+      # Re-parses only when the file has been modified since the last read.
+      # Thread-safe via mutex — concurrent callers share the same cache.
+      #
+      # @return [Hash] parsed config
+      # @raise [MissingConfigError] when config.toml does not exist
+      def config
+        @cache_mutex.synchronize do
+          path = config_path
+          unless File.exist?(path)
+            @config_cache = nil
+            @config_mtime = nil
+            raise MissingConfigError,
+              "Config file not found: #{path}. Run `anima install` to create it."
+          end
+
+          current_mtime = File.mtime(path)
+          if current_mtime != @config_mtime
+            @config_mtime = current_mtime
+            @config_cache = TomlRB.load_file(path)
+          end
+
+          @config_cache
+        end
+      end
+    end
+  end
+end

data/lib/anima/version.rb

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

data/lib/anima.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "anima/version"
+require_relative "anima/settings"
 
 module Anima
   class Error < StandardError; end
@@ -9,4 +10,12 @@ module Anima
   def self.gem_root
     @gem_root ||= Pathname.new(File.expand_path("..", __dir__))
   end
+
+  # Boots Rails when CLI commands need access to Rails-managed resources
+  # like encrypted credentials. No-op if Rails is already loaded.
+  def self.boot_rails!
+    return if defined?(Rails)
+
+    require gem_root.join("config", "environment").to_s
+  end
 end

data/lib/credential_store.rb

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