anima-core 0.0.1 → 0.1.0

data/lib/events/tool_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  class ToolResponse < Base
+    TYPE = "tool_response"
+
+    attr_reader :tool_name, :success, :tool_use_id
+
+    # @param content [String] tool execution output
+    # @param tool_name [String] registered tool name
+    # @param success [Boolean] whether the tool executed successfully
+    # @param tool_use_id [String, nil] Anthropic-assigned ID for correlating call/result
+    # @param session_id [String, nil] optional session identifier
+    def initialize(content:, tool_name:, success: true, tool_use_id: nil, session_id: nil)
+      super(content: content, session_id: session_id)
+      @tool_name = tool_name
+      @success = success
+      @tool_use_id = tool_use_id
+    end
+
+    def type
+      TYPE
+    end
+
+    def success?
+      @success
+    end
+
+    def to_h
+      super.merge(tool_name: tool_name, success: success, tool_use_id: tool_use_id)
+    end
+  end
+end

data/lib/events/user_message.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Events
+  class UserMessage < Base
+    TYPE = "user_message"
+
+    def type
+      TYPE
+    end
+  end
+end

data/lib/llm/client.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module LLM
+  # Convenience layer over {Providers::Anthropic} for sending messages
+  # and handling tool execution loops. Supports both simple text chat
+  # and multi-turn tool calling via the Anthropic tool use protocol.
+  #
+  # @example Simple chat (no tools)
+  #   client = LLM::Client.new
+  #   client.chat([{role: "user", content: "Say hello"}])
+  #   # => "Hello! How can I help you today?"
+  #
+  # @example Chat with tools
+  #   registry = Tools::Registry.new
+  #   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
+
+    # @return [String] the model identifier used for API calls
+    attr_reader :model
+
+    # @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 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)
+      @provider = build_provider(provider)
+      @model = model
+      @max_tokens = max_tokens
+    end
+
+    # Send messages to the LLM and return the assistant's text response.
+    #
+    # @param messages [Array<Hash>] conversation messages, each with +:role+ and +:content+
+    # @param options [Hash] additional API parameters (e.g. +system:+, +temperature:+)
+    # @return [String] the assistant's response text
+    # @raise [Providers::Anthropic::Error] on API errors
+    # @raise [Providers::Anthropic::AuthenticationError] on auth failures
+    def chat(messages, **options)
+      response = provider.create_message(
+        model: model,
+        messages: messages,
+        max_tokens: max_tokens,
+        **options
+      )
+
+      extract_text(response)
+    end
+
+    # Send messages with tool support. Runs the full tool execution loop:
+    # call LLM, execute any requested tools, feed results back, repeat
+    # until the LLM produces a final text response.
+    #
+    # Emits {Events::ToolCall} and {Events::ToolResponse} events for each
+    # tool interaction so they're persisted and visible in the event stream.
+    #
+    # @param messages [Array<Hash>] conversation messages in Anthropic format
+    # @param registry [Tools::Registry] registered tools to make available
+    # @param session_id [Integer, String] session ID for emitted events
+    # @param options [Hash] additional API parameters (e.g. +system:+)
+    # @return [String] the assistant's final text response
+    # @raise [Providers::Anthropic::Error] on API errors
+    def chat_with_tools(messages, registry:, session_id:, **options)
+      messages = messages.dup
+      rounds = 0
+
+      loop do
+        rounds += 1
+        if rounds > MAX_TOOL_ROUNDS
+          return "[Tool loop exceeded #{MAX_TOOL_ROUNDS} rounds — halting]"
+        end
+
+        response = provider.create_message(
+          model: model,
+          messages: messages,
+          max_tokens: max_tokens,
+          tools: registry.schemas,
+          **options
+        )
+
+        if response["stop_reason"] == "tool_use"
+          tool_results = execute_tools(response, registry, session_id)
+
+          messages += [
+            {role: "assistant", content: response["content"]},
+            {role: "user", content: tool_results}
+          ]
+        else
+          return extract_text(response)
+        end
+      end
+    end
+
+    private
+
+    def build_provider(provider)
+      provider || Providers::Anthropic.new
+    end
+
+    def extract_text(response)
+      content = response["content"] || []
+
+      content
+        .select { |block| block["type"] == "text" }
+        .map { |block| block["text"] }
+        .join
+    end
+
+    def extract_tool_uses(response)
+      content = response["content"] || []
+      content.select { |block| block["type"] == "tool_use" }
+    end
+
+    # Executes all tool_use blocks from a response, emitting events for each.
+    #
+    # @param response [Hash] Anthropic API response with tool_use content blocks
+    # @param registry [Tools::Registry] tool registry for dispatch
+    # @param session_id [Integer, String] session ID for events
+    # @return [Array<Hash>] tool_result content blocks for the next API call
+    def execute_tools(response, registry, session_id)
+      extract_tool_uses(response).map do |tool_use|
+        execute_single_tool(tool_use, registry, session_id)
+      end
+    end
+
+    def execute_single_tool(tool_use, registry, session_id)
+      name = tool_use["name"]
+      id = tool_use["id"]
+      input = tool_use["input"] || {}
+
+      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_content = format_tool_result(result)
+
+      Events::Bus.emit(Events::ToolResponse.new(
+        content: result_content, tool_name: name, tool_use_id: id,
+        success: !result.is_a?(Hash) || !result.key?(:error),
+        session_id: session_id
+      ))
+
+      {type: "tool_result", tool_use_id: id, content: result_content}
+    end
+
+    def format_tool_result(result)
+      result.is_a?(Hash) ? result.to_json : result.to_s
+    end
+  end
+end

