legate 0.1.0

data/lib/legate/llm/adapter.rb

@@ -0,0 +1,69 @@
+# File: lib/legate/llm/adapter.rb
+# frozen_string_literal: true
+
+module Legate
+  # LLM provider abstraction. The planner (and code generators) talk to an
+  # Adapter rather than a specific provider client, so Legate is not hardwired to
+  # one model vendor. Gemini is the first adapter; others (OpenAI, Anthropic,
+  # Ollama, ...) implement the same interface.
+  module LLM
+    # Abstract base for LLM provider adapters.
+    class Adapter
+      # @return [Boolean] whether the adapter can make calls (e.g. an API key is
+      #   present and the client constructed successfully).
+      def available?
+        false
+      end
+
+      # The resolved model identifier, or nil if the adapter is unavailable.
+      # @return [String, nil]
+      def model_name
+        nil
+      end
+
+      # Generates a text completion for a single user prompt.
+      # @param prompt [String] the user prompt
+      # @param json [Boolean] request raw-JSON output where the provider supports it
+      # @param schema [Hash, nil] an optional response schema (provider-native
+      #   structured output) to constrain the JSON shape. Ignored by adapters
+      #   that don't support it; see {#supports_structured_output?}.
+      # @return [String, nil] the model's text output, or nil if unavailable
+      # @raise [StandardError] on a non-retryable provider error
+      def generate(prompt, json: false, schema: nil)
+        raise NotImplementedError, "#{self.class} must implement #generate"
+      end
+
+      # Whether this adapter can constrain output to a schema (structured output)
+      # via the `schema:` argument to {#generate}. When true, the planner uses it
+      # to guarantee valid plan JSON instead of parsing it out of prose. Default
+      # false (the prompt-and-parse path).
+      # @return [Boolean]
+      def supports_structured_output?
+        false
+      end
+
+      # Whether this adapter can use the provider's native function/tool-calling
+      # API. When true, the agentic loop selects its next action via
+      # {#generate_with_tools} (structured, reliable) instead of parsing JSON out
+      # of prose; when false it falls back to the JSON-prompt path. Default false.
+      # @return [Boolean]
+      def supports_function_calling?
+        false
+      end
+
+      # Chooses the next action with the given tool schemas available to the
+      # model, using native function calling. Only meaningful when
+      # {#supports_function_calling?} is true.
+      #
+      # @param prompt [String] instructions + context + observation transcript
+      # @param tools [Array<Hash>] each { name:, description:, parameters: <JSON Schema> }
+      # @return [Hash] a provider-neutral choice, one of:
+      #   * `{ kind: :tool,  name: String, arguments: Hash, thought: String }`
+      #   * `{ kind: :final, text: String, thought: String }`
+      # @raise [StandardError] on a non-retryable provider error
+      def generate_with_tools(prompt, tools:)
+        raise NotImplementedError, "#{self.class} must implement #generate_with_tools"
+      end
+    end
+  end
+end

data/lib/legate/llm/gemini.rb

