anima-core 0.3.0 → 1.0.1

data/lib/mcp/secrets.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Mcp
+  # CRUD operations for MCP server secrets stored in Rails encrypted credentials.
+  # Secrets live under the +mcp+ namespace in the credentials file:
+  #
+  #   mcp:
+  #     linear_api_key: "sk-xxx"
+  #     mythonix_api_key: "Bearer tok-yyy"
+  #
+  # Referenced in mcp.toml via +${credential:key_name}+ syntax, resolved at
+  # runtime by {Mcp::Config#interpolate_credentials}.
+  #
+  # @example Storing a secret
+  #   Mcp::Secrets.set("linear_api_key", "sk-xxx")
+  #
+  # @example Retrieving a secret
+  #   Mcp::Secrets.get("linear_api_key") #=> "sk-xxx"
+  class Secrets
+    NAMESPACE = "mcp"
+
+    # Keys must be interpolatable via ${credential:key_name} in mcp.toml.
+    VALID_KEY_PATTERN = /\A\w+\z/
+
+    class << self
+      # Stores a secret in encrypted credentials.
+      #
+      # @param key [String] secret identifier (e.g. "linear_api_key")
+      # @param value [String] secret value
+      # @return [void]
+      # @raise [ArgumentError] if key contains characters that cannot be
+      #   referenced via +${credential:key_name}+ syntax
+      def set(key, value)
+        validate_key!(key)
+        CredentialStore.write(NAMESPACE, key => value)
+      end
+
+      # Retrieves a secret from encrypted credentials.
+      #
+      # @param key [String] secret identifier
+      # @return [String, nil] secret value or nil if not found
+      def get(key)
+        CredentialStore.read(NAMESPACE, key)
+      end
+
+      # Lists all stored MCP secret keys (not values).
+      #
+      # @return [Array<String>] secret names
+      def list
+        CredentialStore.list(NAMESPACE)
+      end
+
+      # Removes a secret from encrypted credentials.
+      #
+      # @param key [String] secret identifier to remove
+      # @return [void]
+      def remove(key)
+        CredentialStore.remove(NAMESPACE, key)
+      end
+
+      private
+
+      # @raise [ArgumentError] if key is not interpolatable
+      def validate_key!(key)
+        return if key.match?(VALID_KEY_PATTERN)
+
+        raise ArgumentError,
+          "invalid secret key '#{key}' — use only letters, numbers, and underscores " \
+          "(must match ${credential:key_name} syntax)"
+      end
+    end
+  end
+end

