jrubyagents 0.2.1

data/lib/rubyagents/sandbox.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Rubyagents
+  class Sandbox
+    DEFAULT_TIMEOUT = 30 # seconds
+
+    # ---------------------------------------------------------------------------
+    # Executor strategy — selected once at load time based on the Ruby engine.
+    # Adding a new backend (e.g. TruffleRuby) is a new subclass + one constant.
+    # ---------------------------------------------------------------------------
+    class Executor
+      def self.for_platform
+        RUBY_ENGINE == "jruby" ? ThreadExecutor : ForkExecutor
+      end
+
+      def call(_timeout, &_block)
+        raise NotImplementedError, "#{self.class}#call not implemented"
+      end
+    end
+
+    # MRI / TruffleRuby: fork gives full process isolation and safe kill.
+    class ForkExecutor < Executor
+      def call(timeout, &block)
+        reader, writer = IO.pipe
+
+        pid = Process.fork do
+          reader.close
+          Marshal.dump(block.call, writer)
+        rescue => e
+          Marshal.dump({ error: "#{e.class}: #{e.message}" }, writer)
+        ensure
+          writer.close
+          exit!(0)
+        end
+
+        writer.close
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          _, status = Process.waitpid2(pid, Process::WNOHANG)
+          if status
+            break
+          elsif Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            Process.kill("KILL", pid)
+            Process.waitpid(pid)
+            reader.close
+            return { error: "Execution timed out after #{timeout}s" }
+          end
+          sleep 0.05
+        end
+
+        data = reader.read
+        reader.close
+
+        data.empty? ? { output: "", result: nil, is_final_answer: false } : Marshal.load(data) # rubocop:disable Security/MarshalLoad
+      end
+    end
+
+    # JRuby >= 10.0.3.0: fork is unavailable; use a thread with a join-based timeout.
+    # STDOUT_MUTEX serializes $stdout redirection so concurrent sandbox calls
+    # (e.g. managed agents) don't interleave captured output.
+    class ThreadExecutor < Executor
+      STDOUT_MUTEX = Mutex.new
+
+      def call(timeout, &block)
+        result = nil
+        error  = nil
+
+        thread = Thread.new do
+          STDOUT_MUTEX.synchronize { result = block.call }
+        rescue => e
+          error = "#{e.class}: #{e.message}"
+        end
+
+        unless thread.join(timeout)
+          thread.kill
+          return { error: "Execution timed out after #{timeout}s" }
+        end
+
+        error ? { error: error } : result
+      end
+    end
+
+    EXECUTOR = Executor.for_platform.new
+
+    attr_reader :timeout
+
+    def initialize(tools:, timeout: DEFAULT_TIMEOUT)
+      @tools = tools
+      @timeout = timeout
+      @tool_map = tools.each_with_object({}) { |t, h| h[t.class.tool_name] = t }
+    end
+
+    def execute(code)
+      EXECUTOR.call(@timeout) { run_in_child(code) }
+    end
+
+    private
+
+    def run_in_child(code)
+      # Capture stdout
+      stdout_capture = StringIO.new
+      $stdout = stdout_capture
+
+      # Create a clean execution context with tool methods
+      context = build_context
+
+      result = context.instance_eval(code, "(agent)", 1)
+      $stdout = STDOUT
+
+      output = stdout_capture.string
+      { output: output, result: result, is_final_answer: false }
+    rescue FinalAnswerException => e
+      $stdout = STDOUT
+      output = stdout_capture.string
+      { output: output, result: e.value, is_final_answer: true }
+    end
+
+    def build_context
+      ctx = Object.new
+
+      # Define each tool as a method on the context object
+      @tool_map.each do |name, tool|
+        if name == "final_answer"
+          # Wrap final_answer to raise FinalAnswerException
+          ctx.define_singleton_method(name) do |**kwargs|
+            result = tool.call(**kwargs)
+            raise FinalAnswerException.new(result)
+          end
+        else
+          ctx.define_singleton_method(name) do |**kwargs|
+            tool.call(**kwargs)
+          end
+        end
+      end
+
+      ctx
+    end
+  end
+end

