robot_lab 0.0.7 → 0.0.9

data/lib/generators/robot_lab/templates/routing_robot.rb.tt

@@ -4,50 +4,56 @@
 #
 # <%= robot_description %>
 #
-# This robot routes requests to other robots based on classification.
+# This robot classifies requests and activates optional tasks in a Network.
+# Use it as the first task in a network with optional downstream tasks:
 #
-class <%= class_name %>Robot
-  include RobotLab::Lifecycle
-
+#   classifier = <%= class_name %>Robot.build
+#   billing    = BillingRobot.build
+#   technical  = TechnicalRobot.build
+#
+#   network = RobotLab.create_network(name: "support") do
+#     task :classifier, classifier, depends_on: :none
+#     task :billing,    billing,    depends_on: :optional
+#     task :technical,  technical,  depends_on: :optional
+#   end
+#
+#   result = network.run(message: "I was charged twice")
+#
+class <%= class_name %>Robot < RobotLab::Robot
   SYSTEM_PROMPT = <<~PROMPT
-    You are a routing robot that classifies user requests and directs them
-    to the appropriate specialist robot.
+    You are a routing robot that classifies user requests.
 
-    Analyze the user's request and determine which robot should handle it.
-    Respond with your classification decision.
+    Analyze the user's request and respond with ONLY the category name.
+    Valid categories: billing, technical, general
   PROMPT
 