@@ -0,0 +1,172 @@
+# File: lib/legate/llm/gemini.rb
+# frozen_string_literal: true
+
+require 'gemini-ai'
+require_relative '../gemini_ai_beta_patch' # Apply monkey patch for v1beta API
+require_relative '../redaction'
+require_relative 'adapter'
+
+module Legate
+  module LLM
+    # LLM adapter backed by the gemini-ai gem (Google Gemini, v1beta endpoint).
+    class Gemini < Adapter
+      MAX_RETRIES = 2
+      RETRY_BASE_DELAY = 1 # seconds, exponential: 1s, 2s
+
+      # @param model [String] the Gemini model id
+      # @param api_key [String, nil] defaults to ENV['GOOGLE_API_KEY'], then
+      #   ENV['GEMINI_API_KEY'] — so either env var works directly (no need to go
+      #   through Legate.load_environment for the alias).
+      # @param logger [Logger, nil] defaults to Legate.logger
+      def initialize(model:, api_key: nil, logger: nil)
+        super()
+        @model = model
+        @api_key = api_key || ENV['GOOGLE_API_KEY'] || ENV['GEMINI_API_KEY']
+        @logger = logger || Legate.logger
+        @client = build_client
+      end
+
+      def available?
+        !@client.nil?
+      end
+
+      def model_name
+        available? ? @model : nil
+      end
+
+      # @see Legate::LLM::Adapter#generate
+      def generate(prompt, json: false, schema: nil)
+        return nil unless @client
+
+        response = request_with_retry(build_text_payload(prompt, json: json, schema: schema))
+        response.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      end
+
+      # Gemini supports structured output via responseSchema on the v1beta endpoint.
+      def supports_structured_output?
+        true
+      end
+
+      # Gemini supports native function calling on the v1beta endpoint.
+      def supports_function_calling?
+        true
+      end
+
+      # @see Legate::LLM::Adapter#generate_with_tools
+      def generate_with_tools(prompt, tools:)
+        return { kind: :final, text: nil, thought: nil } unless @client
+
+        response = request_with_retry(build_tools_payload(prompt, tools))
+        parse_tool_response(response)
+      end
+
+      private
+
+      def build_text_payload(prompt, json:, schema: nil)
+        payload = { contents: [{ role: 'user', parts: { text: prompt } }] }
+        # Ask Gemini to return raw JSON (v1beta field names; the gem sends the
+        # payload through verbatim). A responseSchema additionally constrains the
+        # output to that shape (structured output) — guaranteed-valid JSON.
+        if json || schema
+          config = { responseMimeType: 'application/json' }
+          config[:responseSchema] = schema if schema
+          payload[:generationConfig] = config
+        end
+        payload
+      end
+
+      def build_tools_payload(prompt, tools)
+        {
+          contents: [{ role: 'user', parts: { text: prompt } }],
+          tools: [{ functionDeclarations: Array(tools).map { |t| function_declaration(t) } }]
+        }
+      end
+
+      # Convert a neutral tool schema { name:, description:, parameters: <JSON Schema> }
+      # into a Gemini functionDeclaration (OpenAPI subset, uppercase type names).
+      def function_declaration(tool)
+        {
+          name: tool[:name].to_s,
+          description: tool[:description].to_s,
+          parameters: to_openapi_schema(tool[:parameters])
+        }
+      end
+
+      def to_openapi_schema(schema)
+        return { type: 'OBJECT', properties: {} } unless schema.is_a?(Hash)
+
+        props = (schema[:properties] || {}).transform_values do |prop|
+          out = { type: (prop[:type] || 'string').to_s.upcase }
+          out[:description] = prop[:description].to_s if prop[:description]
+          out[:items] = { type: (prop.dig(:items, :type) || 'string').to_s.upcase } if out[:type] == 'ARRAY'
+          out
+        end
+        result = { type: 'OBJECT', properties: props }
+        required = Array(schema[:required]).map(&:to_s)
+        result[:required] = required unless required.empty?
+        result
+      end
+
+      # A functionCall part -> tool choice; otherwise the text parts -> final.
+      def parse_tool_response(response)
+        parts = response.dig('candidates', 0, 'content', 'parts') || []
+        text = parts.filter_map { |p| p['text'] }.join.strip
+        text = nil if text.empty?
+
+        call = parts.find { |p| p['functionCall'] }
+        if call
+          fc = call['functionCall']
+          return { kind: :tool, name: fc['name'].to_s, arguments: fc['args'] || {}, thought: text }
+        end
+
+        { kind: :final, text: text, thought: nil }
+      end
+
+      def build_client
+        if @api_key.nil? || @api_key.empty?
+          @logger.error('GOOGLE_API_KEY not found. The Gemini LLM adapter requires an API key.')
+          return nil
+        end
+
+        client = ::Gemini.new(
+          credentials: { service: 'generative-language-api', api_key: @api_key },
+          options: { model: @model, server_sent_events: false }
+        )
+        @logger.info("Gemini LLM adapter initialized with model: #{@model}")
+        client
+      rescue StandardError => e
+        @logger.error("Failed to initialize Gemini client (model '#{@model}'): #{e.class}: #{Legate::Redaction.redact(e.message)}")
+        @logger.error(Legate::Redaction.redact(e.backtrace.join("\n"))) if e.backtrace
+        nil
+      end
+
+      def request_with_retry(payload)
+        attempt = 0
+        begin
+          attempt += 1
+          @client.generate_content(payload)
+        rescue StandardError => e
+          if attempt <= MAX_RETRIES && retryable_error?(e)
+            delay = RETRY_BASE_DELAY * (2**(attempt - 1))
+            @logger.warn("Gemini API attempt #{attempt}/#{MAX_RETRIES + 1} failed (#{e.class}), retrying in #{delay}s...")
+            sleep(delay)
+            retry
+          end
+          # Re-raise with the API key scrubbed from the message (the gemini-ai gem
+          # embeds the full request URL, including ?key=..., in its errors).
+          raise e.class, Legate::Redaction.redact(e.message), e.backtrace
+        end
+      end
+
+      def retryable_error?(error)
+        msg = error.message.to_s
+        return true if error.is_a?(Errno::ECONNRESET) || error.is_a?(Errno::ECONNREFUSED) || error.is_a?(Errno::ETIMEDOUT)
+        return true if error.is_a?(Net::OpenTimeout) || error.is_a?(Net::ReadTimeout)
+        return true if msg.match?(/429|rate.limit/i)
+        return true if msg.match?(/^5\d{2}\b|server.error|service.unavailable|internal.server/i)
+
+        false
+      end
+    end
+  end
+end