data/lib/rubyagents/tool.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class Tool
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@inputs, {})
+      end
+
+      def tool_name(value = nil)
+        if value
+          @tool_name = value
+        else
+          @tool_name || name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        end
+      end
+      alias_method :name, :tool_name
+
+      def description(value = nil)
+        if value
+          @description = value
+        else
+          @description || ""
+        end
+      end
+
+      def input(name, type:, description:, required: true)
+        @inputs[name] = { type: type, description: description, required: required }
+      end
+
+      def inputs
+        @inputs ||= {}
+      end
+
+      def output_type(value = nil)
+        if value
+          @output_type = value
+        else
+          @output_type || :string
+        end
+      end
+
+      def to_schema
+        properties = {}
+        required = []
+
+        inputs.each do |param_name, config|
+          properties[param_name] = {
+            type: config[:type].to_s,
+            description: config[:description]
+          }
+          required << param_name.to_s if config[:required]
+        end
+
+        {
+          name: tool_name,
+          description: description,
+          parameters: {
+            type: "object",
+            properties: properties,
+            required: required
+          }
+        }
+      end
+
+      def to_prompt
+        lines = ["Tool: #{tool_name}", "Description: #{description}"]
+
+        if inputs.any?
+          lines << "Inputs:"
+          inputs.each do |param_name, config|
+            opt = config[:required] ? "" : " (optional)"
+            lines << "  - #{param_name} (#{config[:type]}#{opt}): #{config[:description]}"
+          end
+        end
+
+        lines << "Output type: #{output_type}"
+        lines.join("\n")
+      end
+    end
+
+    def call(**kwargs)
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+  end
+
+  # Built-in tool: signals the final answer
+  class FinalAnswerTool < Tool
+    tool_name "final_answer"
+    description "Returns the final answer to the user's question"
+    input :answer, type: :string, description: "The final answer to return"
+    output_type :string
+
+    def call(answer:)
+      answer
+    end
+  end
+
+  # Block-based tool shorthand
+  # Usage:
+  #   greet = Rubyagents.tool(:greet, "Greets a person", name: "The person's name") { |name:| "Hello, #{name}!" }
+  def self.tool(tool_name, desc, output: :string, **inputs, &block)
+    klass = Class.new(Tool) do
+      self.tool_name(tool_name.to_s)
+      self.description(desc)
+
+      inputs.each do |param_name, param_desc|
+        type, description = if param_desc.is_a?(Hash)
+          [param_desc[:type] || :string, param_desc[:description] || param_desc.to_s]
+        else
+          [:string, param_desc.to_s]
+        end
+        input param_name, type: type, description: description
+      end
+
+      self.output_type(output)
+
+      define_method(:call, &block)
+    end
+
+    klass.new
+  end
+end

data/lib/rubyagents/tool_calling_agent.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class ToolCallingAgent < Agent
+    private
+
+    def system_prompt
+      prompt = if @prompt_templates.system_prompt
+        tool_descriptions = tools.map { |t| t.class.to_prompt }.join("\n\n")
+        @prompt_templates.system_prompt.gsub("{{tool_descriptions}}", tool_descriptions)
+      else
+        Prompt.tool_calling_agent_system(tools: tools)
+      end
+      prompt = "#{prompt}\n\n#{@instructions}" if @instructions
+      prompt
+    end
+
+    def generate_response(messages, &on_stream)
+      tool_schemas = tools.map { |t| t.class.to_schema }
+      spin = on_stream ? nil : UI.spinner("Thinking...")
+      spin&.start
+      response = @model.generate(messages, tools: tool_schemas, &on_stream)
+      spin&.stop
+      response
+    end
+
+    def parse_response(response)
+      [response.content, response.tool_calls]
+    end
+
+    def run_action(thought, tool_calls, response, llm_duration)
+      return nil unless tool_calls&.any?
+
+      results = []
+      final_answer_value = nil
+
+      tool_calls.each do |tc|
+        tool_name = tc.function.name
+        arguments = tc.function.arguments
+
+        UI.code("#{tool_name}(#{arguments.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")})")
+        notify(:on_tool_call, tool_name: tool_name, arguments: arguments)
+
+        if tool_name == "final_answer"
+          final_answer_value = arguments[:answer] || arguments["answer"]
+          results << "Final answer: #{final_answer_value}"
+          next
+        end
+
+        tool = @tool_map[tool_name]
+        unless tool
+          error_msg = "Unknown tool: #{tool_name}"
+          UI.error(error_msg)
+          results << "Error: #{error_msg}"
+          next
+        end
+
+        begin
+          # Convert string keys to symbols for tool call
+          sym_args = arguments.transform_keys(&:to_sym)
+          result = tool.call(**sym_args)
+          UI.observation(result.to_s)
+          results << result.to_s
+        rescue => e
+          UI.error("#{e.class}: #{e.message}")
+          results << "Error: #{e.message}"
+        end
+      end
+
+      total_output = results.join("\n")
+      UI.step_metrics(duration: llm_duration, token_usage: response.token_usage)
+
+      step = memory.add_step(
+        thought: thought,
+        tool_calls: tool_calls,
+        observation: total_output,
+        duration: llm_duration,
+        token_usage: response.token_usage
+      )
+      notify_callbacks(step)
+
+      final_answer_value
+    end
+  end
+end

