robot_lab 0.3.0 → 0.5.0

data/examples/xyzzy.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-# xyzzy.rb — single-file RobotLab hook extension demo
-#
-# Demonstrates the Hook handler class pattern: implement class methods for
-# every hook under a dedicated namespace and log each callback with its
-# context snapshot. Useful as a live trace of the full hook pipeline during
-# development.
-#
-# Fully Ractor-safe: no class-level mutable state. LOG_PATH is a frozen
-# string constant (shareable); each call opens its own file handle.
-#
-# stdout : one tagline per hook call  →  [xyzzy] HH:MM:SS.mmm hook_name
-# logfile: full context snapshot written to LOG_PATH via PP.pp
-#
-# The log destination is read from XYZZY_LOG_PATH at load time and frozen
-# into a constant. Set it BEFORE requiring this file to redirect the log;
-# there is deliberately no writer method, so the constant stays shareable.
-#
-# Usage (from any example that requires common):
-#   ENV["XYZZY_LOG_PATH"] = "/tmp/xyzzy.log"   # optional, must precede require
-#   require_relative "xyzzy"
-
-require "pp"
-require "fileutils"
-
-module RobotLab
-  class Xyzzy < Hook
-    self.namespace = :xyzzy
-
-    LOG_PATH = File.expand_path(
-      ENV.fetch("XYZZY_LOG_PATH", "~/.robot_lab/xyzzy_hooks.log")
-    ).freeze
-    FileUtils.mkdir_p(File.dirname(LOG_PATH))
-
-    class << self
-      def before_run(ctx)               = log_hook(:before_run, ctx)
-      def after_run(ctx)                = log_hook(:after_run, ctx)
-      def on_error(ctx)                 = log_hook(:on_error, ctx)
-      def before_llm_generation(ctx)    = log_hook(:before_llm_generation, ctx)
-      def after_llm_generation(ctx)     = log_hook(:after_llm_generation, ctx)
-      def before_tool_call(ctx)         = log_hook(:before_tool_call, ctx)
-      def after_tool_call(ctx)          = log_hook(:after_tool_call, ctx)
-      def before_network_run(ctx)       = log_hook(:before_network_run, ctx)
-      def after_network_run(ctx)        = log_hook(:after_network_run, ctx)
-      def before_task(ctx)              = log_hook(:before_task, ctx)
-      def after_task(ctx)               = log_hook(:after_task, ctx)
-
-      def around_run(ctx, &block)
-        log_hook(:around_run, ctx)
-        block.call
-      end
-
-      def around_llm_generation(ctx, &block)
-        log_hook(:around_llm_generation, ctx)
-        block.call
-      end
-
-      def around_tool_call(ctx, &block)
-        log_hook(:around_tool_call, ctx)
-        block.call
-      end
-
-      def around_network_run(ctx, &block)
-        log_hook(:around_network_run, ctx)
-        block.call
-      end
-
-      def around_task(ctx, &block)
-        log_hook(:around_task, ctx)
-        block.call
-      end
-
-      private
-
-      def log_hook(hook_name, ctx)
-        ts       = Time.now.strftime('%H:%M:%S.%3N')
-        snapshot = context_snapshot(ctx)
-        $stdout.puts "  [xyzzy] #{ts} #{hook_name}"
-        File.open(LOG_PATH, "a") { |f| f.puts "#{ts} #{hook_name} | #{PP.pp(snapshot, +"").chomp}" }
-      end
-
-      def context_snapshot(ctx)
-        {
-          robot:   ctx.respond_to?(:robot)   ? ctx.robot&.name    : nil,
-          request: ctx.respond_to?(:request) ? ctx.request        : nil,
-          network: ctx.respond_to?(:network) ? ctx.network&.name  : nil,
-          task:    ctx.respond_to?(:task)    ? ctx.task           : nil,
-          error:   ctx.respond_to?(:error)   ? ctx.error&.message : nil
-        }.compact
-      end
-    end
-  end
-end
-
-RobotLab.register_extension(:xyzzy, RobotLab::Xyzzy) if RobotLab.respond_to?(:register_extension)
-RobotLab.on(RobotLab::Xyzzy)