data/lib/legate/llm/ollama.rb

@@ -0,0 +1,80 @@
+# File: lib/legate/llm/ollama.rb
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require_relative 'adapter'
+
+module Legate
+  module LLM
+    # LLM adapter backed by a local Ollama server (https://ollama.com).
+    #
+    # Talks to Ollama's /api/generate HTTP endpoint — no API key, no cost, fully
+    # local. Configure the host via the :host option or the OLLAMA_HOST env var
+    # (default http://localhost:11434). Wire it up globally with:
+    #
+    #   Legate::LLM.default_adapter_factory = lambda do |model:, **|
+    #     Legate::LLM::Ollama.new(model: model)
+    #   end
+    class Ollama < Adapter
+      DEFAULT_HOST = 'http://localhost:11434'
+
+      # @param model [String] the Ollama model tag, e.g. 'llama3' or 'qwen2.5'
+      # @param host [String, nil] base URL of the Ollama server
+      # @param logger [Logger, nil]
+      # @param read_timeout [Integer] seconds to wait for a completion (default 120)
+      def initialize(model:, host: nil, logger: nil, read_timeout: 120, **_ignored)
+        super()
+        @model = model
+        @host = (host || ENV['OLLAMA_HOST'] || DEFAULT_HOST).to_s.chomp('/')
+        @logger = logger || Legate.logger
+        @read_timeout = read_timeout
+      end
+
+      # Ollama is a local server; assume it's reachable rather than pinging it on
+      # every planner init. A real failure surfaces from #generate with a clear
+      # message.
+      def available?
+        true
+      end
+
+      def model_name
+        @model
+      end
+
+      # @see Legate::LLM::Adapter#generate
+      # `schema:` is accepted for interface parity but ignored (Ollama's
+      # `format: json` is the only structured constraint used here).
+      def generate(prompt, json: false, schema: nil) # rubocop:disable Lint/UnusedMethodArgument
+        body = { model: @model, prompt: prompt, stream: false }
+        # Ollama supports constrained JSON output via the "format" field.
+        body[:format] = 'json' if json
+
+        post_json('/api/generate', body)['response']
+      rescue StandardError => e
+        @logger.error("Ollama generate failed (#{@host}, model '#{@model}'): #{e.class}: #{e.message}")
+        raise
+      end
+
+      private
+
+      def post_json(path, body)
+        uri = URI.join("#{@host}/", path.sub(%r{\A/}, ''))
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.open_timeout = 5
+        http.read_timeout = @read_timeout
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(body)
+
+        response = http.request(request)
+        raise "Ollama HTTP #{response.code}: #{response.body.to_s[0, 300]}" unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/legate/llm.rb