data/lib/rubyagents/tools/file_read.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class FileRead < Tool
+    tool_name "file_read"
+    description "Reads the contents of a file at the given path and returns it as text"
+    input :path, type: :string, description: "The path to the file to read"
+    output_type :string
+
+    MAX_CHARS = 50_000
+
+    def call(path:)
+      expanded = File.expand_path(path)
+      content = File.read(expanded)
+      content.length > MAX_CHARS ? content[0, MAX_CHARS] : content
+    rescue => e
+      "Error reading #{path}: #{e.message}"
+    end
+  end
+end

data/lib/rubyagents/tools/file_write.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rubyagents
+  class FileWrite < Tool
+    tool_name "file_write"
+    description "Writes content to a file at the given path, creating parent directories if needed"
+    input :path, type: :string, description: "The path to the file to write"
+    input :content, type: :string, description: "The content to write to the file"
+    output_type :string
+
+    def call(path:, content:)
+      expanded = File.expand_path(path)
+      FileUtils.mkdir_p(File.dirname(expanded))
+      File.write(expanded, content)
+      "Successfully wrote #{content.length} bytes to #{expanded}"
+    rescue => e
+      "Error writing #{path}: #{e.message}"
+    end
+  end
+end

data/lib/rubyagents/tools/list_gems.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class ListGems < Tool
+    tool_name "list_gems"
+    description "Lists Ruby gems available in the current environment that you can require and use in your code"
+    output_type :string
+
+    def call(**_kwargs)
+      specs = Gem::Specification.sort_by(&:name)
+      lines = specs.map { |s| "#{s.name} (#{s.version}) - #{s.summary&.slice(0, 80)}" }
+      lines.join("\n")
+    end
+  end
+end

data/lib/rubyagents/tools/user_input.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class UserInput < Tool
+    tool_name "user_input"
+    description "Asks the user a question and returns their response. Use this when you need clarification."
+    input :question, type: :string, description: "The question to ask the user"
+    output_type :string
+
+    def call(question:)
+      $stderr.print "\n#{question}\n> "
+      response = $stdin.gets&.strip
+      response || ""
+    end
+  end
+end

data/lib/rubyagents/tools/visit_webpage.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "reverse_markdown"
+
+module Rubyagents
+  class VisitWebpage < Tool
+    tool_name "visit_webpage"
+    description "Fetches the content of a webpage and returns it as markdown"
+    input :url, type: :string, description: "The URL of the webpage to visit"
+    output_type :string
+
+    def call(url:)
+      uri = URI(url)
+      uri = URI("https://#{url}") unless uri.scheme
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 15
+      http.open_timeout = 10
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+      request["Accept"] = "text/html"
+
+      response = http.request(request)
+
+      # Follow redirects (one level)
+      if response.is_a?(Net::HTTPRedirection) && response["location"]
+        return call(url: response["location"])
+      end
+
+      body = response.body
+        .force_encoding("UTF-8")
+        .encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+
+      md = ReverseMarkdown.convert(body, unknown_tags: :bypass, github_flavored: true).strip
+      md.empty? ? "No readable content found at #{url}" : md[0, 10_000]
+    rescue => e
+      "Error fetching #{url}: #{e.message}"
+    end
+  end
+end

