anima-core 0.2.1 → 1.0.0

data/lib/mcp/health_check.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Mcp
+  # Probes an MCP server to verify connectivity and count available tools.
+  # Used by the CLI +list+ command to show server health status.
+  #
+  # @example
+  #   result = Mcp::HealthCheck.call(name: "sentry", url: "https://mcp.sentry.dev/mcp", headers: {})
+  #   result #=> { status: :connected, tools: 5 }
+  class HealthCheck
+    # Health check probe timeout in seconds. Balances responsiveness
+    # (CLI shouldn't hang) vs. giving slow servers a fair chance.
+    TIMEOUT = 5
+
+    # @param server [Hash] interpolated server config with symbol keys
+    #   (+:name+, +:url+/+:command+, and +:transport+)
+    # @return [Hash] +{ status: :connected, tools: Integer }+ or
+    #   +{ status: :failed, error: String }+
+    def self.call(server)
+      new(server).call
+    end
+
+    def initialize(server)
+      @server = server
+      @stdio_transport = nil
+    end
+
+    def call
+      Timeout.timeout(TIMEOUT) { check }
+    rescue Timeout::Error
+      {status: :failed, error: "connection timeout"}
+    rescue KeyError => key_error
+      {status: :failed, error: "missing credential #{key_error.message}"}
+    rescue => error
+      {status: :failed, error: error.message}
+    end
+
+    private
+
+    def check
+      transport = @server[:transport]
+
+      case transport
+      when "http" then check_http
+      when "stdio" then check_stdio
+      else {status: :failed, error: "unknown transport '#{transport}'"}
+      end
+    end
+
+    def check_http
+      require "mcp"
+
+      transport = MCP::Client::HTTP.new(url: @server[:url], headers: @server[:headers] || {})
+      client = MCP::Client.new(transport: transport)
+      tool_count = client.tools.size
+      {status: :connected, tools: tool_count}
+    end
+
+    def check_stdio
+      require "mcp"
+      require_relative "stdio_transport"
+
+      @stdio_transport = StdioTransport.new(
+        command: @server[:command],
+        args: @server[:args] || [],
+        env: @server[:env] || {}
+      )
+      client = MCP::Client.new(transport: @stdio_transport)
+      tool_count = client.tools.size
+      {status: :connected, tools: tool_count}
+    ensure
+      @stdio_transport&.shutdown
+    end
+  end
+end

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
@@ -25,21 +23,11 @@ module Providers
     class ServerError < TransientError; end
 
     class << self
-      def validate!
-        token = fetch_token
-        validate_token_format!(token)
-        validate_token_api!(token)
-        true
-      end
-
       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.
-          Run: bin/rails credentials:edit
-          Add:
-            anthropic:
-              subscription_token: sk-ant-oat01-YOUR_TOKEN_HERE
+          Use the TUI token setup (Ctrl+a → a) to configure your token.
         MSG
         token
       end
@@ -76,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)
@@ -98,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)
@@ -111,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
@@ -123,7 +114,7 @@ module Providers
         true
       when 401
         raise AuthenticationError,
-          "Token rejected by Anthropic API (401). Re-run `claude setup-token` and update credentials."
+          "Token rejected by Anthropic API (401). Re-run `claude setup-token` and use the TUI token setup (Ctrl+a → a)."
       when 403
         raise AuthenticationError,
           "Token not authorized for API access (403). This credential may be restricted to Claude Code only."
@@ -151,7 +142,7 @@ module Providers
         raise Error, "Bad request: #{error_message(response)}"
       when 401
         raise AuthenticationError,
-          "Authentication failed (401): #{error_message(response)}. Re-run `claude setup-token` and update credentials."
+          "Authentication failed (401): #{error_message(response)}. Re-run `claude setup-token` and use the TUI token setup (Ctrl+a → a)."
       when 403
         raise AuthenticationError,
           "Forbidden (403): #{error_message(response)}"

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