-  def self.build
-    RobotLab.create_routing_robot(
+  def self.build(**options)
+    new(
       name: "<%= file_name %>",
       description: "<%= robot_description %>",
-      system: SYSTEM_PROMPT,
-      on_route: method(:route_decision)
+      system_prompt: SYSTEM_PROMPT,
+      **options
     )
   end
 
-  # Determine which robot should handle the request
-  #
-  # @param result [RobotLab::RobotResult] Classification result
-  # @param robot [RobotLab::Robot] This robot
-  # @param network [RobotLab::Network] Parent network
-  # @return [Array<String>, nil] Robot names to route to
-  #
-  def self.route_decision(result:, robot:, network:)
-    # Extract classification from the result
-    output = result.output.last&.content.to_s.downcase
-
-    # Route based on classification
-    # Example routing logic:
-    # case output
-    # when /billing|payment|invoice/
-    #   ["billing_robot"]
-    # when /technical|bug|error/
-    #   ["technical_robot"]
-    # else
-    #   ["general_robot"]
-    # end
-
-    nil # Return nil to end the network run
+  # Override call to inspect classification output and activate optional tasks.
+  def call(result)
+    context = extract_run_context(result)
+    message = context.delete(:message)
+
+    robot_result = run(message, **context)
+
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+
+    category = robot_result.last_text_content.to_s.strip.downcase
+
+    # Route based on classification — customize these patterns
+    case category
+    when /billing/  then new_result.activate(:billing)
+    when /technical/ then new_result.activate(:technical)
+    else new_result.activate(:general)
+    end
   end
 end

data/lib/robot_lab/mcp/client.rb

@@ -162,15 +162,17 @@ module RobotLab
       end
 
       def create_transport
+        config = @server.transport.merge(timeout: @server.timeout)
+
         case @server.transport_type
         when "stdio"
-          Transports::Stdio.new(@server.transport)
+          Transports::Stdio.new(config)
         when "ws", "websocket"
-          Transports::WebSocket.new(@server.transport)
+          Transports::WebSocket.new(config)
         when "sse"
-          Transports::SSE.new(@server.transport)
+          Transports::SSE.new(config)
         when "streamable-http", "http"
-          Transports::StreamableHTTP.new(@server.transport)
+          Transports::StreamableHTTP.new(config)
         else
           raise MCPError, "Unsupported transport type: #{@server.transport_type}"
         end

data/lib/robot_lab/mcp/server.rb

@@ -24,20 +24,28 @@ module RobotLab
       # Valid transport types for MCP connections
       VALID_TRANSPORT_TYPES = %w[stdio sse ws websocket streamable-http http].freeze
 
+      # Default timeout for MCP requests (in seconds)
+      DEFAULT_TIMEOUT = 15
+
       # @!attribute [r] name
       #   @return [String] the server name
       # @!attribute [r] transport
       #   @return [Hash] the transport configuration
-      attr_reader :name, :transport
+      # @!attribute [r] timeout
+      #   @return [Numeric] request timeout in seconds
+      attr_reader :name, :transport, :timeout
 
       # Creates a new Server configuration.
       #
       # @param name [String] the server name
       # @param transport [Hash] the transport configuration
+      # @param timeout [Numeric, nil] request timeout in seconds (default: 15)
+      # @param _extra [Hash] additional keys are silently ignored for forward compatibility
       # @raise [ArgumentError] if transport type is invalid or required fields are missing
-      def initialize(name:, transport:)
+      def initialize(name:, transport:, timeout: nil, **_extra)
         @name = name.to_s
         @transport = normalize_transport(transport)
+        @timeout = normalize_timeout(timeout)
         validate!
       end
 
@@ -54,7 +62,8 @@ module RobotLab
       def to_h
         {
           name: name,
-          transport: transport
+          transport: transport,
+          timeout: timeout
         }
       end
 
@@ -79,6 +88,15 @@ module RobotLab
           raise ArgumentError, "Transport requires :url" unless transport[:url]
         end
       end
+
+      def normalize_timeout(value)
+        return DEFAULT_TIMEOUT if value.nil?
+
+        seconds = value.to_f
+        # If the caller passed milliseconds (>= 1000), convert to seconds
+        seconds = seconds / 1000.0 if seconds >= 1000
+        [seconds, 1].max
+      end
     end
   end
 end

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

@@ -8,15 +8,23 @@ module RobotLab
       # @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
-        attr_reader :config
+        # @!attribute [r] timeout
+        #   @return [Numeric] request timeout in seconds
+        attr_reader :config, :timeout
 
         # Creates a new transport instance.
         #
-        # @param config [Hash] transport configuration options
+        # @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

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

@@ -2,6 +2,7 @@
 
 require "open3"
 require "json"
+require "timeout"
 
 module RobotLab
   module MCP
@@ -9,12 +10,13 @@ module RobotLab
       # StdIO transport for local MCP servers
       #
       # Spawns a subprocess and communicates via stdin/stdout.
+      # All blocking I/O is wrapped with a configurable timeout
+      # so a missing or hung server cannot block the caller forever.
       #
       # @example
       #   transport = Stdio.new(
-      #     command: "mcp-server-filesystem",
-      #     args: ["--root", "/data"],
-      #     env: { "DEBUG" => "true" }
+      #     { command: "mcp-server-filesystem", args: ["--root", "/data"] },
+      #     timeout: 10
       #   )
       #
       class Stdio < Base
@@ -24,6 +26,7 @@ module RobotLab
         # @option config [String] :command the command to execute
         # @option config [Array<String>] :args command arguments
         # @option config [Hash] :env environment variables
+        # @option config [Numeric] :timeout request timeout in seconds (default: 15)
         def initialize(config)
           super
           @stdin = nil
@@ -36,7 +39,8 @@ module RobotLab
         # Connect to the MCP server via stdio.
         #
         # @return [self]
-        # @raise [MCPError] if connection fails
+        # @raise [MCPError] if the server process cannot be started or does not
+        #   respond to the MCP initialize handshake within the timeout period
         def connect
           return self if @connected
 
@@ -44,44 +48,59 @@ module RobotLab
           args = @config[:args] || []
           env = @config[:env] || {}
 
-          # Merge with current environment
           full_env = ENV.to_h.merge(env.transform_keys(&:to_s))
 
           @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(full_env, command, *args)
+
+          # Verify the process actually started
+          unless @wait_thread.alive?
+            raise MCPError, "MCP server process exited immediately (command: #{command})"
+          end
+
           @connected = true
 
-          # Initialize MCP protocol
+          # Initialize MCP protocol — this must complete within the timeout
           send_initialize
 
           self
+        rescue Errno::ENOENT => e
+          cleanup_process
+          raise MCPError, "MCP server command not found: #{command} (#{e.message})"
+        rescue Timeout::Error
+          cleanup_process
+          raise MCPError, "MCP server '#{command}' did not respond within #{@timeout}s"
         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 or no response
+        # @raise [MCPError] if not connected, no response, or timeout
         def send_request(message)
           raise MCPError, "Not connected" unless @connected
 
-          # Write JSON-RPC message
-          json = message.to_json
-          @stdin.puts(json)
-          @stdin.flush
+          Timeout.timeout(@timeout, Timeout::Error) do
+            json = message.to_json
+            @stdin.puts(json)
+            @stdin.flush
 
-          # Read response, skipping notifications
-          loop do
-            response_line = @stdout.gets
-            raise MCPError, "No response from MCP server" unless response_line
+            loop do
+              response_line = @stdout.gets
+              raise MCPError, "No response from MCP server (EOF on stdout)" unless response_line
 
-            parsed = JSON.parse(response_line, symbolize_names: true)
+              parsed = JSON.parse(response_line, symbolize_names: true)
 
-            # Skip notifications (messages without an id)
-            next if parsed[:method] && !parsed.key?(:id)
+              # Skip notifications (messages without an id)
+              next if parsed[:method] && !parsed.key?(:id)
 
-            # Return responses (messages with an id)
-            return parsed
+              return parsed
+            end
           end
+        rescue Timeout::Error
+          raise MCPError, "MCP server did not respond within #{@timeout}s"
+        rescue Errno::EPIPE, IOError => e
+          @connected = false
+          raise MCPError, "MCP server connection lost: #{e.message}"
         end
 
         # Close the connection to the MCP server.
@@ -90,12 +109,7 @@ module RobotLab
         def close
           return self unless @connected
 
-          @stdin&.close
-          @stdout&.close
-          @stderr&.close
-          @wait_thread&.kill if @wait_thread&.alive?
-
-          @connected = false
+          cleanup_process
           self
         end
 
@@ -127,6 +141,18 @@ module RobotLab
           @stdin.puts({ jsonrpc: "2.0", method: "notifications/initialized" }.to_json)
           @stdin.flush
         end
+
+        def cleanup_process
+          @connected = false
+          @stdin&.close  rescue nil
+          @stdout&.close rescue nil
+          @stderr&.close rescue nil
+          @wait_thread&.kill if @wait_thread&.alive?
+          @stdin = nil
+          @stdout = nil
+          @stderr = nil
+          @wait_thread = nil
+        end
       end
     end
   end

data/lib/robot_lab/{rails → rails_integration}/engine.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RobotLab
-  module Rails
+  module RailsIntegration
     # Rails Engine for RobotLab integration
     #
     # Provides automatic loading of RobotLab components and

data/lib/robot_lab/{rails → rails_integration}/railtie.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RobotLab
-  module Rails
+  module RailsIntegration
     # Railtie for RobotLab Rails integration
     #
     # Provides configuration hooks and initialization for

data/lib/robot_lab/rails_integration/turbo_stream_callbacks.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module RailsIntegration
+    # Stateless utility module that builds callback Procs for Turbo Stream broadcasting.
+    #
+    # Safe to require even without turbo-rails installed — checks at call time
+    # via `defined?(Turbo::StreamsChannel)`.
+    #
+    # @example Wire streaming in a background job
+    #   stream_name = "robot_lab_thread_#{thread_id}"
+    #   on_content = RobotLab::RailsIntegration::TurboStreamCallbacks.build_content_callback(
+    #     stream_name: stream_name
+    #   )
+    #   robot = MyRobot.build(on_content: on_content)
+    #   robot.run(message)
+    #
+    module TurboStreamCallbacks
+      # Check whether Turbo Streams broadcasting is available at runtime.
+      #
+      # @return [Boolean]
+      #
+      def self.available?
+        defined?(Turbo::StreamsChannel) ? true : false
+      end
+
+      # Build a Proc that broadcasts content chunks via Turbo Streams.
+      #
+      # The returned Proc receives a chunk object (e.g. RubyLLM::Chunk) and
+      # broadcasts `chunk.content` as HTML-escaped text via `broadcast_append_to`.
+      #
+      # @param stream_name [String] the Turbo Stream channel name
+      # @param target [String] the DOM target ID (default: "robot_response")
+      # @return [Proc] a callback suitable for `on_content:`
+      #
+      def self.build_content_callback(stream_name:, target: "robot_response")
+        ->(chunk) {
+          content = chunk.respond_to?(:content) ? chunk.content : chunk.to_s
+          return unless content && TurboStreamCallbacks.available?
+
+          Turbo::StreamsChannel.broadcast_append_to(
+            stream_name,
+            target: target,
+            html: ERB::Util.html_escape(content)
+          )
+        }
+      end
+
+      # Build a Proc that broadcasts tool call badges via Turbo Streams.
+      #
+      # The returned Proc receives a tool_call object and broadcasts
+      # a badge showing the tool name.
+      #
+      # @param stream_name [String] the Turbo Stream channel name
+      # @param target [String] the DOM target ID (default: "robot_tools")
+      # @return [Proc] a callback suitable for `on_tool_call:`
+      #
+      def self.build_tool_call_callback(stream_name:, target: "robot_tools")
+        ->(tool_call) {
+          return unless TurboStreamCallbacks.available?
+
+          name = tool_call.respond_to?(:name) ? tool_call.name : tool_call.to_s
+          Turbo::StreamsChannel.broadcast_append_to(
+            stream_name,
+            target: target,
+            html: "<span class=\"tool-badge\">Using: #{ERB::Util.html_escape(name)}</span>"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/mcp_management.rb

@@ -26,17 +26,22 @@ module RobotLab
       end
 
 
-      # Ensure MCP clients are initialized for the given server configs
+      # Ensure MCP clients are initialized for the given server configs.
+      # On subsequent calls, retries any servers that previously failed to connect.
       def ensure_mcp_clients(mcp_servers)
         return if mcp_servers.empty?
 
         needed_servers = mcp_servers.map { |s| s.is_a?(Hash) ? s[:name] : s.to_s }.compact
-        return if @mcp_initialized && (@mcp_clients.keys.sort == needed_servers.sort)
 
-        disconnect if @mcp_initialized
+        if @mcp_initialized
+          # Already initialized — retry any servers that are needed but not connected
+          retry_failed_servers(mcp_servers, needed_servers)
+          return
+        end
 
         @mcp_clients = {}
         @mcp_tools = []
+        @failed_mcp_configs = {}
 
         mcp_servers.each do |server_config|
           init_mcp_client(server_config)
@@ -55,8 +60,48 @@ module RobotLab
           @mcp_clients[server_name] = client
           discover_mcp_tools(client, server_name)
         else
+          server_name = extract_server_name(server_config)
+          @failed_mcp_configs[server_name] = server_config
           RobotLab.config.logger.warn(
-            "Robot '#{@name}' failed to connect to MCP server: #{server_config[:name] || server_config}"
+            "Robot '#{@name}' failed to connect to MCP server: #{server_name}"
+          )
+        end
+      rescue StandardError => e
+        server_name = extract_server_name(server_config)
+        @failed_mcp_configs[server_name] = server_config
+        RobotLab.config.logger.warn(
+          "Robot '#{@name}' error connecting to MCP server '#{server_name}': #{e.message}"
+        )
+      end
+
+
+      # Retry connecting to servers that previously failed
+      def retry_failed_servers(mcp_servers, needed_servers)
+        return if @failed_mcp_configs.nil? || @failed_mcp_configs.empty?
+
+        # Only retry servers that are still needed and still failed
+        to_retry = @failed_mcp_configs.select { |name, _| needed_servers.include?(name) }
+        return if to_retry.empty?
+
+        to_retry.each do |name, server_config|
+          RobotLab.config.logger.info(
+            "Robot '#{@name}' retrying MCP server: #{name}"
+          )
+
+          client = MCP::Client.new(server_config)
+          client.connect
+
+          if client.connected?
+            @mcp_clients[name] = client
+            @failed_mcp_configs.delete(name)
+            discover_mcp_tools(client, name)
+            RobotLab.config.logger.info(
+              "Robot '#{@name}' successfully connected to MCP server '#{name}' on retry"
+            )
+          end
+        rescue StandardError => e
+          RobotLab.config.logger.warn(
+            "Robot '#{@name}' retry failed for MCP server '#{name}': #{e.message}"
           )
         end
       end
@@ -83,6 +128,18 @@ module RobotLab
           "Robot '#{@name}' discovered #{tools.size} tools from MCP server '#{server_name}'"
         )
       end
+
+
+      def extract_server_name(server_config)
+        case server_config
+        when Hash
+          server_config[:name] || server_config['name'] || server_config.to_s
+        when MCP::Server
+          server_config.name
+        else
+          server_config.to_s
+        end
+      end
     end
   end
 end