data/lib/robot_lab/mcp/client.rb

@@ -1,223 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    # MCP client for communicating with Model Context Protocol servers
-    #
-    # Uses actionmcp gem for MCP protocol implementation.
-    # Supports multiple transport types: StdIO, SSE, WebSocket, HTTP.
-    #
-    # @example
-    #   client = Client.new(name: "neon", transport: { type: "ws", url: "ws://..." })
-    #   client.connect
-    #   tools = client.list_tools
-    #   result = client.call_tool("createBranch", { project_id: "abc" })
-    #
-    # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every public operation must check it.
-    class Client
-      # @!attribute [r] server
-      #   @return [Server] the MCP server configuration
-      # @!attribute [r] connected
-      #   @return [Boolean] whether currently connected
-      attr_reader :server, :connected, :transport
-
-      # Creates a new MCP Client instance.
-      #
-      # @param server_or_config [Server, Hash] the server or configuration hash
-      # @param poller [MCP::ConnectionPoller, nil] optional shared IO.select poller
-      #   for multiplexing multiple stdio transports (opt-in, default nil = per-client blocking)
-      # @raise [ArgumentError] if config is invalid
-      def initialize(server_or_config, poller: nil)
-        @server = case server_or_config
-                  when Server
-                    server_or_config
-                  when Hash
-                    Server.new(**server_or_config.transform_keys(&:to_sym))
-                  else
-                    raise ArgumentError, "Invalid server config"
-                  end
-        @connected  = false
-        @transport  = nil
-        @request_id = 0
-        @poller     = poller
-      end
-
-      # Connect to the MCP server
-      #
-      # @return [self]
-      #
-      # :reek:TooManyStatements -- linear connect/register sequence with a best-effort rescue.
-      def connect
-        return self if @connected
-
-        @transport = create_transport
-        @transport.connect if @transport.respond_to?(:connect)
-        @connected = true
-
-        # Register with shared poller after the transport is connected
-        @poller.register(self) if @poller
-
-        self
-      rescue StandardError => e
-        RobotLab.config.logger.warn("MCP connection failed for #{@server.name}: #{e.message}")
-        @connected = false
-        self
-      end
-
-      # Disconnect from the server
-      #
-      # @return [self]
-      #
-      def disconnect
-        return self unless @connected
-
-        @poller.unregister(self) if @poller
-        @transport.close if @transport.respond_to?(:close)
-        @connected = false
-        @transport = nil
-
-        self
-      end
-
-      # List available tools from the server
-      #
-      # @return [Array<Hash>] Tool definitions
-      #
-      def list_tools
-        ensure_connected!
-        response = request(method: "tools/list")
-        response[:tools] || []
-      end
-
-      # Call a tool on the server
-      #
-      # @param name [String] Tool name
-      # @param arguments [Hash] Tool arguments
-      # @return [Object] Tool result
-      #
-      def call_tool(name, arguments = {})
-        ensure_connected!
-        response = request(
-          method: "tools/call",
-          params: { name: name, arguments: arguments }
-        )
-        response[:content] || response
-      end
-
-      # List available resources
-      #
-      # @return [Array<Hash>]
-      #
-      def list_resources
-        ensure_connected!
-        response = request(method: "resources/list")
-        response[:resources] || []
-      end
-
-      # Read a resource
-      #
-      # @param uri [String] Resource URI
-      # @return [Object]
-      #
-      def read_resource(uri)
-        ensure_connected!
-        response = request(method: "resources/read", params: { uri: uri })
-        response[:contents] || response
-      end
-
-      # List available prompts
-      #
-      # @return [Array<Hash>]
-      #
-      def list_prompts
-        ensure_connected!
-        response = request(method: "prompts/list")
-        response[:prompts] || []
-      end
-
-      # Get a prompt
-      #
-      # @param name [String] Prompt name
-      # @param arguments [Hash] Prompt arguments
-      # @return [Hash]
-      #
-      def get_prompt(name, arguments = {})
-        ensure_connected!
-        request(method: "prompts/get", params: { name: name, arguments: arguments })
-      end
-
-      # Checks if the client is connected to the server.
-      #
-      # @return [Boolean]
-      def connected?
-        @connected
-      end
-
-      # Converts the client to a hash representation.
-      #
-      # @return [Hash]
-      def to_h
-        {
-          server: @server.to_h,
-          connected: @connected
-        }
-      end
-
-      private
-
-      def ensure_connected!
-        raise MCPError, "Not connected to MCP server: #{@server.name}" unless @connected
-      end
-
-      def create_transport
-        config = @server.transport.merge(timeout: @server.timeout)
-
-        case @server.transport_type
-        when "stdio"
-          Transports::Stdio.new(config)
-        when "ws", "websocket"
-          Transports::WebSocket.new(config)
-        when "sse"
-          Transports::SSE.new(config)
-        when "streamable-http", "http"
-          Transports::StreamableHTTP.new(config)
-        else
-          raise MCPError, "Unsupported transport type: #{@server.transport_type}"
-        end
-      end
-
-      def request(method:, params: nil)
-        @request_id += 1
-
-        message = {
-          jsonrpc: "2.0",
-          id: @request_id,
-          method: method
-        }
-        message[:params] = params if params
-
-        response = if @poller && @transport.is_a?(Transports::Stdio)
-                     @poller.send_request(self, message, timeout: @server.timeout)
-                   else
-                     @transport.send_request(message)
-                   end
-
-        parse_response(response)
-      end
-
-      def parse_response(response)
-        case response
-        when String
-          parsed = JSON.parse(response, symbolize_names: true)
-          parsed[:result] || parsed
-        when Hash
-          response[:result] || response
-        else
-          response
-        end
-      rescue JSON::ParserError
-        { raw: response }
-      end
-    end
-  end
-end

