jrubyagents 0.2.1

data/lib/rubyagents/agent.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class Agent
+    attr_reader :name, :description, :model, :tools, :max_steps, :memory, :planning_interval, :step_callbacks, :callbacks
+
+    def initialize(model:, tools: [], agents: [], name: nil, description: nil,
+                   max_steps: 10, planning_interval: nil, step_callbacks: [],
+                   callbacks: [], final_answer_checks: [], prompt_templates: nil,
+                   instructions: nil, output_type: nil)
+      @name = name
+      @description = description
+      @model = model.is_a?(String) ? Model.for(model) : model
+      @tools = build_tools(tools, agents)
+      @max_steps = max_steps
+      @planning_interval = planning_interval
+      @step_callbacks = step_callbacks
+      @callbacks = Array(callbacks)
+      @final_answer_checks = final_answer_checks
+      @prompt_templates = prompt_templates || PromptTemplates.new
+      @instructions = instructions
+      @output_type = output_type
+      @memory = nil
+      @interrupt_switch = false
+      @step_number = 0
+      @final_answer_value = nil
+      @tool_map = @tools.each_with_object({}) { |t, h| h[t.class.tool_name] = t }
+    end
+
+    def run(task, reset: true, return_full_result: false, &on_stream)
+      @interrupt_switch = false
+
+      if reset || @memory.nil?
+        @memory = Memory.new(system_prompt: system_prompt, task: task)
+      else
+        memory.add_user_message(task)
+      end
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      notify(:on_run_start, task: task)
+
+      (1..max_steps).each do |step_number|
+        raise InterruptError, "Agent interrupted" if @interrupt_switch
+
+        notify(:on_step_start, step_number: step_number)
+        maybe_plan(step_number)
+
+        # Call LLM with timing
+        llm_duration, response = timed { generate_response(memory.to_messages, &on_stream) }
+
+        # Parse response
+        thought, action = parse_response(response)
+        UI.thought(thought) if thought
+
+        # Check for final answer or execute
+        if action
+          result = run_action(thought, action, response, llm_duration)
+          if result
+            error_msg = validate_final_answer(result)
+            error_msg ||= validate_output_type(result)
+            if error_msg
+              memory.add_user_message(error_msg)
+              next
+            end
+            total_timing = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+            built = build_result(result, total_timing, return_full_result)
+            notify(:on_run_end, result: built)
+            return built
+          end
+        else
+          UI.step_metrics(duration: llm_duration, token_usage: response.token_usage)
+          step = memory.add_step(thought: thought || response.content, code: nil, observation: nil,
+                                 duration: llm_duration, token_usage: response.token_usage)
+          notify_callbacks(step)
+        end
+      end
+
+      # Max steps reached
+      UI.run_summary(
+        total_steps: memory.action_steps.size,
+        total_duration: memory.total_duration,
+        total_tokens: memory.total_tokens
+      )
+      UI.error("Max steps (#{max_steps}) reached without a final answer")
+      notify(:on_error, error: MaxStepsError.new("Max steps (#{max_steps}) reached"))
+
+      total_timing = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      output = memory.last_step&.observation
+      result = RunResult.new(
+        output: output,
+        state: "max_steps",
+        steps: memory.action_steps,
+        token_usage: memory.total_tokens,
+        timing: total_timing
+      )
+      notify(:on_run_end, result: return_full_result ? result : output)
+      return_full_result ? result : output
+    end
+
+    # --- Step-by-step execution ---
+
+    def step(task_or_message = nil)
+      if @memory.nil?
+        raise ArgumentError, "task required on first call" unless task_or_message
+        @memory = Memory.new(system_prompt: system_prompt, task: task_or_message)
+        @step_number = 0
+        @interrupt_switch = false
+        @final_answer_value = nil
+      elsif task_or_message
+        memory.add_user_message(task_or_message)
+      end
+
+      @step_number += 1
+      raise MaxStepsError, "Max steps (#{max_steps}) reached" if @step_number > max_steps
+      raise InterruptError, "Agent interrupted" if @interrupt_switch
+
+      maybe_plan(@step_number)
+
+      llm_duration, response = timed { generate_response(memory.to_messages) }
+      thought, action = parse_response(response)
+
+      if action
+        result = run_action(thought, action, response, llm_duration)
+        if result
+          error_msg = validate_final_answer(result)
+          error_msg ||= validate_output_type(result)
+          if error_msg
+            memory.add_user_message(error_msg)
+          else
+            @final_answer_value = result
+          end
+        end
+      else
+        memory.add_step(thought: thought || response.content,
+                        duration: llm_duration, token_usage: response.token_usage)
+      end
+
+      memory.last_step
+    end
+
+    def done? = !@final_answer_value.nil?
+
+    def final_answer_value = @final_answer_value
+
+    def reset!
+      @memory = nil
+      @step_number = 0
+      @final_answer_value = nil
+      @interrupt_switch = false
+    end
+
+    def interrupt
+      @interrupt_switch = true
+    end
+
+    private
+
+    def system_prompt
+      raise NotImplementedError
+    end
+
+    def generate_response(messages, &on_stream)
+      spin = on_stream ? nil : UI.spinner("Thinking...")
+      spin&.start
+      response = @model.generate(messages, &on_stream)
+      spin&.stop
+      response
+    end
+
+    def parse_response(response)
+      raise NotImplementedError
+    end
+
+    def execute(action)
+      raise NotImplementedError
+    end
+
+    def run_action(thought, action, response, llm_duration)
+      raise NotImplementedError
+    end
+
+    def maybe_plan(step_number)
+      return unless planning_interval
+      if step_number == 1
+        run_planning_step(initial: true)
+      elsif (step_number % planning_interval) == 1
+        run_planning_step(initial: false)
+      end
+    end
+
+    def run_planning_step(initial: true)
+      spin = UI.spinner("Planning...")
+      spin.start
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      planning_messages = memory.to_messages
+      if initial
+        plan_prompt = @prompt_templates.planning_initial || Prompt.initial_plan
+        planning_messages[0] = { role: "system", content: plan_prompt }
+      else
+        plan_prompt = @prompt_templates.planning_update || Prompt.update_plan(progress_summary: memory.progress_summary)
+        planning_messages[0] = { role: "system", content: plan_prompt }
+      end
+
+      response = @model.generate(planning_messages)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      spin.stop
+
+      UI.plan(response.content)
+      UI.step_metrics(duration: duration, token_usage: response.token_usage)
+      memory.add_plan(plan: response.content, duration: duration, token_usage: response.token_usage)
+    end
+
+    def validate_final_answer(answer)
+      @final_answer_checks.each_with_index do |check, i|
+        unless check.call(answer, memory)
+          return "Final answer rejected by check ##{i + 1}. Please try a different answer."
+        end
+      end
+      nil
+    end
+
+    def validate_output_type(answer)
+      return nil unless @output_type
+      case @output_type
+      when Hash
+        require "json-schema"
+        errors = JSON::Validator.fully_validate(@output_type, answer)
+        errors.empty? ? nil : "Output validation failed: #{errors.join("; ")}"
+      when Proc
+        @output_type.call(answer) ? nil : "Output validation failed: custom validator returned falsy"
+      end
+    end
+
+    def build_tools(tool_classes, agents)
+      instances = [FinalAnswerTool.new]
+
+      tool_classes.each do |klass|
+        instances << (klass.is_a?(Tool) ? klass : klass.new)
+      end
+
+      agents.each do |agent|
+        instances << ManagedAgentTool.for(agent)
+      end
+
+      instances
+    end
+
+    def build_result(output, timing, return_full_result)
+      UI.run_summary(
+        total_steps: memory.action_steps.size,
+        total_duration: memory.total_duration,
+        total_tokens: memory.total_tokens
+      )
+      UI.final_answer(output)
+
+      result = RunResult.new(
+        output: output,
+        state: "success",
+        steps: memory.action_steps,
+        token_usage: memory.total_tokens,
+        timing: timing
+      )
+      return_full_result ? result : output
+    end
+
+    def notify_callbacks(step)
+      @step_callbacks.each { |cb| cb.call(step, agent: self) }
+      notify(:on_step_end, step: step)
+    end
+
+    def notify(event, **payload)
+      @callbacks.each do |cb|
+        cb.send(event, **payload, agent: self) if cb.respond_to?(event)
+      end
+    end
+
+    def format_output(result)
+      parts = []
+      parts << result[:output] unless result[:output].to_s.empty?
+      parts << result[:result].inspect unless result[:result].nil?
+      parts.join("\n")
+    end
+
+    def timed
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      [duration, result]
+    end
+  end
+
+  class ManagedAgentTool < Tool
+    tool_name "call_agent"
+    description "Delegates a task to a managed agent"
+    input :task, type: :string, description: "Task to delegate"
+    output_type :string
+
+    # Factory that creates an anonymous subclass per agent instance
+    def self.for(agent)
+      klass = Class.new(self) do
+        tool_name(agent.name || "agent")
+        description(agent.description || "A managed agent")
+      end
+      klass.new(agent)
+    end
+
+    def initialize(agent)
+      @agent = agent
+    end
+
+    def call(task:, **_kwargs)
+      @agent.run(task)
+    end
+  end
+end

