anima-core 0.2.1 → 1.0.0

data/lib/environment_probe.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "etc"
+require "open3"
+require "timeout"
+require "json"
+require "pathname"
+require "uri"
+
+# Probes the shell environment and assembles a lightweight metadata block
+# for injection into the system prompt. Gives the agent awareness of its
+# working directory, OS, Git status, and nearby project files — without
+# loading any file content.
+#
+# @example
+#   EnvironmentProbe.to_prompt("/home/user/projects/my-app")
+#   # => "## Environment\n\nOS: Arch Linux (pacman, yay)\n..."
+class EnvironmentProbe
+  # Assembles the environment context block for a given working directory.
+  #
+  # @param pwd [String, nil] current working directory
+  # @return [String, nil] Markdown-formatted environment block, or nil when pwd is unknown
+  def self.to_prompt(pwd)
+    new(pwd).to_prompt
+  end
+
+  # @param pwd [String, nil] current working directory
+  def initialize(pwd)
+    @pwd = pwd
+  end
+
+  # @return [String, nil] Markdown-formatted environment block
+  def to_prompt
+    return unless @pwd
+
+    sections = [os_section, working_directory_section, project_files_section].compact
+    return if sections.empty?
+
+    "## Environment\n\n#{sections.join("\n\n")}"
+  end
+
+  private
+
+  # @return [String] OS name with package manager hint
+  def os_section
+    sysname = Etc.uname[:sysname]
+    "OS: #{format_os(sysname)}"
+  end
+
+  # @param sysname [String] kernel name from uname (e.g. "Linux", "Darwin")
+  # @return [String] human-readable OS description
+  def format_os(sysname)
+    case sysname
+    when "Linux"
+      distro = detect_linux_distro || "Linux"
+      pkg = detect_package_manager
+      pkg ? "#{distro} (#{pkg})" : distro
+    when "Darwin"
+      "macOS (Homebrew)"
+    else
+      sysname
+    end
+  end
+
+  # Reads PRETTY_NAME from /etc/os-release.
+  #
+  # @return [String, nil] distro name, or nil on non-Linux / missing file
+  def detect_linux_distro
+    return unless File.exist?("/etc/os-release")
+
+    File.foreach("/etc/os-release") do |line|
+      if line.start_with?("PRETTY_NAME=")
+        return line.split("=", 2).last.strip.delete('"')
+      end
+    end
+    nil
+  end
+
+  # Returns the primary package manager(s) for the current system.
+  # Arch-based systems list both pacman and yay when present;
+  # other families return the first match.
+  #
+  # @return [String, nil] comma-separated package manager names
+  def detect_package_manager
+    managers = []
+    managers << "pacman" if File.exist?("/usr/bin/pacman")
+    managers << "yay" if File.exist?("/usr/bin/yay")
+    return managers.join(", ") if managers.any?
+
+    return "apt" if File.exist?("/usr/bin/apt")
+    return "dnf" if File.exist?("/usr/bin/dnf")
+    return "Homebrew" if File.exist?("/opt/homebrew/bin/brew") || File.exist?("/usr/local/bin/brew")
+
+    nil
+  end
+
+  # @return [String] CWD line plus optional Git metadata
+  def working_directory_section
+    lines = ["CWD: #{@pwd}"]
+    append_git_lines(lines)
+    lines.join("\n")
+  end
+
+  # Appends Git metadata lines (remote, branch, PR) to the output array.
+  #
+  # @param lines [Array<String>] accumulator for output lines
+  # @return [void]
+  def append_git_lines(lines)
+    git = detect_git
+    return unless git
+
+    remote = git[:remote]
+    branch = git[:branch]
+    pr_number = git[:pr_number]
+
+    lines << "Git: #{git[:repo_name]} (#{remote})" if remote
+    lines << "Branch: #{branch}" if branch
+    lines << "PR: ##{pr_number} (#{git[:pr_state]})" if pr_number
+  end
+
+  # Detects Git repo metadata: remote, branch, and open PR.
+  #
+  # @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")
+    return unless status.success?
+
+    info = {}
+    detect_git_remote(info)
+    detect_git_branch(info)
+    info
+  rescue Errno::ENOENT
+    nil
+  end
+
+  # 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 = remote.strip
+    return unless remote.present?
+
+    info[:remote] = remote
+    info[:repo_name] = extract_repo_name(remote)
+  end
+
+  # 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 = branch.strip
+    return unless branch.present?
+
+    info[:branch] = branch
+    pr = detect_pr(branch)
+    info.merge!(pr) if pr
+  end
+
+  # Extracts owner/repo from a Git remote URL.
+  #
+  # @param remote_url [String] SSH or HTTPS remote URL
+  # @return [String] "owner/repo" path, or the raw URL when parsing fails
+  def extract_repo_name(remote_url)
+    path = if remote_url.match?(%r{\A\w+://})
+      URI.parse(remote_url).path
+    else
+      # SSH format: git@host:owner/repo.git
+      remote_url.split(":").last
+    end
+    path.delete_prefix("/").delete_suffix(".git")
+  rescue URI::InvalidURIError
+    remote_url
+  end
+
+  # Queries GitHub for an open PR on the given branch via the gh CLI.
+  #
+  # @param branch [String] branch name
+  # @return [Hash, nil] with :pr_number and :pr_state, or nil
+  # @note Returns nil on timeout, missing gh CLI, or JSON parse errors
+  def detect_pr(branch)
+    Timeout.timeout(Anima::Settings.web_request_timeout) do
+      output, status = Open3.capture2(
+        "gh", "pr", "list", "--head", branch,
+        "--json", "number,state", "--limit", "1",
+        chdir: @pwd
+      )
+      return unless status.success?
+
+      pr = JSON.parse(output).first
+      return unless pr
+
+      {pr_number: pr["number"], pr_state: pr["state"].downcase}
+    end
+  rescue Timeout::Error, Errno::ENOENT, JSON::ParserError
+    nil
+  end
+
+  # Scans for well-known project files up to a configurable depth.
+  #
+  # @return [String, nil] project files section, or nil when none found
+  def project_files_section
+    found = scan_project_files
+    return if found.empty?
+
+    header = "Project files that may contain useful context:"
+    entries = found.map { |path| "- #{path}" }
+    [header, *entries, "Use read_file to examine these when needed."].join("\n")
+  end
+
+  # Scans the working directory for whitelisted filenames.
+  #
+  # @return [Array<String>] sorted relative paths
+  def scan_project_files
+    base = Pathname.new(@pwd)
+
+    glob_patterns.flat_map { |pattern| Dir.glob(pattern) }
+      .map { |full_path| Pathname.new(full_path).relative_path_from(base).to_s }
+      .sort
+      .uniq
+  end
+
+  # Builds glob patterns for each whitelisted filename at each depth level.
+  #
+  # @return [Array<String>] glob patterns
+  def glob_patterns
+    whitelist = Anima::Settings.project_files_whitelist
+    max_depth = Anima::Settings.project_files_max_depth
+
+    whitelist.product((0..max_depth).to_a).map do |filename, depth|
+      File.join(@pwd, Array.new(depth, "*"), filename)
+    end
+  end
+end

data/lib/events/subscribers/persister.rb

@@ -42,6 +42,7 @@ module Events
           target_session.events.create!(
             event_type: event_type,
             payload: payload,
+            status: payload[:status],
             tool_use_id: payload[:tool_use_id],
             timestamp: payload[:timestamp] || Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
           )

data/lib/events/user_message.rb

@@ -4,8 +4,25 @@ module Events
   class UserMessage < Base
     TYPE = "user_message"
 
+    # @return [String, nil] "pending" when queued during active processing, nil otherwise
+    attr_reader :status
+
+    # @param content [String] message text
+    # @param session_id [Integer, nil] session identifier
+    # @param status [String, nil] "pending" when queued during active agent processing
+    def initialize(content:, session_id: nil, status: nil)
+      super(content: content, session_id: session_id)
+      @status = status
+    end
+
     def type
       TYPE
     end
+
+    def to_h
+      h = super
+      h[:status] = status if status
+      h
+    end
   end
 end

data/lib/llm/client.rb

@@ -15,10 +15,6 @@ module LLM
   #   registry.register(Tools::WebGet)
   #   client.chat_with_tools(messages, registry: registry, session_id: session.id)
   class Client
-    DEFAULT_MODEL = "claude-sonnet-4-20250514"
-    DEFAULT_MAX_TOKENS = 8192
-    MAX_TOOL_ROUNDS = 25
-
     # @return [Providers::Anthropic] the underlying API provider
     attr_reader :provider
 
@@ -28,14 +24,16 @@ module LLM
     # @return [Integer] maximum tokens in the response
     attr_reader :max_tokens
 
-    # @param model [String] Anthropic model identifier
-    # @param max_tokens [Integer] maximum tokens in the response
+    # @param model [String] Anthropic model identifier (default from Settings)
+    # @param max_tokens [Integer] maximum tokens in the response (default from Settings)
     # @param provider [Providers::Anthropic, nil] injectable provider instance;
     #   defaults to a new {Providers::Anthropic} using credentials
-    def initialize(model: DEFAULT_MODEL, max_tokens: DEFAULT_MAX_TOKENS, provider: nil)
+    # @param logger [Logger, nil] optional logger for tool call tracing
+    def initialize(model: Anima::Settings.model, max_tokens: Anima::Settings.max_tokens, provider: nil, logger: nil)
       @provider = build_provider(provider)
       @model = model
       @max_tokens = max_tokens
+      @logger = logger
     end
 
     # Send messages to the LLM and return the assistant's text response.
@@ -75,8 +73,9 @@ module LLM
 
       loop do
         rounds += 1
-        if rounds > MAX_TOOL_ROUNDS
-          return "[Tool loop exceeded #{MAX_TOOL_ROUNDS} rounds — halting]"
+        max_rounds = Anima::Settings.max_tool_rounds
+        if rounds > max_rounds
+          return "[Tool loop exceeded #{max_rounds} rounds — halting]"
         end
 
         response = provider.create_message(
@@ -87,6 +86,8 @@ module LLM
           **options
         )
 
+        log(:debug, "stop_reason=#{response["stop_reason"]} content_types=#{(response["content"] || []).map { |b| b["type"] }.join(",")}")
+
         if response["stop_reason"] == "tool_use"
           tool_results = execute_tools(response, registry, session_id)
 
@@ -132,18 +133,30 @@ module LLM
       end
     end
 
+    # Executes a single tool and always returns a tool_result — even if
+    # the tool raises. The LLM requires every tool_use to have a matching
+    # tool_result; a missing result breaks the conversation permanently.
     def execute_single_tool(tool_use, registry, session_id)
       name = tool_use["name"]
       id = tool_use["id"]
       input = tool_use["input"] || {}
 
+      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
       ))
 