data/lib/robot_lab/mcp/connection_poller.rb

@@ -1,195 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    # Multiplexes I/O across multiple stdio MCP transports.
-    #
-    # When a robot connects to more than one local (stdio) MCP server,
-    # the default approach blocks independently per client, each with its
-    # own Timeout.timeout wrapper. ConnectionPoller replaces this with a
-    # single IO.select call across all registered stdout file descriptors,
-    # dispatching each response to the pending request for that client.
-    #
-    # Async-based transports (SSE, WebSocket, StreamableHTTP) are
-    # unaffected — they already use the Async fiber scheduler.
-    #
-    # == Usage
-    #
-    #   poller = MCP::ConnectionPoller.new.start
-    #   client = MCP::Client.new(server_config, poller: poller)
-    #   client.connect     # registers transport with poller
-    #   client.call_tool(…)
-    #   poller.stop
-    #
-    # @api private
-    class ConnectionPoller
-      POLL_INTERVAL = 0.1  # seconds between IO.select checks
-
-      # Creates a new ConnectionPoller.
-      def initialize
-        @mutex    = Mutex.new
-        @clients  = {}    # IO => { client:, queue: Thread::Queue }
-        @running  = false
-        @thread   = nil
-      end
-
-      # Start the multiplexing thread.
-      #
-      # @return [self]
-      def start
-        @mutex.synchronize do
-          return self if @running
-
-          @running = true
-          @thread  = Thread.new { poll_loop }
-          @thread.name = "RobotLab::MCP::ConnectionPoller"
-        end
-        self
-      end
-
-      # Stop the multiplexing thread.
-      #
-      # Cancels all pending requests with an MCPError.
-      #
-      # @param timeout [Numeric] seconds to wait for thread to finish
-      # @return [self]
-      def stop(timeout: 5)
-        @mutex.synchronize do
-          return self unless @running
-
-          @running = false
-
-          # Unblock any pending request queues
-          @clients.each_value do |entry|
-            entry[:queue]&.push({ error: "ConnectionPoller stopped" })
-          end
-        end
-
-        @thread&.join(timeout)
-        @thread = nil
-        self
-      end
-
-      # Register an MCP client with the poller.
-      #
-      # Only stdio clients are registered — others are silently ignored.
-      #
-      # @param client [MCP::Client]
-      # @return [void]
-      def register(client)
-        return unless stdio_client?(client)
-
-        io = client.transport.stdout
-        @mutex.synchronize { @clients[io] = { client: client, queue: nil } }
-      end
-
-      # Unregister a client.
-      #
-      # @param client [MCP::Client]
-      # @return [void]
-      def unregister(client)
-        return unless stdio_client?(client)
-
-        io = client.transport.stdout
-        @mutex.synchronize { @clients.delete(io) }
-      end
-
-      # Send a JSON-RPC request via the poller and block until the response.
-      #
-      # Writes to the client's stdin, registers a response queue, then
-      # blocks until the poll loop dispatches the response.
-      #
-      # @param client  [MCP::Client]
-      # @param message [Hash] JSON-RPC message
-      # @param timeout [Numeric] seconds before raising MCPError
-      # @return [Hash] parsed response
-      # @raise [MCPError] on timeout or connection error
-      # :reek:TooManyStatements -- register/write/wait/cleanup must stay in one method so ensure releases the queue.
-      # :reek:DuplicateMethodCall -- the repeated @mutex.synchronize/@clients[io] pairs are deliberately separate short critical
-      #   sections; holding the lock across the blocking write/wait would deadlock the poll loop.
-      def send_request(client, message, timeout:)
-        transport = client.transport
-        io        = transport.stdout
-        stdin     = transport.stdin
-        queue     = Thread::Queue.new
-
-        @mutex.synchronize { @clients[io][:queue] = queue }
-
-        begin
-          stdin.puts(message.to_json)
-          stdin.flush
-        rescue Errno::EPIPE, IOError => e
-          @mutex.synchronize { @clients[io][:queue] = nil }
-          raise MCPError.new("MCP connection lost: #{e.message}", retryable: true)
-        end
-
-        response = Timeout.timeout(timeout) { queue.pop }
-
-        if response.is_a?(Hash) && response[:error]
-          raise MCPError, response[:error]
-        end
-
-        response
-      rescue Timeout::Error
-        @mutex.synchronize { @clients[io]&.[]= :queue, nil }
-        raise MCPError.new("MCP server did not respond within #{timeout}s", retryable: true)
-      ensure
-        @mutex.synchronize { @clients[io]&.[]= :queue, nil }
-      end
-
-      # Whether the poller thread is running.
-      #
-      # @return [Boolean]
-      def running?
-        @mutex.synchronize { @running }
-      end
-
-      private
-
-      def poll_loop
-        loop do
-          ios = @mutex.synchronize { @clients.keys.reject(&:closed?) }
-
-          if ios.empty?
-            sleep POLL_INTERVAL
-          else
-            begin
-              ready, = IO.select(ios, nil, nil, POLL_INTERVAL)
-              dispatch(ready) if ready
-            rescue Errno::EBADF
-              # A pipe was closed between the reject and IO.select — harmless, loop again
-            end
-          end
-
-          break unless @mutex.synchronize { @running }
-        end
-      end
-
-      # :reek:TooManyStatements -- read/parse/filter/route steps for each readable IO; each guard skips a non-response line.
-      def dispatch(readable_ios)
-        readable_ios.each do |io|
-          line = io.gets rescue nil
-          next unless line
-
-          parsed = JSON.parse(line, symbolize_names: true) rescue nil
-          next unless parsed
-
-          # Skip notifications (method present, no id)
-          next if parsed[:method] && !parsed.key?(:id)
-
-          entry = @mutex.synchronize { @clients[io] }
-          entry[:queue]&.push(parsed)
-        end
-      end
-
-      def stdio_client?(client)
-        return false unless client.respond_to?(:transport)
-
-        transport = client.transport
-        transport.is_a?(Transports::Stdio) &&
-          transport.respond_to?(:stdout) &&
-          !transport.stdout.nil?
-      end
-    end
-  end
-end

