anima-core 0.2.1 → 1.0.0

data/lib/skills/registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Skills
+  # Loads skill definitions from Markdown files and provides lookup.
+  # Supports two formats:
+  #   - Flat file: skills/skill-name.md
+  #   - Directory: skills/skill-name/SKILL.md (with optional references/ and examples/)
+  # Scans two directories:
+  #   1. Built-in skills shipped with Anima (skills/ in the gem root)
+  #   2. User-defined skills (~/.anima/skills/)
+  # User skills override built-in ones when names collide.
+  class Registry
+    # @return [Hash{String => Definition}] loaded definitions keyed by name
+    attr_reader :skills
+
+    BUILTIN_DIR = File.expand_path("../../skills", __dir__).freeze
+    USER_DIR = File.expand_path("~/.anima/skills").freeze
+
+    def initialize
+      @skills = {}
+    end
+
+    # Returns the global registry, lazily loaded on first access.
+    #
+    # @return [Registry]
+    def self.instance
+      @instance ||= new.load_all
+    end
+
+    # Reloads the global registry from disk.
+    #
+    # @return [Registry]
+    def self.reload!
+      @instance = new.load_all
+    end
+
+    # Loads definitions from both built-in and user directories.
+    # User definitions override built-in ones with the same name.
+    #
+    # @return [self]
+    def load_all
+      load_directory(BUILTIN_DIR)
+      load_directory(USER_DIR)
+      self
+    end
+
+    # Loads skill definitions from a single directory.
+    # Supports flat files (*.md) and directory-based skills (*/SKILL.md).
+    #
+    # @param dir [String] directory path to scan for skill definitions
+    #   (flat .md files and SKILL.md inside subdirectories)
+    # @return [void]
+    def load_directory(dir)
+      return unless Dir.exist?(dir)
+
+      skill_files(dir).each do |path|
+        definition = Definition.from_file(path)
+        @skills[definition.name] = definition
+      rescue InvalidDefinitionError => error
+        Rails.logger.warn("Skipping invalid skill definition #{path}: #{error.message}")
+      end
+    end
+
+    # Looks up a named skill definition.
+    #
+    # @param name [String] skill name
+    # @return [Definition, nil]
+    def find(name)
+      @skills[name]
+    end
+
+    # Skill names and descriptions for inclusion in the analytical brain's context.
+    #
+    # @return [Hash{String => String}] name => description
+    def catalog
+      @skills.transform_values(&:description)
+    end
+
+    # @return [Array<String>] registered skill names
+    def available_names
+      @skills.keys
+    end
+
+    # @return [Boolean]
+    def any?
+      @skills.any?
+    end
+
+    # @return [Integer]
+    def size
+      @skills.size
+    end
+
+    private
+
+    # Finds all skill definition files in a directory — both flat .md files
+    # and SKILL.md files inside subdirectories.
+    #
+    # @param dir [String] directory to scan
+    # @return [Array<String>] sorted paths to skill definition files
+    def skill_files(dir)
+      Dir.glob([File.join(dir, "*.md"), File.join(dir, "*/SKILL.md")]).sort
+    end
+  end
+end