data/lib/rubyagents/callback.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class Callback
+    def on_run_start(task:, agent:) = nil
+    def on_step_start(step_number:, agent:) = nil
+    def on_step_end(step:, agent:) = nil
+    def on_tool_call(tool_name:, arguments:, agent:) = nil
+    def on_error(error:, agent:) = nil
+    def on_run_end(result:, agent:) = nil
+  end
+end

data/lib/rubyagents/cli.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rubyagents
+  class CLI
+    TOOL_MAP = {
+      "web_search" => -> { require_relative "tools/web_search"; WebSearch },
+      "visit_webpage" => -> { require_relative "tools/visit_webpage"; VisitWebpage },
+      "user_input" => -> { require_relative "tools/user_input"; UserInput },
+      "file_read" => -> { require_relative "tools/file_read"; FileRead },
+      "file_write" => -> { require_relative "tools/file_write"; FileWrite }
+    }.freeze
+
+    def self.run(argv = ARGV)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv
+      @options = {
+        model: "openai/gpt-5.2",
+        tools: [],
+        mcp: [],
+        interactive: false,
+        max_steps: 10,
+        planning_interval: nil,
+        agent_type: "code"
+      }
+      parse_options!
+    end
+
+    def run
+      if @options[:interactive]
+        interactive_mode
+      elsif @query
+        single_query(@query)
+      else
+        puts @parser.help
+      end
+    end
+
+    private
+
+    def parse_options!
+      @parser = OptionParser.new do |opts|
+        opts.banner = "Usage: rubyagents [options] \"query\""
+        opts.separator ""
+
+        opts.on("-m", "--model MODEL", "Model to use (default: openai/gpt-5.2)") do |m|
+          @options[:model] = m
+        end
+
+        opts.on("-t", "--tools TOOLS", "Comma-separated tool names (#{TOOL_MAP.keys.join(", ")})") do |t|
+          @options[:tools] = t.split(",").map(&:strip)
+        end
+
+        opts.on("-a", "--agent-type TYPE", "Agent type: code or tool_calling (default: code)") do |a|
+          @options[:agent_type] = a
+        end
+
+        opts.on("-p", "--plan N", Integer, "Re-plan every N steps") do |n|
+          @options[:planning_interval] = n
+        end
+
+        opts.on("-i", "--interactive", "Interactive mode") do
+          @options[:interactive] = true
+        end
+
+        opts.on("--mcp COMMAND", "MCP server command (repeatable)") do |cmd|
+          @options[:mcp] << cmd
+        end
+
+        opts.on("-s", "--max-steps N", Integer, "Max agent steps (default: 10)") do |n|
+          @options[:max_steps] = n
+        end
+
+        opts.on("-v", "--version", "Show version") do
+          puts "rubyagents #{VERSION}"
+          exit
+        end
+
+        opts.on("-h", "--help", "Show help") do
+          puts opts
+          exit
+        end
+      end
+
+      @parser.parse!(@argv)
+      @query = @argv.join(" ") unless @argv.empty?
+    end
+
+    def build_agent
+      tools = @options[:tools].filter_map do |name|
+        loader = TOOL_MAP[name]
+        if loader
+          loader.call
+        else
+          $stderr.puts "Unknown tool: #{name}. Available: #{TOOL_MAP.keys.join(", ")}"
+          nil
+        end
+      end
+
+      @options[:mcp].each do |cmd|
+        mcp_tools = Rubyagents.tools_from_mcp(command: cmd)
+        tools.concat(mcp_tools)
+      end
+
+      agent_class = @options[:agent_type] == "tool_calling" ? ToolCallingAgent : CodeAgent
+
+      agent_class.new(
+        model: @options[:model],
+        tools: tools,
+        max_steps: @options[:max_steps],
+        planning_interval: @options[:planning_interval]
+      )
+    end
+
+    def single_query(query)
+      UI.welcome
+      agent = build_agent
+      agent.run(query)
+    end
+
+    def interactive_mode
+      UI.welcome
+      puts "Type your queries (Ctrl+C to exit)\n\n"
+
+      agent = build_agent
+      first = true
+
+      loop do
+        prompt = RUBY_ENGINE == "jruby" ? ">> " : Lipgloss::Style.new.bold(true).foreground("#7B61FF").render(">> ")
+        print prompt
+        query = $stdin.gets&.strip
+        break if query.nil? || query.empty?
+
+        agent.run(query, reset: first)
+        first = false
+        puts
+      end
+    rescue Interrupt
+      puts "\nGoodbye!"
+    end
+  end
+end