data/lib/providers/anthropic.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Providers
+  class Anthropic
+    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
+    class TokenFormatError < Error; 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)
+        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
+        MSG
+        token
+      end
+
+      def validate_token_format!(token)
+        unless token.start_with?(TOKEN_PREFIX)
+          raise TokenFormatError,
+            "Token must start with '#{TOKEN_PREFIX}'. Got: '#{token[0..12]}...'"
+        end
+
+        unless token.length >= TOKEN_MIN_LENGTH
+          raise TokenFormatError,
+            "Token must be at least #{TOKEN_MIN_LENGTH} characters (got #{token.length})"
+        end
+
+        true
+      end
+
+      def validate_token_api!(token)
+        provider = new(token)
+        provider.validate_credentials!
+      end
+    end
+
+    attr_reader :token
+
+    def initialize(token = nil)
+      @token = token || self.class.fetch_token
+    end
+
+    def create_message(model:, messages:, max_tokens:, **options)
+      body = {model: model, messages: messages, max_tokens: max_tokens}.merge(options)
+
+      response = self.class.post(
+        "/v1/messages",
+        body: body.to_json,
+        headers: request_headers
+      )
+
+      handle_response(response)
+    end
+
+    # Count tokens in a message payload without creating a message.
+    # Uses the free Anthropic token counting endpoint.
+    #
+    # @param model [String] Anthropic model identifier
+    # @param messages [Array<Hash>] conversation messages
+    # @param options [Hash] additional parameters (e.g. +system:+, +tools:+)
+    # @return [Integer] estimated input token count
+    # @raise [Error] on API errors
+    def count_tokens(model:, messages:, **options)
+      body = {model: model, messages: messages}.merge(options)
+
+      response = self.class.post(
+        "/v1/messages/count_tokens",
+        body: body.to_json,
+        headers: request_headers
+      )
+
+      result = handle_response(response)
+      result["input_tokens"]
+    end
+
+    def validate_credentials!
+      response = self.class.post(
+        "/v1/messages",
+        body: {
+          model: VALIDATION_MODEL,
+          messages: [{role: "user", content: "Hi"}],
+          max_tokens: 1
+        }.to_json,
+        headers: request_headers
+      )
+
+      case response.code
+      when 200
+        true
+      when 401
+        raise AuthenticationError,
+          "Token rejected by Anthropic API (401). Re-run `claude setup-token` and update credentials."
+      when 403
+        raise AuthenticationError,
+          "Token not authorized for API access (403). This credential may be restricted to Claude Code only."
+      else
+        handle_response(response)
+      end
+    end
+
+    private
+
+    def request_headers
+      {
+        "Authorization" => "Bearer #{token}",
+        "anthropic-version" => API_VERSION,
+        "anthropic-beta" => REQUIRED_BETA,
+        "content-type" => "application/json"
+      }
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200
+        response.parsed_response
+      when 400
+        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."
+      when 403
+        raise AuthenticationError,
+          "Forbidden (403): #{error_message(response)}"
+      when 429
+        raise Error, "Rate limit exceeded: #{error_message(response)}"
+      when 500..599
+        raise Error, "Anthropic server error (#{response.code}): #{response.message}"
+      else
+        raise Error, "Unexpected response (#{response.code}): #{response.message}"
+      end
+    end
+
+    def error_message(response)
+      response.parsed_response&.dig("error", "message") || response.message
+    rescue JSON::ParserError, NoMethodError
+      response.message
+    end
+  end
+end