-      result = registry.execute(name, input)
+      result = begin
+        registry.execute(name, input)
+      rescue => error
+        Rails.logger.error("Tool #{name} raised #{error.class}: #{error.message}")
+        {error: "#{error.class}: #{error.message}"}
+      end
+
       result_content = format_tool_result(result)
+      log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
 
       Events::Bus.emit(Events::ToolResponse.new(
         content: result_content, tool_name: name, tool_use_id: id,
@@ -154,6 +167,12 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: result_content}
     end
 
+    def log(level, message)
+      return unless @logger
+
+      @logger.public_send(level, message)
+    end
+
     def format_tool_result(result)
       result.is_a?(Hash) ? result.to_json : result.to_s
     end

data/lib/mcp/client_manager.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Mcp
+  # Manages MCP client connections and registers their tools with
+  # {Tools::Registry}. Each configured server (HTTP or stdio) gets
+  # a dedicated {MCP::Client} instance. Tool lists are fetched once
+  # during registration and cached in the registry — subsequent LLM
+  # turns reuse the same tool set without re-querying servers.
+  #
+  # Connection failures are logged and skipped — a misconfigured or
+  # unavailable server does not prevent other servers or built-in
+  # tools from working.
+  #
+  # @example
+  #   manager = Mcp::ClientManager.new
+  #   manager.register_tools(registry)
+  class ClientManager
+    # @param config [Mcp::Config] injectable config for testing
+    def initialize(config: Config.new(logger: Rails.logger))
+      @config = config
+    end
+
+    # Connects to all configured MCP servers and registers their tools
+    # in the given registry. Returns warnings for servers that failed
+    # to load so the caller can surface them to the user.
+    #
+    # @param registry [Tools::Registry] the registry to add tools to
+    # @return [Array<String>] warning messages for servers that failed
+    def register_tools(registry)
+      warnings = []
+      register_transport_tools(@config.http_servers, registry, warnings) { |server| build_http_client(server) }
+      register_transport_tools(@config.stdio_servers, registry, warnings) { |server| build_stdio_client(server) }
+      @config.warnings + warnings
+    end
+
+    private
+
+    # Iterates server configs, builds a client for each via the block,
+    # and registers the server's tools. Failures are logged and collected.
+    #
+    # @param servers [Array<Hash>] server configs from {Mcp::Config}
+    # @param registry [Tools::Registry] registry to register tools in
+    # @param warnings [Array<String>] collects failure messages
+    # @yield [server] block that builds an {MCP::Client} for the server
+    def register_transport_tools(servers, registry, warnings)
+      servers.each do |server|
+        client = yield(server)
+        register_server_tools(server[:name], client, registry)
+      rescue => error
+        message = "MCP: failed to load tools from #{server[:name]}: #{error.message}"
+        Rails.logger.warn(message)
+        warnings << message
+      end
+    end
+
+    # Fetches tools from an MCP client and registers them with
+    # namespaced names in the registry.
+    #
+    # @param server_name [String] server name for tool namespacing
+    # @param client [MCP::Client] connected MCP client
+    # @param registry [Tools::Registry] registry to register tools in
+    def register_server_tools(server_name, client, registry)
+      count = client.tools.map { |mcp_tool|
+        Tools::McpTool.new(server_name: server_name, mcp_client: client, mcp_tool: mcp_tool)
+      }.each { |wrapper| registry.register(wrapper) }.size
+
+      Rails.logger.info("MCP: registered #{count} tools from #{server_name}")
+    end
+
+    # @param server [Hash] server config with +:url+ and +:headers+
+    # @return [MCP::Client]
+    def build_http_client(server)
+      transport = MCP::Client::HTTP.new(url: server[:url], headers: server[:headers])
+      MCP::Client.new(transport: transport)
+    end
+
+    # @param server [Hash] server config with +:command+, +:args+, +:env+
+    # @return [MCP::Client]
+    def build_stdio_client(server)
+      transport = StdioTransport.new(command: server[:command], args: server[:args], env: server[:env])
+      MCP::Client.new(transport: transport)
+    end
+  end
+end

data/lib/mcp/config.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "toml-rb"
+
+module Mcp
+  # Reads and writes MCP server configuration from a TOML file at
+  # {DEFAULT_PATH}. Supports HTTP and stdio transports. Secrets stored
+  # in Rails encrypted credentials are interpolated via
+  # +${credential:key_name}+ syntax in any string value.
+  #
+  # @example Config file format (~/.anima/mcp.toml)
+  #   [servers.mythonix]
+  #   transport = "http"
+  #   url = "http://localhost:3000/mcp/v2"
+  #
+  #   [servers.linear]
+  #   transport = "http"
+  #   url = "https://mcp.linear.app/mcp"
+  #   headers = { Authorization = "Bearer ${credential:linear_api_key}" }
+  #
+  #   [servers.filesystem]
+  #   transport = "stdio"
+  #   command = "mcp-server-filesystem"
+  #   args = ["--root", "/workspace"]
+  class Config
+    DEFAULT_PATH = File.expand_path("~/.anima/mcp.toml")
+
+    # Pattern matching `${credential:key_name}` for credential interpolation.
+    CREDENTIAL_PATTERN = /\$\{credential:(\w+)\}/
+
+    # Bare TOML keys: letters, digits, hyphens, underscores.
+    VALID_NAME_PATTERN = /\A[A-Za-z0-9_-]+\z/
+
+    # Warnings accumulated during parsing (missing credentials, invalid entries).
+    # @return [Array<String>]
+    attr_reader :warnings
+
+    # @param path [String] path to the TOML config file
+    # @param logger [#warn, nil] optional logger for warning output
+    def initialize(path: DEFAULT_PATH, logger: nil)
+      @path = path
+      @logger = logger
+      @warnings = []
+      @config_cache = nil
+    end
+
+    # Returns all configured servers with raw (pre-interpolation) settings.
+    # Intended for display in CLI commands where showing literal
+    # +${credential:...}+ placeholders is more useful than resolved values.
+    #
+    # @return [Array<Hash>] servers with string keys from TOML plus +"name"+
+    def all_servers
+      servers = load_config["servers"] || {}
+      servers.map { |name, settings| settings.merge("name" => name) }
+    end
+
+    # Adds a server entry to the configuration file.
+    # Creates the file and parent directories if they don't exist.
+    #
+    # @param name [String] unique server identifier (letters, digits, hyphens, underscores)
+    # @param settings [Hash<String, Object>] server configuration (transport, url/command, etc.)
+    # @raise [ArgumentError] if name is invalid or already exists
+    def add_server(name, settings)
+      validate_name!(name)
+      config = load_config
+      servers = config["servers"] ||= {}
+
+      raise ArgumentError, "server '#{name}' already exists" if servers.key?(name)
+
+      servers[name] = settings
+      write_config(config)
+    end
+
+    # Removes a server entry from the configuration file.
+    #
+    # @param name [String] server identifier to remove
+    # @raise [ArgumentError] if server name not found
+    def remove_server(name)
+      config = load_config
+      servers = config["servers"] || {}
+
+      raise ArgumentError, "server '#{name}' not found" unless servers.key?(name)
+
+      servers.delete(name)
+      write_config(config)
+    end
+
+    # Returns HTTP server configurations from the config file.
+    #
+    # @return [Array<Hash>] server configs with +:name+, +:url+, +:headers+ keys
+    def http_servers
+      servers_by_transport("http") do |name, settings|
+        url = settings["url"]
+        unless url
+          warn_and_skip("server '#{name}' has transport=http but no url")
+          next
+        end
+
+        {
+          name: name,
+          url: interpolate_credentials(url),
+          headers: interpolate_hash_values(settings["headers"] || {})
+        }
+      end
+    end
+
+    # Returns stdio server configurations from the config file.
+    #
+    # @return [Array<Hash>] server configs with +:name+, +:command+, +:args+, +:env+ keys
+    def stdio_servers
+      servers_by_transport("stdio") do |name, settings|
+        command = settings["command"]
+        unless command
+          warn_and_skip("server '#{name}' has transport=stdio but no command")
+          next
+        end
+
+        {
+          name: name,
+          command: interpolate_credentials(command),
+          args: (settings["args"] || []).map { |arg| interpolate_credentials(arg) },
+          env: interpolate_hash_values(settings["env"] || {})
+        }
+      end
+    end
+
+    private
+
+    # Reads the TOML config file, returning an empty hash when missing.
+    # Result is cached for the lifetime of this Config instance; mutating
+    # callers (+add_server+, +remove_server+) invalidate the cache on write.
+    #
+    # @return [Hash] parsed TOML config
+    def load_config
+      @config_cache ||= if File.exist?(@path)
+        TomlRB.load_file(@path)
+      else
+        {}
+      end
+    end
+
+    # Serializes config hash to TOML and writes to disk.
+    # Creates parent directories if needed. Sets restrictive permissions
+    # since config may contain API keys or auth headers.
+    def write_config(config)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, TomlRB.dump(config))
+      File.chmod(0o600, @path)
+      @config_cache = nil
+    end
+
+    # @raise [ArgumentError] if name contains characters invalid for TOML bare keys
+    def validate_name!(name)
+      return if name.match?(VALID_NAME_PATTERN)
+
+      raise ArgumentError,
+        "invalid server name '#{name}' — use only letters, numbers, hyphens, and underscores"
+    end
+
+    # Iterates servers matching a given transport type, yielding each
+    # for transport-specific parsing. Servers referencing missing
+    # credentials are skipped with a warning — one bad server config
+    # must not prevent others from loading.
+    #
+    # @param transport [String] transport type to filter by ("http", "stdio")
+    # @yield [name, settings] block that returns a parsed server hash or nil
+    # @return [Array<Hash>] parsed server configs
+    def servers_by_transport(transport)
+      servers = load_config["servers"] || {}
+
+      servers.filter_map do |name, settings|
+        next unless settings["transport"] == transport
+
+        yield(name, settings)
+      rescue KeyError => error
+        warn_and_skip("server '#{name}' references missing credential #{error.message}")
+        nil
+      end
+    end
+
+    # Logs a warning and collects it for the caller to surface.
+    def warn_and_skip(detail)
+      message = "MCP: #{detail} — skipping"
+      @logger&.warn(message)
+      @warnings << message
+    end
+
+    # Replaces +${credential:key_name}+ placeholders with values from
+    # Rails encrypted credentials via {Mcp::Secrets}.
+    #
+    # @param value [String] string potentially containing placeholders
+    # @return [String] interpolated string
+    # @raise [KeyError] if a referenced credential is not stored
+    def interpolate_credentials(value)
+      Anima.boot_rails!
+      require_relative "secrets"
+
+      value.gsub(CREDENTIAL_PATTERN) do
+        key = ::Regexp.last_match(1)
+        Secrets.get(key) || raise(KeyError, key)
+      end
+    end
+
+    # Interpolates credentials in all values of a string hash.
+    #
+    # @param hash [Hash<String, String>] key-value pairs with potential placeholders
+    # @return [Hash<String, String>] hash with interpolated values
+    def interpolate_hash_values(hash)
+      hash.transform_values { |value| interpolate_credentials(value) }
+    end
+  end
+end