data/lib/robot_lab/mcp/transports/base.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    module Transports
-      # Base class for MCP transports
-      #
-      # @abstract Subclass and implement {#connect}, {#send_request}, {#close}
-      #
-      class Base
-        # Default timeout for request operations (in seconds)
-        DEFAULT_TIMEOUT = 15
-
-        # @!attribute [r] config
-        #   @return [Hash] the transport configuration
-        # @!attribute [r] timeout
-        #   @return [Numeric] request timeout in seconds
-        attr_reader :config, :timeout
-
-        # Creates a new transport instance.
-        #
-        # @param config [Hash] transport configuration options.
-        #   May include a :timeout key (in seconds) that controls how long
-        #   blocking operations wait before raising an error.
-        def initialize(config)
-          @config = config.transform_keys(&:to_sym)
-          @timeout = @config.delete(:timeout) || DEFAULT_TIMEOUT
-        end
-
-        # Connect to the server
-        #
-        # @return [self]
-        #
-        def connect
-          raise NotImplementedError
-        end
-
-        # Send a JSON-RPC request
-        #
-        # @param message [Hash] JSON-RPC message
-        # @return [Hash] Response
-        #
-        def send_request(message)
-          raise NotImplementedError
-        end
-
-        # Close the connection
-        #
-        # @return [self]
-        #
-        def close
-          raise NotImplementedError
-        end
-
-        # Check if the transport is connected.
-        #
-        # @return [Boolean] true if connected
-        def connected?
-          false
-        end
-      end
-    end
-  end
-end