data/lib/tools/edit.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Tools
+  # Performs surgical text replacement with uniqueness constraint.
+  # Finds old_text in the file (must match exactly one location), replaces
+  # with new_text, and returns a unified diff. Falls back to
+  # whitespace-normalized fuzzy matching when exact match fails.
+  #
+  # Normalizes BOM and CRLF line endings for matching, restoring them after
+  # the edit. Rejects ambiguous edits where old_text matches zero or
+  # multiple locations.
+  #
+  # @example Replacing a method body
+  #   tool.execute("path" => "app.rb",
+  #                "old_text" => "def greet\n  'hi'\nend",
+  #                "new_text" => "def greet\n  'hello'\nend")
+  #   # => "--- app.rb\n+++ app.rb\n@@ -1,3 +1,3 @@\n ..."
+  class Edit < Base
+    def self.tool_name = "edit"
+
+    def self.description = "Replace exact text in a file. old_text must match exactly one location; " \
+                           "include surrounding lines for uniqueness. Use for surgical edits; " \
+                           "use write for new files or full replacement."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
+          old_text: {type: "string", description: "Exact text to find (must match exactly one location — include surrounding context if needed)"},
+          new_text: {type: "string", description: "Replacement text (empty string to delete)"}
+        },
+        required: %w[path old_text new_text]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] unified diff showing the change
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, old_text, new_text = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+      return {error: "old_text cannot be blank"} if old_text.empty?
+
+      path = resolve_path(path)
+
+      error = validate_file(path)
+      return error if error
+
+      edit_file(path, old_text, new_text)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      old_text = input["old_text"].to_s
+      new_text = input["new_text"].to_s
+      [path, old_text, new_text]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_file(path)
+      return {error: "File not found: #{path}"} unless File.exist?(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      return {error: "Permission denied: #{path}"} unless File.readable?(path) && File.writable?(path)
+      size = File.size(path)
+      max_size = Anima::Settings.max_file_size
+      if size > max_size
+        {error: "File is #{size} bytes (#{size / 1_048_576} MB). " \
+                "Max editable size is #{max_size / 1_048_576} MB. Use bash tool with sed instead."}
+      end
+    end
+
+    def edit_file(path, old_text, new_text)
+      raw = File.binread(path)
+      bom = extract_bom(raw)
+      content = raw[bom.length..].force_encoding("UTF-8")
+      had_crlf = content.include?("\r\n")
+      normalized = had_crlf ? content.gsub("\r\n", "\n") : content
+
+      match = find_unique_match(normalized, old_text, path)
+      return match if match.is_a?(Hash)
+
+      position, matched_text, fuzzy = match
+      new_content = normalized[0...position] + new_text + normalized[(position + matched_text.length)..]
+
+      if normalized == new_content
+        return {error: "old_text and new_text are identical. No changes made to #{path}."}
+      end
+
+      output = had_crlf ? new_content.gsub("\n", "\r\n") : new_content
+      File.binwrite(path, bom + output.b)
+
+      build_diff(path, normalized, new_content, fuzzy)
+    rescue Errno::EACCES
+      {error: "Permission denied: #{path}"}
+    rescue Errno::ENOSPC
+      {error: "No space left on device: #{path}"}
+    rescue Errno::EROFS
+      {error: "Read-only file system: #{path}"}
+    end
+
+    # @return [String] UTF-8 BOM bytes if present, empty binary string otherwise
+    def extract_bom(raw)
+      bytes = raw.b
+      bytes.start_with?("\xEF\xBB\xBF".b) ? bytes[0, 3] : "".b
+    end
+
+    # Finds exactly one match for old_text in content.
+    # Tries exact match first, then whitespace-normalized fuzzy match.
+    # @return [Array(Integer, String, Boolean)] position, matched text, fuzzy flag
+    # @return [Hash] error hash if zero or multiple matches found
+    def find_unique_match(content, old_text, path)
+      exact = find_all_positions(content, old_text)
+      return [exact[0], old_text, false] if exact.one?
+      return ambiguity_error(exact, content, path) if exact.length > 1
+
+      fuzzy = find_fuzzy_matches(content, old_text)
+      return [fuzzy[0][0], fuzzy[0][1], true] if fuzzy.one?
+      return ambiguity_error(fuzzy.map(&:first), content, path, fuzzy: true) if fuzzy.length > 1
+
+      {error: "Could not find old_text in #{path}. " \
+              "Verify the text exists and matches exactly (including whitespace). " \
+              "Use the read tool to check current file contents."}
+    end
+
+    def ambiguity_error(positions, content, path, fuzzy: false)
+      kind = fuzzy ? "fuzzy matches" : "matches"
+      line_numbers = positions.map { |pos| line_number_at(content, pos) }
+      {error: "Found #{positions.length} #{kind} for old_text in #{path}. " \
+              "Provide more surrounding context to uniquely identify the location. " \
+              "Matches at lines: #{line_numbers.join(", ")}"}
+    end
+
+    def line_number_at(content, position)
+      content[0...position].count("\n") + 1
+    end
+
+    def find_all_positions(content, text)
+      positions = []
+      offset = 0
+      while (pos = content.index(text, offset))
+        positions << pos
+        offset = pos + 1
+      end
+      positions
+    end
+
+    # Finds old_text in content using whitespace-normalized line comparison.
+    # @return [Array<Array(Integer, String)>] array of [position, matched_text] pairs
+    def find_fuzzy_matches(content, old_text)
+      content_lines = content.split("\n", -1)
+      search_lines = old_text.split("\n", -1)
+      search_lines.pop if search_lines.last&.empty? && old_text.end_with?("\n")
+      trailing_newline = old_text.end_with?("\n")
+
+      normalized_search = search_lines.map { |line| collapse_whitespace(line) }
+      return [] if normalized_search.all?(&:empty?)
+
+      window_size = search_lines.length
+      matches = []
+      (0..content_lines.length - window_size).each do |start_idx|
+        window = content_lines[start_idx, window_size]
+        next unless window.map { |line| collapse_whitespace(line) } == normalized_search
+
+        pos = start_idx.zero? ? 0 : content_lines[0...start_idx].sum { |line| line.length + 1 }
+        matched = window.join("\n")
+        matched += "\n" if trailing_newline
+        matches << [pos, matched]
+      end
+
+      matches
+    end
+
+    def collapse_whitespace(text)
+      text.gsub(/[[:blank:]]+/, " ").strip
+    end
+
+    # Generates a unified diff between old and new content with 3 lines of context.
+    DIFF_CONTEXT = 3
+
+    def build_diff(path, old_content, new_content, fuzzy)
+      before = old_content.lines(chomp: true)
+      after = new_content.lines(chomp: true)
+
+      first = 0
+      first += 1 while first < before.length && first < after.length && before[first] == after[first]
+
+      old_end = before.length - 1
+      new_end = after.length - 1
+      while old_end > first && new_end > first && before[old_end] == after[new_end]
+        old_end -= 1
+        new_end -= 1
+      end
+
+      ctx_start = [first - DIFF_CONTEXT, 0].max
+      old_ctx_end = [old_end + DIFF_CONTEXT, before.length - 1].min
+      new_ctx_end = [new_end + DIFF_CONTEXT, after.length - 1].min
+
+      hunk = []
+      hunk << "--- #{path}"
+      hunk << "+++ #{path}"
+      hunk << "@@ -#{ctx_start + 1},#{old_ctx_end - ctx_start + 1} +#{ctx_start + 1},#{new_ctx_end - ctx_start + 1} @@"
+      (ctx_start...first).each { |idx| hunk << " #{before[idx]}" }
+      (first..old_end).each { |idx| hunk << "-#{before[idx]}" }
+      (first..new_end).each { |idx| hunk << "+#{after[idx]}" }
+      ((old_end + 1)..old_ctx_end).each { |idx| hunk << " #{before[idx]}" }
+
+      diff = hunk.join("\n")
+      fuzzy ? "(fuzzy match — whitespace differences were ignored)\n#{diff}" : diff
+    end
+  end
+end

data/lib/tools/mcp_tool.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Tools
+  # Wraps a single MCP server tool for use with {Tools::Registry}.
+  # Registered as an instance (not a class) — the Registry calls
+  # +#execute+ directly without instantiation, since MCP tools
+  # carry their own client reference and are effectively stateless
+  # from the LLM's perspective.
+  #
+  # Implements the same duck-typed interface as {Tools::Base} subclasses:
+  # - +#tool_name+ — unique identifier
+  # - +#description+ — human-readable description
+  # - +#input_schema+ — JSON Schema for parameters
+  # - +#schema+ — Anthropic API tool definition
+  # - +#execute(input)+ — run the tool
+  #
+  # Tool names are namespaced as `<server_name>__<tool_name>` to prevent
+  # collisions between servers and with built-in tools.
+  #
+  # @example
+  #   wrapper = Tools::McpTool.new(
+  #     server_name: "mythonix",
+  #     mcp_client: client,
+  #     mcp_tool: client.tools.first
+  #   )
+  #   wrapper.tool_name  # => "mythonix__create_image"
+  #   wrapper.execute({"prompt" => "a red dragon"})
+  class McpTool
+    # Separator between server name and tool name in namespaced identifiers.
+    NAMESPACE_SEPARATOR = "__"
+
+    # @return [String] namespaced tool identifier (<server>__<tool>)
+    attr_reader :tool_name
+
+    # @param server_name [String] MCP server name from config
+    # @param mcp_client [MCP::Client] the client instance for this server
+    # @param mcp_tool [MCP::Client::Tool] tool metadata from the server
+    def initialize(server_name:, mcp_client:, mcp_tool:)
+      @tool_name = "#{server_name}#{NAMESPACE_SEPARATOR}#{mcp_tool.name}"
+      @mcp_client = mcp_client
+      @mcp_tool = mcp_tool
+    end
+
+    # @return [String] tool description from the MCP server
+    def description
+      @mcp_tool.description
+    end
+
+    # @return [Hash] JSON Schema for tool input parameters
+    def input_schema
+      @mcp_tool.input_schema
+    end
+
+    # Builds the schema hash expected by the Anthropic tools API.
+    # @return [Hash] with :name, :description, and :input_schema keys
+    def schema
+      {name: tool_name, description: description, input_schema: input_schema}
+    end
+
+    # Calls the MCP server tool and normalizes the response.
+    #
+    # @param input [Hash] tool input parameters from the LLM
+    # @return [String] normalized tool output
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      response = @mcp_client.call_tool(tool: @mcp_tool, arguments: input)
+      normalize_response(response)
+    rescue MCP::Client::RequestHandlerError => error
+      {error: "#{tool_name}: #{error.message}"}
+    end
+
+    private
+
+    # Extracts content from an MCP tool response (JSON-RPC envelope).
+    # Checks the `isError` flag and routes accordingly.
+    #
+    # @param response [Hash] full JSON-RPC response from MCP client
+    # @return [String] concatenated text content
+    # @return [Hash] with :error key if the response indicates an error
+    def normalize_response(response)
+      result = response["result"] || response
+      error = result["isError"]
+
+      text = extract_text(result)
+      error ? {error: "#{tool_name}: #{text}"} : text
+    end
+
+    # Extracts human-readable text from MCP content blocks.
+    # MCP responses contain an array of typed content blocks.
+    #
+    # @param result [Hash] MCP result containing "content" array
+    # @return [String] concatenated text from all content blocks
+    def extract_text(result)
+      content = result["content"]
+
+      return result.to_json unless content
+
+      case content
+      when Array
+        content.filter_map { |block|
+          case block["type"]
+          when "text" then block["text"]
+          when "image" then "[image: #{block["mimeType"]}]"
+          else block.to_json
+          end
+        }.join("\n")
+      when String
+        content
+      else
+        content.to_json
+      end
+    end
+  end
+end

data/lib/tools/read.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Tools
+  # Reads file contents with smart truncation and offset/limit paging.
+  # Returns plain text without line numbers, normalized to LF line endings.
+  #
+  # Truncation limits: `Anima::Settings.max_read_lines` lines or `Anima::Settings.max_read_bytes` bytes, whichever
+  # hits first. When truncated, appends a continuation hint with the next
+  # offset value so the agent can page through large files.
+  #
+  # @example Basic read
+  #   tool.execute("path" => "config/routes.rb")
+  #   # => "Rails.application.routes.draw do\n  ..."
+  #
+  # @example Paging through a large file
+  #   tool.execute("path" => "large.log", "offset" => 2001, "limit" => 500)
+  #   # => "line 2001 content\n..."
+  class Read < Base
+    def self.tool_name = "read"
+
+    def self.description = "Read file contents. Returns plain text with smart truncation. Use offset/limit to page through large files."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
+          offset: {type: "integer", description: "1-indexed line number to start from (default: 1)"},
+          limit: {type: "integer", description: "Maximum lines to read (subject to line and byte caps from config)"}
+        },
+        required: ["path"]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] file contents (possibly truncated with continuation hint)
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, offset, limit = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+
+      path = resolve_path(path)
+
+      error = validate_file(path)
+      return error if error
+
+      read_file(path, offset, limit)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      offset = [input["offset"].to_i, 1].max
+      raw_limit = input["limit"]
+      limit = raw_limit ? [raw_limit.to_i, 1].max : Anima::Settings.max_read_lines
+      [path, offset, limit]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_file(path)
+      return {error: "File not found: #{path}"} unless File.exist?(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      {error: "Permission denied: #{path}"} unless File.readable?(path)
+    end
+
+    # Reads the file, normalizes line endings, and applies truncation limits.
+    # Two limits are enforced as first-hit-wins: line count and byte size.
+    # A single line exceeding `Anima::Settings.max_read_bytes` is rejected outright (likely minified).
+    # Files larger than max_file_size are rejected to avoid memory exhaustion.
+
+    def read_file(path, offset, limit)
+      file_size = File.size(path)
+      max_size = Anima::Settings.max_file_size
+      if file_size > max_size
+        return {error: "File is #{file_size} bytes (#{file_size / 1_048_576} MB). " \
+                       "Max readable size is #{max_size / 1_048_576} MB. " \
+                       "Use bash tool with: head -n #{offset + limit} #{path} | tail -n +#{offset}"}
+      end
+
+      lines = normalize(File.read(path))
+      return "" if lines.empty?
+
+      start_index = offset - 1
+      return "[File has #{lines.size} lines. Offset #{offset} is beyond end of file.]" if start_index >= lines.size
+
+      window = lines[start_index, [limit, Anima::Settings.max_read_lines].min]
+
+      error = check_oversized_lines(window, offset, path)
+      return error if error
+
+      build_output(window, lines.size, offset)
+    end
+
+    def normalize(content)
+      content.gsub("\r\n", "\n").lines
+    end
+
+    def check_oversized_lines(window, offset, path)
+      max_bytes = Anima::Settings.max_read_bytes
+      index = window.index { |line| line.bytesize > max_bytes }
+      return unless index
+
+      line_num = offset + index
+      {error: "Line #{line_num} exceeds #{max_bytes} bytes (likely minified). " \
+              "Use bash tool with: sed -n '#{line_num}p' #{path}"}
+    end
+
+    def build_output(window, total_lines, offset)
+      text, count = accumulate_lines(window)
+      end_line = offset + count - 1
+
+      if end_line < total_lines
+        text + "\n\n[Showing lines #{offset}-#{end_line} of #{total_lines}. Use offset=#{end_line + 1} to continue.]"
+      else
+        text
+      end
+    end
+
+    # Accumulates lines until the byte cap would be exceeded.
+    # @return [Array(String, Integer)] accumulated text and number of lines included
+    def accumulate_lines(window)
+      max_bytes = Anima::Settings.max_read_bytes
+      output = +""
+      bytes = 0
+      count = 0
+
+      window.each_with_index do |line, index|
+        break if bytes + line.bytesize > max_bytes && index > 0
+
+        output << line
+        bytes += line.bytesize
+        count += 1
+      end
+
+      [output, count]
+    end
+  end
+end

data/lib/tools/registry.rb

@@ -4,16 +4,17 @@ module Tools
   class UnknownToolError < StandardError; end
 
   # Manages tool registration, schema export, and dispatch.
-  # Tools are registered by class and looked up by name at execution time.
-  # An optional context hash is passed to each tool's constructor, allowing
-  # shared dependencies (e.g. a {ShellSession}) to reach tools that need them.
+  # Accepts both tool classes (e.g. {Tools::Base} subclasses) and tool
+  # instances (e.g. {Tools::McpTool}) via duck typing. Classes are
+  # instantiated with the registry's context on each execution; instances
+  # are called directly since they carry their own state.
   #
   # @example
   #   registry = Tools::Registry.new(context: {shell_session: my_shell})
   #   registry.register(Tools::Bash)
   #   registry.execute("bash", {"command" => "ls"})
   class Registry
-    # @return [Hash{String => Class}] registered tool classes keyed by name
+    # @return [Hash{String => Class, Object}] registered tools keyed by name
     attr_reader :tools
 
     # @param context [Hash] keyword arguments forwarded to every tool constructor
@@ -22,11 +23,11 @@ module Tools
       @context = context
     end
 
-    # Register a tool class. The class must respond to .tool_name.
-    # @param tool_class [Class<Tools::Base>] the tool class to register
+    # Register a tool class or instance. Must respond to +tool_name+ and +schema+.
+    # @param tool [Class<Tools::Base>, #tool_name] tool class or duck-typed instance
     # @return [void]
-    def register(tool_class)
-      @tools[tool_class.tool_name] = tool_class
+    def register(tool)
+      @tools[tool.tool_name] = tool
     end
 
     # @return [Array<Hash>] schema array for the Anthropic tools API parameter
@@ -34,16 +35,17 @@ module Tools
       @tools.values.map(&:schema)
     end
 
-    # Instantiate and execute a tool by name. The registry's context is
-    # forwarded to the tool constructor as keyword arguments.
+    # 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
     # @return [String, Hash] tool execution result
     # @raise [UnknownToolError] if no tool is registered with the given name
     def execute(name, input)
-      tool_class = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
-      tool_class.new(**@context).execute(input)
+      tool = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
+      instance = tool.is_a?(Class) ? tool.new(**@context) : tool
+      instance.execute(input)
     end
 
     # @param name [String] tool name to check