data/lib/mcp/stdio_transport.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+require "open3"
+require "timeout"
+
+module Mcp
+  # Client-side stdio transport for MCP servers that communicate via
+  # JSON-RPC over stdin/stdout. Conforms to the MCP SDK transport contract
+  # (+send_request(request:)+ → Hash) so it plugs into {MCP::Client}
+  # identically to the built-in HTTP transport.
+  #
+  # Spawns the server process lazily on first request. If the process
+  # crashes, the next request automatically respawns it. Thread-safe
+  # via a mutex around the entire request/response cycle.
+  #
+  # @example
+  #   transport = Mcp::StdioTransport.new(command: "linear-toon-mcp")
+  #   client = MCP::Client.new(transport: transport)
+  #   client.tools  # spawns process, sends tools/list, returns tools
+  #
+  # @see MCP::Client::HTTP the built-in HTTP transport this mirrors
+  class StdioTransport
+    # Seconds to wait for graceful SIGTERM shutdown before escalating to SIGKILL.
+    GRACEFUL_SHUTDOWN_TIMEOUT = 2
+
+    # @param command [String] executable to spawn (resolved via $PATH)
+    # @param args [Array<String>] command-line arguments for the server process
+    # @param env [Hash<String, String>] environment variables merged into
+    #   the child process's inherited environment
+    def initialize(command:, args: [], env: {})
+      @command = command
+      @args = args
+      @env = env
+      @mutex = Mutex.new
+      @stdin = nil
+      @stdout = nil
+      @wait_thread = nil
+    end
+
+    # Sends a JSON-RPC request and returns the parsed response.
+    # Spawns the server process on first call. If the process died
+    # since the last call, respawns automatically.
+    #
+    # @param request [Hash] complete JSON-RPC request object with
+    #   +:jsonrpc+, +:id+, +:method+, and optional +:params+ keys
+    # @return [Hash] parsed JSON-RPC response (string keys)
+    # @raise [MCP::Client::RequestHandlerError] on transport-level errors
+    #   (process crash, invalid JSON, timeout, command not found)
+    def send_request(request:)
+      @mutex.synchronize do
+        perform_request(request)
+      end
+    end
+
+    # Terminates the server process and releases resources.
+    # Safe to call multiple times — subsequent calls are no-ops.
+    def shutdown
+      @mutex.synchronize { stop_process }
+      self.class.unregister(self)
+    end
+
+    # --- Class-level instance tracking for at_exit cleanup ---
+
+    @instances = []
+    @instances_mutex = Mutex.new
+
+    class << self
+      # @api private
+      def register(instance)
+        @instances_mutex.synchronize { @instances << instance }
+      end
+
+      # @api private
+      def unregister(instance)
+        @instances_mutex.synchronize { @instances.delete(instance) }
+      end
+
+      # Shuts down all tracked instances. Called automatically via +at_exit+.
+      def cleanup_all
+        @instances_mutex.synchronize do
+          @instances.each { |instance| instance.send(:stop_process) }
+          @instances.clear
+        end
+      end
+    end
+
+    at_exit { Mcp::StdioTransport.cleanup_all }
+
+    private
+
+    def perform_request(request)
+      ensure_running
+      write_request(request)
+      read_response(request)
+    rescue Errno::EPIPE, IOError => error
+      stop_process
+      raise_transport_error("Server process crashed: #{error.message}", request, error)
+    rescue JSON::ParserError => error
+      stop_process
+      raise_transport_error("Invalid JSON from server: #{error.message}", request, error)
+    rescue Timeout::Error
+      stop_process
+      raise_transport_error("No response within #{Anima::Settings.mcp_response_timeout}s", request)
+    end
+
+    def ensure_running
+      return if alive?
+
+      spawn_process
+    end
+
+    def alive?
+      @wait_thread&.alive? || false
+    end
+
+    def spawn_process
+      @stdin, @stdout, @wait_thread = Open3.popen2(@env, @command, *@args)
+      @stdin.set_encoding("UTF-8")
+      @stdout.set_encoding("UTF-8")
+      self.class.register(self)
+    rescue Errno::ENOENT => error
+      raise_transport_error("Command not found: #{@command}", {}, error)
+    end
+
+    def write_request(request)
+      @stdin.puts(JSON.generate(request))
+      @stdin.flush
+    end
+
+    # Reads lines from stdout until a JSON-RPC response matching the
+    # request ID is found. Notifications (messages without a matching id)
+    # are silently skipped — the MCP protocol allows servers to emit
+    # them at any time.
+    def read_response(request)
+      request_id = (request[:id] || request["id"]).to_s
+
+      Timeout.timeout(Anima::Settings.mcp_response_timeout) do
+        loop do
+          line = @stdout.gets
+          raise IOError, "Server process closed stdout" if line.nil?
+
+          parsed = JSON.parse(line)
+          unless parsed.is_a?(Hash)
+            raise JSON::ParserError, "Expected JSON object, got #{parsed.class}"
+          end
+
+          return parsed if parsed["id"].to_s == request_id
+        end
+      end
+    end
+
+    def stop_process
+      close_pipes
+      terminate_process
+      @stdin = nil
+      @stdout = nil
+      @wait_thread = nil
+    end
+
+    def close_pipes
+      @stdin&.close rescue IOError # rubocop:disable Style/RescueModifier
+      @stdout&.close rescue IOError # rubocop:disable Style/RescueModifier
+    end
+
+    # Sends SIGTERM and waits up to 2 seconds for the process to exit.
+    # Falls back to SIGKILL if the process does not terminate in time.
+    def terminate_process
+      return unless @wait_thread
+
+      pid = @wait_thread.pid
+      begin
+        Process.kill("TERM", pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        return
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + GRACEFUL_SHUTDOWN_TIMEOUT
+      loop do
+        _, status = Process.wait2(pid, Process::WNOHANG)
+        break if status
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          Process.kill("KILL", pid) rescue Errno::ESRCH # rubocop:disable Style/RescueModifier
+          Process.wait(pid) rescue Errno::ECHILD # rubocop:disable Style/RescueModifier
+          break
+        end
+        sleep 0.05
+      end
+    rescue Errno::ECHILD, Errno::ESRCH
+      # Already reaped
+    end
+
+    def raise_transport_error(message, request, original_error = nil)
+      method = request[:method] || request["method"]
+      params = request[:params] || request["params"]
+
+      raise MCP::Client::RequestHandlerError.new(
+        message,
+        {method: method, params: params},
+        error_type: :internal_error,
+        original_error: original_error
+      )
+    end
+  end
+end

data/lib/providers/anthropic.rb

@@ -7,13 +7,11 @@ module Providers
     include HTTParty
 
     base_uri "https://api.anthropic.com"
-    default_timeout 30
 
     TOKEN_PREFIX = "sk-ant-oat01-"
     TOKEN_MIN_LENGTH = 80
     API_VERSION = "2023-06-01"
     REQUIRED_BETA = "oauth-2025-04-20"
-    VALIDATION_MODEL = "claude-sonnet-4-20250514"
 
     class Error < StandardError; end
     class AuthenticationError < Error; end
@@ -26,7 +24,7 @@ module Providers
 
     class << self
       def fetch_token
-        token = Rails.application.credentials.dig(:anthropic, :subscription_token)
+        token = CredentialStore.read("anthropic", "subscription_token")
         raise AuthenticationError, <<~MSG.strip if token.blank?
           No Anthropic subscription token found in credentials.
           Use the TUI token setup (Ctrl+a → a) to configure your token.
@@ -66,7 +64,8 @@ module Providers
       response = self.class.post(
         "/v1/messages",
         body: body.to_json,
-        headers: request_headers
+        headers: request_headers,
+        timeout: Anima::Settings.api_timeout
       )
 
       handle_response(response)
@@ -88,7 +87,8 @@ module Providers
       response = self.class.post(
         "/v1/messages/count_tokens",
         body: body.to_json,
-        headers: request_headers
+        headers: request_headers,
+        timeout: Anima::Settings.api_timeout
       )
 
       result = handle_response(response)
@@ -101,11 +101,12 @@ module Providers
       response = self.class.post(
         "/v1/messages",
         body: {
-          model: VALIDATION_MODEL,
+          model: Anima::Settings.model,
           messages: [{role: "user", content: "Hi"}],
           max_tokens: 1
         }.to_json,
-        headers: request_headers
+        headers: request_headers,
+        timeout: Anima::Settings.api_timeout
       )
 
       case response.code

data/lib/shell_session.rb

@@ -16,9 +16,6 @@ require "timeout"
 #   # => {stdout: "/tmp", stderr: "", exit_code: 0}
 #   session.finalize
 class ShellSession
-  COMMAND_TIMEOUT = 30
-  MAX_OUTPUT_BYTES = 100_000
-
   # @return [String, nil] current working directory of the shell process
   attr_reader :pwd
 
@@ -140,12 +137,14 @@ class ShellSession
     @stderr_buffer = []
     @stderr_bytes = 0
     @stderr_truncated = false
+    @max_output_bytes = Anima::Settings.max_output_bytes
     @stderr_thread = Thread.new do
+      max_bytes = @max_output_bytes
       File.open(@fifo_path, "r") do |fifo|
         while (line = fifo.gets)
           cleaned = line.chomp.delete("\r")
           @stderr_mutex.synchronize do
-            if @stderr_bytes < MAX_OUTPUT_BYTES
+            if @stderr_bytes < max_bytes
               @stderr_buffer << cleaned
               @stderr_bytes += cleaned.bytesize
             else
@@ -172,8 +171,9 @@ class ShellSession
   def execute_in_pty(command)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
+    timeout = Anima::Settings.command_timeout
 
-    Timeout.timeout(COMMAND_TIMEOUT) do
+    Timeout.timeout(timeout) do
       # All on one line: run command, capture exit code, ensure newline
       # before marker so output without trailing newline doesn't merge.
       @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
@@ -190,7 +190,7 @@ class ShellSession
     end
   rescue Timeout::Error
     recover_from_timeout
-    {error: "Command timed out after #{COMMAND_TIMEOUT} seconds"}
+    {error: "Command timed out after #{timeout} seconds"}
   rescue Errno::EIO
     @alive = false
     {error: "Shell session terminated unexpectedly"}
@@ -260,7 +260,7 @@ class ShellSession
       @stderr_buffer.clear
       @stderr_bytes = 0
       @stderr_truncated = false
-      truncated ? result + "\n\n[Truncated: output exceeded #{MAX_OUTPUT_BYTES} bytes]" : result
+      truncated ? result + "\n\n[Truncated: output exceeded #{@max_output_bytes} bytes]" : result
     end
   end
 
@@ -274,12 +274,13 @@ class ShellSession
   end
 
   def truncate(output)
-    return output if output.bytesize <= MAX_OUTPUT_BYTES
+    max_bytes = @max_output_bytes
+    return output if output.bytesize <= max_bytes
 
-    output.byteslice(0, MAX_OUTPUT_BYTES)
+    output.byteslice(0, max_bytes)
       .force_encoding("UTF-8")
       .scrub +
-      "\n\n[Truncated: output exceeded #{MAX_OUTPUT_BYTES} bytes]"
+      "\n\n[Truncated: output exceeded #{max_bytes} bytes]"
   end
 
   def shutdown

data/lib/skills/definition.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Skills
+  class InvalidDefinitionError < StandardError; end
+
+  # A domain knowledge skill parsed from a Markdown definition file.
+  # YAML frontmatter holds metadata; the Markdown body is the knowledge
+  # content injected into the main agent's system prompt when active.
+  #
+  # Skills are passive knowledge — they describe WHAT you know, not
+  # WHAT to do. The analytical brain activates/deactivates them based
+  # on conversation context.
+  #
+  # @example Skill file format
+  #   ---
+  #   name: gh-issue
+  #   description: "GitHub issue writing with WHAT/WHY/HOW framework."
+  #   ---
+  #
+  #   # GitHub Issue Writing
+  #   Write issues with clear rationale...
+  class Definition
+    # @return [String] unique skill identifier used in activate_skill(name: "...")
+    attr_reader :name
+
+    # @return [String] description shown to the analytical brain for relevance matching
+    attr_reader :description
+
+    # @return [String] knowledge content (Markdown body) injected into system prompt
+    attr_reader :content
+
+    # @return [String] file path this definition was loaded from
+    attr_reader :source_path
+
+    def initialize(name:, description:, content:, source_path: "")
+      @name = name
+      @description = description
+      @content = content
+      @source_path = source_path
+    end
+
+    # Parses a Markdown file with YAML frontmatter into a Definition.
+    #
+    # @param path [String, Pathname] path to the .md file
+    # @return [Definition]
+    # @raise [InvalidDefinitionError] if required fields are missing or frontmatter is malformed
+    def self.from_file(path)
+      raw = File.read(path)
+      frontmatter, body = parse_frontmatter(raw)
+
+      validate_required_fields!(frontmatter, path)
+
+      new(
+        name: frontmatter["name"].to_s.strip,
+        description: frontmatter["description"].to_s.strip,
+        content: body.strip,
+        source_path: path.to_s
+      )
+    end
+
+    # @param raw [String] raw file content with YAML frontmatter
+    # @return [Array(Hash, String)] parsed frontmatter and body text
+    # @raise [InvalidDefinitionError] if frontmatter is missing or malformed
+    def self.parse_frontmatter(raw)
+      # Opening "---" must be followed by a newline (not just whitespace).
+      # Non-greedy (.*?\n) captures YAML lines up to the closing "---".
+      # Closing "---" may optionally be followed by a newline before the body.
+      # The /m flag lets (.*) in the body capture across newlines.
+      match = raw.match(/\A---\s*\n(.*?\n)---\s*\n?(.*)\z/m)
+      raise InvalidDefinitionError, "Missing YAML frontmatter" unless match
+
+      frontmatter = YAML.safe_load(match[1])
+      raise InvalidDefinitionError, "Frontmatter is not a valid YAML mapping" unless frontmatter.is_a?(Hash)
+
+      [frontmatter, match[2]]
+    end
+
+    NAME_FORMAT = /\A[a-z0-9][a-z0-9_-]*\z/
+
+    def self.validate_required_fields!(frontmatter, path)
+      %w[name description].each do |field|
+        value = frontmatter[field].to_s.strip
+        raise InvalidDefinitionError, "Missing required field '#{field}' in #{path}" if value.empty?
+      end
+
+      name = frontmatter["name"].to_s.strip
+      unless name.match?(NAME_FORMAT)
+        raise InvalidDefinitionError,
+          "Invalid skill name '#{name}' in #{path} — must be lowercase alphanumeric with hyphens/underscores"
+      end
+    end
+
+    private_class_method :parse_frontmatter, :validate_required_fields!
+  end
+end

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

@@ -16,8 +16,6 @@ module Tools
   #                "new_text" => "def greet\n  'hello'\nend")
   #   # => "--- app.rb\n+++ app.rb\n@@ -1,3 +1,3 @@\n ..."
   class Edit < Base
-    MAX_FILE_SIZE = 10 * 1024 * 1024 # 10 MB
-
     def self.tool_name = "edit"
 
     def self.description = "Replace exact text in a file. old_text must match exactly one location; " \
@@ -79,9 +77,10 @@ module Tools
       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)
-      if size > MAX_FILE_SIZE
+      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_FILE_SIZE / 1_048_576} MB. Use bash tool with sed instead."}
+                "Max editable size is #{max_size / 1_048_576} MB. Use bash tool with sed instead."}
       end
     end