@@ -0,0 +1,34 @@
+# File: lib/legate/llm.rb
+# frozen_string_literal: true
+
+require_relative 'llm/adapter'
+require_relative 'llm/gemini'
+require_relative 'llm/ollama'
+
+module Legate
+  module LLM
+    class << self
+      # A factory for the default LLM adapter, called as
+      # `factory.call(model:, api_key:, logger:)` and expected to return a
+      # Legate::LLM::Adapter. Set this to use a provider other than Gemini for
+      # every agent, e.g.:
+      #   Legate::LLM.default_adapter_factory = ->(model:, api_key:, logger:) {
+      #     MyProvider::Adapter.new(model: model, logger: logger)
+      #   }
+      # Nil means use the built-in Gemini adapter.
+      # @return [#call, nil]
+      attr_accessor :default_adapter_factory
+    end
+
+    # Builds an adapter using the configured factory, or the default Gemini
+    # adapter. Per-planner overrides take precedence over this.
+    # @return [Legate::LLM::Adapter]
+    def self.build_adapter(model:, api_key: nil, logger: nil)
+      if default_adapter_factory
+        default_adapter_factory.call(model: model, api_key: api_key, logger: logger)
+      else
+        Gemini.new(model: model, api_key: api_key, logger: logger)
+      end
+    end
+  end
+end

data/lib/legate/mcp/client.rb

