anima-core 0.0.1 → 0.2.0

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

data/lib/tools/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tools
+  # Abstract base class for all Anima tools. Subclasses must implement
+  # the class-level schema methods and the instance-level {#execute} method.
+  #
+  # @abstract Subclass and implement {.tool_name}, {.description},
+  #   {.input_schema}, and {#execute}
+  #
+  # @example Implementing a tool
+  #   class Tools::Echo < Tools::Base
+  #     def self.tool_name = "echo"
+  #     def self.description = "Echoes input back"
+  #     def self.input_schema
+  #       {type: "object", properties: {text: {type: "string"}}, required: ["text"]}
+  #     end
+  #
+  #     def execute(input)
+  #       input["text"]
+  #     end
+  #   end
+  class Base
+    class << self
+      # @return [String] unique tool identifier sent to the LLM
+      def tool_name
+        raise NotImplementedError, "#{self} must implement .tool_name"
+      end
+
+      # @return [String] human-readable description for the LLM
+      def description
+        raise NotImplementedError, "#{self} must implement .description"
+      end
+
+      # @return [Hash] JSON Schema describing the tool's input parameters
+      def input_schema
+        raise NotImplementedError, "#{self} must implement .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
+    end
+
+    # Accepts and discards context keywords so that the Registry can pass
+    # shared dependencies (e.g. shell_session) to any tool uniformly.
+    # Subclasses that need specific context should override with named kwargs.
+    def initialize(**) = nil
+
+    # Execute the tool with the given input.
+    # @param input [Hash] parsed input matching {.input_schema}
+    # @return [String, Hash] result content; Hash with :error key signals failure
+    def execute(input)
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
+  end
+end

data/lib/tools/bash.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tools
+  # Executes bash commands in a persistent {ShellSession}. Commands share
+  # working directory, environment variables, and shell history within a
+  # conversation. Output is truncated and timeouts are enforced by the
+  # underlying session.
+  #
+  # @see ShellSession#run
+  class Bash < Base
+    def self.tool_name = "bash"
+
+    def self.description = "Execute a bash command. Working directory and environment persist across calls within a conversation."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          command: {type: "string", description: "The bash command to execute"}
+        },
+        required: ["command"]
+      }
+    end
+
+    # @param shell_session [ShellSession] persistent shell backing this tool
+    def initialize(shell_session:, **)
+      @shell_session = shell_session
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] formatted output with stdout, stderr, and exit code
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      command = input["command"].to_s
+      return {error: "Command cannot be blank"} if command.strip.empty?
+
+      result = @shell_session.run(command)
+      return result if result.key?(:error)
+
+      format_result(result[:stdout], result[:stderr], result[:exit_code])
+    end
+
+    private
+
+    def format_result(stdout, stderr, exit_code)
+      parts = []
+      parts << "stdout:\n#{stdout}" unless stdout.empty?
+      parts << "stderr:\n#{stderr}" unless stderr.empty?
+      parts << "exit_code: #{exit_code}"
+      parts.join("\n\n")
+    end
+  end
+end

data/lib/tools/registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # @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
+    attr_reader :tools
+
+    # @param context [Hash] keyword arguments forwarded to every tool constructor
+    def initialize(context: {})
+      @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
+    # @return [void]
+    def register(tool_class)
+      @tools[tool_class.tool_name] = tool_class
+    end
+
+    # @return [Array<Hash>] schema array for the Anthropic tools API parameter
+    def schemas
+      @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.
+    #
+    # @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)
+    end
+
+    # @param name [String] tool name to check
+    # @return [Boolean] whether a tool with the given name is registered
+    def registered?(name)
+      @tools.key?(name)
+    end
+
+    # @return [Boolean] whether any tools are registered
+    def any?
+      @tools.any?
+    end
+  end
+end

data/lib/tools/web_get.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Tools
+  # Fetches content from a URL via HTTP GET. Returns the response body
+  # as plain text, truncated to {MAX_RESPONSE_BYTES} to prevent memory issues.
+  #
+  # Only http and https schemes are allowed.
+  class WebGet < Base
+    MAX_RESPONSE_BYTES = 100_000
+    REQUEST_TIMEOUT = 10
+
+    def self.tool_name = "web_get"
+
+    def self.description = "Fetch content from a URL via HTTP GET and return the response body"
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          url: {type: "string", description: "The URL to fetch (http or https)"}
+        },
+        required: ["url"]
+      }
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] response body (possibly truncated)
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      validate_and_fetch(input["url"].to_s)
+    end
+
+    private
+
+    def validate_and_fetch(url)
+      scheme = URI.parse(url).scheme
+
+      unless %w[http https].include?(scheme)
+        return {error: "Only http and https URLs are supported, got: #{scheme.inspect}"}
+      end
+
+      truncate_body(HTTParty.get(url, timeout: REQUEST_TIMEOUT, follow_redirects: false).body.to_s)
+    rescue URI::InvalidURIError => error
+      {error: "Invalid URL: #{error.message}"}
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      {error: "Request timed out after #{REQUEST_TIMEOUT} seconds"}
+    rescue Errno::ECONNREFUSED
+      {error: "Connection refused: #{url}"}
+    rescue => error
+      {error: "#{error.class}: #{error.message}"}
+    end
+
+    def truncate_body(body)
+      return body if body.bytesize <= MAX_RESPONSE_BYTES
+
+      body.byteslice(0, MAX_RESPONSE_BYTES) +
+        "\n\n[Truncated: response exceeded #{MAX_RESPONSE_BYTES} bytes]"
+    end
+  end
+end