data/lib/shell_session.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "pty"
+require "securerandom"
+require "timeout"
+
+# Persistent shell session backed by a PTY with FIFO-based stderr separation.
+# Commands share working directory, environment variables, and shell history
+# within a conversation. Multiple tools share the same session.
+#
+# @example
+#   session = ShellSession.new(session_id: 42)
+#   session.run("cd /tmp")
+#   session.run("pwd")
+#   # => {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
+
+  # @param session_id [Integer, String] unique identifier for logging/diagnostics
+  def initialize(session_id:)
+    @session_id = session_id
+    @mutex = Mutex.new
+    @fifo_path = File.join(Dir.tmpdir, "anima-stderr-#{Process.pid}-#{SecureRandom.hex(8)}")
+    @alive = false
+    @pwd = nil
+    self.class.cleanup_orphans
+    start
+    self.class.register(self)
+  end
+
+  # Execute a command in the persistent shell.
+  #
+  # @param command [String] bash command to execute
+  # @return [Hash] with :stdout, :stderr, :exit_code keys on success
+  # @return [Hash] with :error key on failure
+  def run(command)
+    @mutex.synchronize do
+      return {error: "Shell session is not running"} unless @alive
+      execute_in_pty(command)
+    end
+  end
+
+  # Clean up PTY, FIFO, and child process.
+  def finalize
+    @mutex.synchronize { shutdown }
+    self.class.unregister(self)
+  end
+
+  # @return [Boolean] whether the shell process is still running
+  def alive?
+    @mutex.synchronize { @alive }
+  end
+
+  # --- Class-level session tracking for at_exit cleanup ---
+
+  @sessions = []
+  @sessions_mutex = Mutex.new
+
+  class << self
+    # @api private
+    def register(session)
+      @sessions_mutex.synchronize { @sessions << session }
+    end
+
+    # @api private
+    def unregister(session)
+      @sessions_mutex.synchronize { @sessions.delete(session) }
+    end
+
+    # Finalize all live sessions. Called automatically via at_exit.
+    def cleanup_all
+      @sessions_mutex.synchronize do
+        @sessions.each { |session| session.send(:shutdown) }
+        @sessions.clear
+      end
+    end
+
+    # Remove stale FIFO files left by crashed processes.
+    # FIFO naming format: anima-stderr-{pid}-{hex}
+    def cleanup_orphans
+      Dir.glob(File.join(Dir.tmpdir, "anima-stderr-*")).each do |path|
+        match = File.basename(path).match(/\Aanima-stderr-(\d+)-/)
+        next unless match
+
+        pid = match[1].to_i
+        next if pid <= 0
+
+        begin
+          Process.kill(0, pid)
+        rescue Errno::ESRCH
+          begin
+            File.delete(path)
+          rescue SystemCallError
+            # Best-effort cleanup
+          end
+        rescue Errno::EPERM
+          # Process exists but we can't signal it — leave it
+        end
+      end
+    end
+  end
+
+  at_exit { ShellSession.cleanup_all }
+
+  private
+
+  def start
+    create_fifo
+    spawn_shell
+    start_stderr_reader
+    init_shell
+    update_pwd
+    @alive = true
+  end
+
+  def create_fifo
+    File.mkfifo(@fifo_path)
+  rescue Errno::EEXIST
+    # FIFO already exists — reuse it
+  end
+
+  def spawn_shell
+    @pty_stdout, @pty_stdin, @pid = PTY.spawn(
+      {"TERM" => "dumb"},
+      "bash", "--norc", "--noprofile"
+    )
+    # Disable terminal echo via termios before bash can echo our commands.
+    # This is instant (kernel-level), unlike stty -echo which races with input.
+    @pty_stdin.echo = false
+  end
+
+  def start_stderr_reader
+    @stderr_mutex = Mutex.new
+    @stderr_buffer = []
+    @stderr_bytes = 0
+    @stderr_truncated = false
+    @stderr_thread = Thread.new do
+      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
+              @stderr_buffer << cleaned
+              @stderr_bytes += cleaned.bytesize
+            else
+              @stderr_truncated = true
+            end
+          end
+        end
+      end
+    rescue Errno::ENOENT, IOError
+      # FIFO was cleaned up or closed
+    end
+  end
+
+  # With echo already off (set in spawn_shell), only command output appears.
+  # The initial bash prompt merges with the marker output on one gets line.
+  def init_shell
+    marker = "__ANIMA_INIT_#{SecureRandom.hex(8)}__"
+    @pty_stdin.puts "PS1=''"
+    @pty_stdin.puts "exec 2>#{@fifo_path}"
+    @pty_stdin.puts "echo '#{marker}'"
+    consume_until(marker)
+  end
+
+  def execute_in_pty(command)
+    clear_stderr
+    marker = "__ANIMA_#{SecureRandom.hex(8)}__"
+
+    Timeout.timeout(COMMAND_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"
+
+      stdout, exit_code = read_until_marker(marker)
+      update_pwd
+      stderr = drain_stderr
+
+      {
+        stdout: truncate(stdout),
+        stderr: truncate(stderr),
+        exit_code: exit_code
+      }
+    end
+  rescue Timeout::Error
+    recover_from_timeout
+    {error: "Command timed out after #{COMMAND_TIMEOUT} seconds"}
+  rescue Errno::EIO
+    @alive = false
+    {error: "Shell session terminated unexpectedly"}
+  rescue => error
+    {error: "#{error.class}: #{error.message}"}
+  end
+
+  def read_until_marker(marker)
+    lines = []
+    exit_code = nil
+
+    loop do
+      line = @pty_stdout.gets
+      break if line.nil?
+
+      line = line.chomp.delete("\r")
+
+      if line.include?(marker)
+        exit_code = line.split.last.to_i
+        break
+      end
+
+      lines << line
+    end
+
+    # Strip trailing empty line added by our separator echo
+    lines.pop if lines.last == ""
+
+    [lines.join("\n"), exit_code || -1]
+  end
+
+  def consume_until(marker)
+    loop do
+      line = @pty_stdout.gets
+      break if line.nil?
+      break if line.chomp.delete("\r").include?(marker)
+    end
+  end
+
+  # Sends Ctrl+C to interrupt the running command and drains leftover output.
+  # If recovery fails, marks the session as dead.
+  def recover_from_timeout
+    @pty_stdin.write("\x03")
+    sleep 0.1
+    marker = "__ANIMA_RECOVER_#{SecureRandom.hex(8)}__"
+    @pty_stdin.puts "echo '#{marker}'"
+    Timeout.timeout(3) { consume_until(marker) }
+  rescue Timeout::Error, Errno::EIO, IOError
+    @alive = false
+  end
+
+  def clear_stderr
+    @stderr_mutex.synchronize do
+      @stderr_buffer.clear
+      @stderr_bytes = 0
+      @stderr_truncated = false
+    end
+  end
+
+  def drain_stderr
+    # Allow FIFO reader thread time to flush kernel buffers into @stderr_buffer.
+    # Without this, stderr arriving just before the marker may be missed.
+    sleep 0.01
+    @stderr_mutex.synchronize do
+      result = @stderr_buffer.join("\n")
+      truncated = @stderr_truncated
+      @stderr_buffer.clear
+      @stderr_bytes = 0
+      @stderr_truncated = false
+      truncated ? result + "\n\n[Truncated: output exceeded #{MAX_OUTPUT_BYTES} bytes]" : result
+    end
+  end
+
+  # Reads the shell's current working directory via the /proc filesystem.
+  # @note Linux-only. Falls back silently on other platforms or if the
+  #   process has exited.
+  def update_pwd
+    @pwd = File.readlink("/proc/#{@pid}/cwd")
+  rescue Errno::ENOENT, Errno::EACCES
+    # Process exited or no access — @pwd retains its previous value
+  end
+
+  def truncate(output)
+    return output if output.bytesize <= MAX_OUTPUT_BYTES
+
+    output.byteslice(0, MAX_OUTPUT_BYTES)
+      .force_encoding("UTF-8")
+      .scrub +
+      "\n\n[Truncated: output exceeded #{MAX_OUTPUT_BYTES} bytes]"
+  end
+
+  def shutdown
+    return unless @alive
+    @alive = false
+
+    begin
+      pgid = Process.getpgid(@pid)
+      Process.kill("TERM", -pgid)
+    rescue Errno::ESRCH, Errno::EPERM
+      # Process group already gone
+    end
+
+    begin
+      @pty_stdin&.close
+    rescue IOError
+      # Already closed
+    end
+
+    begin
+      @pty_stdout&.close
+    rescue IOError
+      # Already closed
+    end
+
+    begin
+      @stderr_thread&.kill
+    rescue ThreadError
+      # Thread already dead
+    end
+
+    File.delete(@fifo_path) if File.exist?(@fifo_path)
+
+    begin
+      # Non-blocking reap with SIGKILL fallback if process doesn't exit in time
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
+      loop do
+        _, status = Process.wait2(@pid, Process::WNOHANG)
+        break if status
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          Process.kill("KILL", @pid)
+          Process.wait(@pid)
+          break
+        end
+        sleep 0.05
+      end
+    rescue Errno::ECHILD, Errno::ESRCH
+      # Already reaped
+    end
+  end
+end