data/lib/rubyagents/code_agent.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class CodeAgent < Agent
+    CODE_BLOCK_RE = /```ruby\s*\n(.*?)```/m
+
+    def initialize(model:, tools: [], agents: [], name: nil, description: nil,
+                   max_steps: 10, timeout: 30, planning_interval: nil, step_callbacks: [],
+                   callbacks: [], final_answer_checks: [], prompt_templates: nil,
+                   instructions: nil, output_type: nil)
+      require_relative "tools/list_gems"
+      tools = [ListGems] + tools unless tools.any? { |t| t == ListGems || (t.is_a?(Tool) && t.is_a?(ListGems)) }
+      super(model: model, tools: tools, agents: agents, name: name, description: description,
+            max_steps: max_steps, planning_interval: planning_interval, step_callbacks: step_callbacks,
+            callbacks: callbacks, final_answer_checks: final_answer_checks,
+            prompt_templates: prompt_templates, instructions: instructions, output_type: output_type)
+      @timeout = timeout
+    end
+
+    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.code_agent_system(tools: tools)
+      end
+      prompt = "#{prompt}\n\n#{@instructions}" if @instructions
+      prompt
+    end
+
+    def parse_response(response)
+      content = response.content
+
+      thought = nil
+      if content =~ /Thought:\s*(.*?)(?=Code:|```ruby)/m
+        thought = $1.strip
+      elsif content =~ /Thought:\s*(.*)/m
+        thought = $1.strip
+      end
+
+      code = nil
+      if content =~ CODE_BLOCK_RE
+        code = $1.strip
+      end
+
+      [thought, code]
+    end
+
+    def run_action(thought, code, response, llm_duration)
+      UI.code(code)
+      exec_duration, result = timed { execute(code) }
+      total_duration = llm_duration + exec_duration
+
+      if result[:error]
+        UI.error(result[:error])
+        UI.step_metrics(duration: total_duration, token_usage: response.token_usage)
+        step = memory.add_step(thought: thought, code: code, error: result[:error],
+                               duration: total_duration, token_usage: response.token_usage)
+        notify_callbacks(step)
+        nil
+      else
+        output = format_output(result)
+        UI.observation(output)
+        UI.step_metrics(duration: total_duration, token_usage: response.token_usage)
+
+        step = memory.add_step(thought: thought, code: code, observation: output,
+                               duration: total_duration, token_usage: response.token_usage)
+        notify_callbacks(step)
+
+        result[:is_final_answer] ? result[:result] : nil
+      end
+    end
+
+    def execute(code)
+      spin = UI.spinner("Executing code...")
+      spin.start
+      sandbox = Sandbox.new(tools: tools, timeout: @timeout)
+      result = sandbox.execute(code)
+      spin.stop
+      result
+    end
+  end
+end

data/lib/rubyagents/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Rubyagents
+  class Error < StandardError; end
+  class AgentError < Error; end
+  class ParsingError < AgentError; end
+  class ExecutionError < AgentError; end
+  class GenerationError < AgentError; end
+  class MaxStepsError < AgentError; end
+  class InterruptError < AgentError; end
+
+  # Inherits Exception (not StandardError) so agent-generated `rescue => e` won't catch it
+  class FinalAnswerException < Exception # rubocop:disable Lint/InheritException
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+      super("Final answer reached")
+    end
+  end
+end

data/lib/rubyagents/mcp.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Rubyagents
+  module MCP
+    class StdioTransport
+      def initialize(command:)
+        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*Array(command))
+        @request_id = 0
+        handshake!
+      end
+
+      def send_request(request:)
+        @request_id += 1
+        payload = { jsonrpc: "2.0", id: @request_id }.merge(request)
+        write_message(payload)
+        read_response(@request_id)
+      end
+
+      def close
+        @stdin.close unless @stdin.closed?
+        @stdout.close unless @stdout.closed?
+        @stderr.close unless @stderr.closed?
+        @wait_thread.join
+      end
+
+      private
+
+      def handshake!
+        # Send initialize
+        @request_id += 1
+        init_request = {
+          jsonrpc: "2.0",
+          id: @request_id,
+          method: "initialize",
+          params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "rubyagents", version: Rubyagents::VERSION }
+          }
+        }
+        write_message(init_request)
+        read_response(@request_id)
+
+        # Send initialized notification (no id)
+        write_message({ jsonrpc: "2.0", method: "notifications/initialized" })
+      end
+
+      def write_message(hash)
+        line = JSON.generate(hash)
+        @stdin.puts(line)
+        @stdin.flush
+      end
+
+      def read_response(expected_id)
+        loop do
+          line = @stdout.gets
+          raise "MCP server closed connection" unless line
+          msg = JSON.parse(line.strip)
+          # Skip notifications (no id)
+          next unless msg.key?("id")
+          return msg if msg["id"] == expected_id
+        end
+      end
+    end
+
+    class MCPToolWrapper < Tool
+      attr_reader :mcp_tool, :client
+
+      def self.for(mcp_tool, client)
+        klass = Class.new(self) do
+          tool_name(mcp_tool["name"])
+          description(mcp_tool["description"] || "")
+
+          schema = mcp_tool.dig("inputSchema", "properties") || {}
+          required_fields = mcp_tool.dig("inputSchema", "required") || []
+          schema.each do |param_name, param_def|
+            input param_name.to_sym,
+                  type: (param_def["type"] || "string").to_sym,
+                  description: param_def["description"] || "",
+                  required: required_fields.include?(param_name)
+          end
+        end
+        klass.new(mcp_tool, client)
+      end
+
+      def initialize(mcp_tool, client)
+        @mcp_tool = mcp_tool
+        @client = client
+      end
+
+      def call(**kwargs)
+        response = @client.send_request(
+          request: {
+            method: "tools/call",
+            params: { name: @mcp_tool["name"], arguments: kwargs.transform_keys(&:to_s) }
+          }
+        )
+        # Extract text content from MCP response
+        content = response.dig("result", "content") || []
+        content.filter_map { |c| c["text"] if c["type"] == "text" }.join("\n")
+      end
+    end
+  end
+
+  def self.tools_from_mcp(command:)
+    transport = MCP::StdioTransport.new(command: command)
+    response = transport.send_request(request: { method: "tools/list", params: {} })
+    tools = response.dig("result", "tools") || []
+    tools.map { |t| MCP::MCPToolWrapper.for(t, transport) }
+  end
+
+  def self.tool_from_mcp(command:, tool_name:)
+    transport = MCP::StdioTransport.new(command: command)
+    response = transport.send_request(request: { method: "tools/list", params: {} })
+    tools = response.dig("result", "tools") || []
+    tool_def = tools.find { |t| t["name"] == tool_name }
+
+    unless tool_def
+      available = tools.map { |t| t["name"] }.join(", ")
+      raise ArgumentError, "Tool #{tool_name.inspect} not found. Available: #{available}"
+    end
+
+    MCP::MCPToolWrapper.for(tool_def, transport)
+  end
+end