@@ -0,0 +1,320 @@
+# File: lib/legate/mcp/client.rb
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'connection/stdio'
+require_relative 'connection/sse'
+require_relative '../errors'
+
+module Legate
+  module Mcp
+    class Client
+      DEFAULT_RESPONSE_TIMEOUT = 30
+      PROCESS_START_TIMEOUT = Connection::Stdio::PROCESS_START_TIMEOUT
+      # --- Define the protocol version Legate Client supports ---
+      CLIENT_PROTOCOL_VERSION = '2024-11-05'
+      # -----------------------------------------------------
+
+      attr_reader :connection_params, :server_capabilities, :last_error
+
+      # ... (initialize remains the same) ...
+      def initialize(connection_params)
+        @connection_params = connection_params
+        @connection = nil
+        @server_capabilities = nil
+        @connected = false
+        @pending_requests = {}
+        @lock = Mutex.new
+        @last_error = nil
+
+        # Validate connection params based on type
+        case @connection_params[:type]
+        when :stdio
+          raise ArgumentError, 'Missing :command for :stdio connection' unless @connection_params[:command]
+        when :sse
+          raise ArgumentError, 'Missing :url for :sse connection' unless @connection_params[:url]
+        else
+          raise ArgumentError, "Unsupported connection type: #{@connection_params[:type]}"
+        end
+      end
+
+      def connected?
+        @connected && @connection&.connected?
+      end
+
+      def connect
+        return true if connected?
+
+        error_occurred = nil
+
+        @lock.synchronize do
+          return true if @connected # Double check
+
+          Legate.logger.info('MCP Client connecting...')
+          @last_error = nil
+          @connection = nil
+          @connected = false
+
+          begin
+            case @connection_params[:type]
+            when :stdio
+              @connection = Connection::Stdio.new(
+                command: @connection_params[:command],
+                args: @connection_params[:args] || []
+              )
+            when :sse
+              # require_relative 'connection/sse' # Ensure loaded if not globally required
+              @connection = Connection::Sse.new(url: @connection_params[:url])
+            else
+              raise ConnectionError, "Cannot connect: Unsupported connection type: #{@connection_params[:type]}"
+            end
+
+            @connection.connect
+            @connected = true # Assume connected for handshake
+
+            Legate.logger.info('Performing MCP initialize handshake...')
+            id = @connection.next_request_id
+            # --- MODIFICATION: Add protocolVersion to params ---
+            request = {
+              jsonrpc: '2.0', id: id, method: 'initialize',
+              params: {
+                protocolVersion: CLIENT_PROTOCOL_VERSION,
+                clientInfo: { name: 'legate-client', version: Legate::VERSION },
+                capabilities: {} # Keep capabilities empty for now
+              }
+            }
+            # --- End Modification ---
+            Legate.logger.info("Initialize Request: #{request.inspect}") # Log modified request
+
+            response = send_request_and_wait(request, timeout: PROCESS_START_TIMEOUT)
+
+            unless response && response[:result]
+              error_msg = 'MCP Initialize failed: No response or missing result.'
+              if response&.dig(:error)
+                err = response[:error]
+                error_msg += " Server Error: #{err[:message]} (Code: #{err[:code]})"
+              elsif !response
+                error_msg += ' Connection likely closed or timed out.'
+              else
+                error_msg += " Response: #{response.inspect}"
+              end
+              @last_error = error_msg
+              raise ConnectionError, @last_error # Raise to be caught below
+            end
+
+            # --- Optional: Validate Server Protocol Version ---
+            server_protocol_version = response.dig(:result, :protocolVersion)
+            if server_protocol_version && server_protocol_version != CLIENT_PROTOCOL_VERSION
+              Legate.logger.warn("MCP Protocol version mismatch. Client: #{CLIENT_PROTOCOL_VERSION}, Server: #{server_protocol_version}")
+              # Decide if this is a critical error - for now, just log a warning
+            end
+            # --- End Protocol Version Check ---
+
+            @server_capabilities = response.dig(:result, :capabilities) || {}
+            Legate.logger.info("MCP Handshake successful. Server capabilities: #{@server_capabilities.inspect}")
+            Legate.logger.info('MCP Client connected successfully.')
+          rescue ConnectionError => e
+            Legate.logger.error("MCP Client connection/handshake failed: #{e.message}")
+            error_occurred = e
+            @connected = false
+          rescue StandardError => e
+            @last_error = "MCP Client unexpected error during connect: #{e.class} - #{e.message}"
+            Legate.logger.error("#{@last_error}\n#{e.backtrace.join("\n")}")
+            error_occurred = ConnectionError.new(@last_error)
+            @connected = false
+          end
+        end # Lock released
+
+        if error_occurred
+          disconnect
+          raise error_occurred
+        end
+
+        true
+      end
+
+      # Disconnects from the MCP server.
+      def disconnect
+        @lock.synchronize do
+          return unless @connected || @connection # Check if there's anything to disconnect
+
+          Legate.logger.info('MCP Client disconnecting...')
+          @connected = false
+          @server_capabilities = nil
+          @pending_requests.clear
+
+          begin
+            @connection&.disconnect
+          rescue StandardError => e
+            Legate.logger.error("MCP Client error during disconnect: #{e.message}")
+          end
+
+          @connection = nil
+          Legate.logger.info('MCP Client disconnected.')
+        end
+      ensure
+        # Ensure state is updated even if disconnect fails
+        @connected = false
+        @connection = nil
+      end
+
+      # Lists available tools from the MCP server.
+      # @return [Array<Hash>] List of MCP tool schemas.
+      # @raise [ConnectionError] if not connected.
+      # @raise [ProtocolError] if the server response is invalid.
+      def list_tools
+        raise ConnectionError, 'Not connected' unless connected?
+
+        Legate.logger.debug('Requesting tools list from MCP server...')
+        id = @connection.next_request_id
+        request = {
+          jsonrpc: '2.0',
+          id: id,
+          method: 'tools/list',
+          params: {}
+        }
+
+        response = send_request_and_wait(request)
+
+        if response&.key?(:result)
+          tools = response.dig(:result, :tools)
+          unless tools.is_a?(Array)
+            @last_error = "MCP tools/list invalid response: 'result.tools' is not an Array. Response: #{response.inspect}"
+            raise ProtocolError, @last_error
+          end
+          Legate.logger.debug("Received #{tools.count} tools from MCP server.")
+          tools
+        elsif response&.key?(:error)
+          err = response[:error]
+          @last_error = "MCP tools/list failed: #{err[:message]} (Code: #{err[:code]})"
+          Legate.logger.error(@last_error)
+          raise RemoteToolError.new(@last_error, err[:code], err[:data])
+        else
+          @last_error = "MCP tools/list failed: Invalid or missing response. #{response ? "Resp: #{response.inspect}" : 'Connection likely closed.'}"
+          raise ProtocolError, @last_error
+        end
+      end
+
+      # Calls a tool on the MCP server.
+      # @param name [String] The name of the tool to call.
+      # @param arguments [Hash] The arguments for the tool.
+      # @return [Any] The result payload from the tool execution.
+      # @raise [ConnectionError] if not connected.
+      # @raise [ProtocolError] if the server response is invalid.
+      # @raise [RemoteToolError] if the server returns a tool execution error.
+      def call_tool(name, arguments)
+        raise ConnectionError, 'Not connected' unless connected?
+        raise ArgumentError, 'Arguments must be a Hash' unless arguments.is_a?(Hash)
+
+        Legate.logger.debug("Calling MCP tool '#{name}' with args: #{arguments.inspect}")
+        id = @connection.next_request_id
+        request = {
+          jsonrpc: '2.0',
+          id: id,
+          method: 'tools/call',
+          params: { name: name, arguments: arguments }
+        }
+
+        response = send_request_and_wait(request)
+
+        if response&.key?(:result)
+          Legate.logger.debug("MCP tool '#{name}' call successful. Result: #{response[:result].inspect}")
+          response[:result]
+        elsif response&.key?(:error)
+          err = response[:error]
+          @last_error = "MCP tool '#{name}' call failed: #{err[:message]} (Code: #{err[:code]})"
+          Legate.logger.error("#{@last_error} Data: #{err[:data].inspect}")
+          raise RemoteToolError.new(err[:message], err[:code], err[:data])
+        else
+          @last_error = "MCP tool '#{name}' call failed: Invalid or missing response. #{response ? "Resp: #{response.inspect}" : 'Connection likely closed.'}"
+          raise ProtocolError, @last_error
+        end
+      end
+
+      # Reads the next *notification* received from the server via the connection.
+      # This is primarily useful for SSE connections.
+      # @param timeout [Numeric] Seconds to wait (default 0.1).
+      # @return [Hash, nil] Notification hash or nil.
+      def read_notification(timeout = 0.1)
+        return nil unless connected?
+
+        # Delegate to connection-specific method if it exists, otherwise return nil
+        if @connection.respond_to?(:read_notification)
+          @connection.read_notification(timeout)
+        else
+          Legate.logger.debug("Connection type #{@connection_params[:type]} does not support read_notification.")
+          nil
+        end
+      end
+
+      private
+
+      def send_request_and_wait(request, timeout: DEFAULT_RESPONSE_TIMEOUT)
+        raise ArgumentError, 'Request must have an ID' unless request[:id]
+
+        request_id = request[:id]
+        @pending_requests[request_id] = true # Mark as waiting
+
+        begin
+          # Raise connection error immediately if low-level connection is dead
+          raise ConnectionError, 'Connection is not alive.' unless @connection&.connected?
+
+          @connection.send_request(request)
+          Legate.logger.debug("Sent request ID #{request_id}, waiting for response (timeout: #{timeout}s)")
+
+          start_time = Time.now
+          message_buffer = []
+          loop do
+            # Check if the low-level connection died
+            unless @connection&.connected?
+              raise ConnectionError,
+                    "Connection lost while waiting for response ID #{request_id}"
+            end
+
+            # Check buffer first
+            message_buffer.reject! do |buffered_message|
+              if buffered_message[:id] == request_id
+                Legate.logger.debug("Found matching response for ID #{request_id} in buffer")
+                return buffered_message
+              end
+              false # Keep non-matching messages
+            end
+
+            # Calculate remaining timeout
+            elapsed_time = Time.now - start_time
+            remaining_time = timeout - elapsed_time
+            if remaining_time <= 0
+              @last_error = "MCP Client timeout waiting for response ID #{request_id}"
+              Legate.logger.error(@last_error)
+              return nil # Timeout occurred
+            end
+
+            # Read the next message using the remaining timeout
+            Legate.logger.debug("Calling read_message with timeout: #{remaining_time.round(3)}s")
+            message = @connection.read_message(remaining_time)
+
+            if message
+              Legate.logger.debug("[Client send_request_and_wait] Received message: #{JSON.pretty_generate(message)} while waiting for ID #{request_id}")
+              if message[:id] == request_id
+                Legate.logger.debug("Received matching response for ID #{request_id}")
+                return message
+              elsif message[:id]
+                Legate.logger.warn("Received unexpected response ID #{message[:id]} while waiting for #{request_id}. Buffering.")
+                message_buffer << message
+              else
+                Legate.logger.debug("Received notification or non-response message while waiting for ID #{request_id}: #{message.inspect}")
+              end
+            else
+              # read_message returned nil, indicating timeout within read_message itself
+              @last_error = "MCP Client timeout waiting for response ID #{request_id} (read_message returned nil)"
+              Legate.logger.error(@last_error)
+              return nil
+            end
+          end
+        ensure
+          @pending_requests.delete(request_id) # Clear pending status
+        end
+      end # --- End send_request_and_wait ---
+    end # End Client class
+  end # End Mcp module
+end # End Legate module