data/lib/rubyagents/tools/web_search.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "cgi"
+
+module Rubyagents
+  # NOTE: DuckDuckGo HTML scraping is fragile - selectors may break if DDG changes their markup.
+  class WebSearch < Tool
+    tool_name "web_search"
+    description "Searches the web using DuckDuckGo and returns results"
+    input :query, type: :string, description: "The search query"
+    output_type :string
+
+    def call(query:)
+      uri = URI("https://html.duckduckgo.com/html/")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      request = Net::HTTP::Post.new(uri)
+      request["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+      request.set_form_data(q: query)
+
+      response = http.request(request)
+
+      # Parse basic results from HTML
+      results = response.body.scan(/<a rel="nofollow" class="result__a" href="(.*?)".*?>(.*?)<\/a>/m)
+      snippets = response.body.scan(/<a class="result__snippet".*?>(.*?)<\/a>/m)
+
+      output = results.first(5).each_with_index.map do |r, i|
+        url = CGI.unescapeHTML(r[0])
+        title = r[1].gsub(/<.*?>/, "").strip
+        snippet = snippets[i] ? snippets[i][0].gsub(/<.*?>/, "").strip : ""
+        "#{i + 1}. #{title}\n   #{url}\n   #{snippet}"
+      end
+
+      output.empty? ? "No results found for: #{query}" : output.join("\n\n")
+    rescue => e
+      "Search error: #{e.message}"
+    end
+  end
+end

data/lib/rubyagents/ui.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+JRUBY = RUBY_ENGINE == "jruby"
+
+require "lipgloss" unless JRUBY # lipgloss is not available on JRuby >= 10.0.3.0
+require "rouge"
+
+module Rubyagents
+  module UI
+    SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+    # Passthrough style used on JRuby where lipgloss is unavailable
+    class NullStyle
+      def render(text)
+        text
+      end
+    end
+
+    module Styles
+      if JRUBY
+        def self.label;         NullStyle.new; end
+        def self.plan_label;    NullStyle.new; end
+        def self.plan_box;      NullStyle.new; end
+        def self.final_answer;  NullStyle.new; end
+        def self.error;         NullStyle.new; end
+        def self.dim;           NullStyle.new; end
+        def self.spinner_style; NullStyle.new; end
+      else
+        def self.label
+          @label ||= Lipgloss::Style.new.faint(true)
+        end
+
+        def self.plan_label
+          @plan_label ||= Lipgloss::Style.new
+            .bold(true)
+            .foreground("#011627")
+            .background("#FF9F1C")
+            .padding(0, 1)
+        end
+
+        def self.plan_box
+          @plan_box ||= Lipgloss::Style.new
+            .border(:rounded)
+            .border_foreground("#FF9F1C")
+            .padding(0, 2)
+        end
+
+        def self.final_answer
+          @final_answer ||= Lipgloss::Style.new
+            .bold(true)
+            .foreground("#2EC4B6")
+        end
+
+        def self.error
+          @error ||= Lipgloss::Style.new
+            .bold(true)
+            .foreground("#FF0000")
+        end
+
+        def self.dim
+          @dim ||= Lipgloss::Style.new.faint(true)
+        end
+
+        def self.spinner_style
+          @spinner_style ||= Lipgloss::Style.new
+            .foreground("#7B61FF")
+        end
+      end
+    end
+
+    class Spinner
+      def initialize(message)
+        @message = message
+        @running = false
+        @frame = 0
+      end
+
+      def start
+        @running = true
+        @thread = Thread.new do
+          while @running
+            char = SPINNER_FRAMES[@frame % SPINNER_FRAMES.size]
+            frame = Styles.spinner_style.render(char)
+            $stderr.print "\r\e[K#{frame} #{@message}"
+            @frame += 1
+            sleep 0.08
+          end
+          $stderr.print "\r\e[K"
+        end
+      end
+
+      def stop
+        @running = false
+        @thread&.join
+      end
+    end
+
+    class << self
+      def thought(text)
+        puts Styles.label.render("Thought: ") + text
+      end
+
+      def code(source)
+        puts
+        highlighted = rouge_formatter.format(rouge_lexer.lex(source))
+        highlighted.each_line { |line| puts "  #{line.rstrip}" }
+        puts
+      end
+
+      def observation(text)
+        puts Styles.label.render("Result: ") + truncate(text, 200)
+      end
+
+      def error(text)
+        puts Styles.error.render("Error: ") + text
+      end
+
+      def plan(text)
+        label = Styles.plan_label.render(" Plan ")
+        body = Styles.plan_box.render(text)
+        puts "\n#{label}\n#{body}\n"
+      end
+
+      def step_metrics(duration:, token_usage:)
+        parts = []
+        parts << format("%.1fs", duration) if duration > 0
+        parts << token_usage.to_s if token_usage
+        return if parts.empty?
+
+        puts Styles.dim.render(parts.join(" | "))
+        puts
+      end
+
+      def run_summary(total_steps:, total_duration:, total_tokens:)
+        parts = ["#{total_steps} steps", format("%.1fs total", total_duration)]
+        parts << total_tokens.to_s if total_tokens.total_tokens > 0
+        puts Styles.dim.render(parts.join(" | "))
+      end
+
+      def final_answer(text)
+        puts
+        puts Styles.final_answer.render("Final answer: ") + text.to_s
+      end
+
+      def spinner(message)
+        Spinner.new(message)
+      end
+
+      def welcome
+        if JRUBY
+          puts "rubyagents v#{VERSION}"
+          puts "Code-first AI agents for Ruby"
+        else
+          title = Lipgloss::Style.new
+            .bold(true)
+            .foreground("#7B61FF")
+            .render("rubyagents")
+
+          version = Styles.dim.render("v#{VERSION}")
+          puts "#{title} #{version}"
+          puts Styles.dim.render("Code-first AI agents for Ruby")
+        end
+        puts
+      end
+
+      private
+
+      def rouge_lexer
+        @rouge_lexer ||= Rouge::Lexers::Ruby.new
+      end
+
+      def rouge_formatter
+        @rouge_formatter ||= Rouge::Formatters::Terminal256.new(Rouge::Themes::Monokai.new)
+      end
+
+      def truncate(text, max)
+        return text if text.length <= max
+        text[0...max] + Styles.dim.render("... (truncated)")
+      end
+
+    end
+  end
+end