data/lib/robot_lab/mcp/transports/sse.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    module Transports
-      # Server-Sent Events transport for MCP servers
-      #
-      # Uses async-http for SSE streaming.
-      #
-      # @example
-      #   transport = SSE.new(url: "http://localhost:8080/sse")
-      #
-      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
-      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
-      class SSE < Base
-        # Creates a new SSE transport.
-        #
-        # @param config [Hash] transport configuration
-        # @option config [String] :url SSE server URL
-        def initialize(config)
-          super
-          @client = nil
-          @connected = false
-          @event_queue = []
-        end
-
-        # Connect to the MCP server via SSE.
-        #
-        # @return [self]
-        # @raise [MCPError] if async-http gem is not available
-        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
-        def connect
-          return self if @connected
-
-          require "async"
-          require "async/http/client"
-          require "async/http/endpoint"
-
-          url = @config[:url]
-
-          Async do
-            endpoint = Async::HTTP::Endpoint.parse(url)
-            @client = Async::HTTP::Client.new(endpoint)
-            @connected = true
-
-            # Initialize MCP protocol
-            send_initialize
-          end
-
-          self
-        rescue LoadError => e
-          raise MCPError, "async-http gem required for SSE transport: #{e.message}"
-        end
-
-        # Send a JSON-RPC request to the MCP server.
-        #
-        # @param message [Hash] JSON-RPC message
-        # @return [Hash] the response
-        # @raise [MCPError] if not connected
-        def send_request(message)
-          raise MCPError, "Not connected" unless @connected
-
-          require "async"
-          require "async/http/body/writable"
-
-          Async do
-            # POST the request
-            response = @client.post(
-              @config[:url],
-              { "Content-Type" => "application/json" },
-              [message.to_json]
-            )
-
-            # Read response
-            body = response.read
-            JSON.parse(body, symbolize_names: true)
-          end.wait
-        end
-
-        # Close the SSE connection.
-        #
-        # @return [self]
-        def close
-          return self unless @connected
-
-          @client&.close
-          @connected = false
-          @client = nil
-
-          self
-        end
-
-        # Check if the transport is connected.
-        #
-        # @return [Boolean] true if connected
-        def connected?
-          @connected
-        end
-
-        private
-
-        def send_initialize
-          send_request(
-            jsonrpc: "2.0",
-            id: 0,
-            method: "initialize",
-            params: {
-              protocolVersion: "2024-11-05",
-              capabilities: {},
-              clientInfo: {
-                name: "RobotLab",
-                version: RobotLab::VERSION
-              }
-            }
-          )
-        end
-      end
-    end
-  end
-end