legate 0.1.0

data/lib/legate/tools/agent_tool.rb

@@ -0,0 +1,187 @@
+# File: lib/legate/tools/agent_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative '../agent'
+# ToolRegistry is NOT needed directly by AgentTool for loading target tools
+# require_relative '../tool_registry'
+require_relative '../session'
+require_relative '../session_service/in_memory'
+require 'json'
+require 'securerandom'
+require_relative '../global_definition_registry'
+require_relative '../global_tool_manager' # Make sure this is required
+
+module Legate
+  module Tools
+    class AgentTool < Legate::Tool
+      self.explicit_tool_name = :delegate_task
+
+      tool_description 'Delegates a specified task to another agent identified by its unique name. Use this when a specific agent is better suited for the sub-task.'
+
+      parameter :target_agent_name,
+                type: :string,
+                description: 'The unique name of the agent definition to delegate the task to.',
+                required: true
+
+      parameter :task,
+                type: :string,
+                description: 'The specific task description to be executed by the target agent.',
+                required: true
+
+      parameter :use_calling_session,
+                type: :boolean,
+                description: 'If true, the target agent executes within the same session context as the caller. If false, a new isolated session is created. Defaults to false.',
+                required: false
+
+      private
+
+      def perform_execution(params, context) # context is the ToolContext of the calling agent
+        # Validate that the context has a valid tool registry
+        unless context && context.respond_to?(:tool_registry) && context.tool_registry
+          msg = 'Tool registry not found or invalid in the provided context'
+          Legate.logger.error("AgentTool: #{msg}")
+          raise Legate::ToolError, msg
+        end
+
+        target_agent_name_str = params.fetch(:target_agent_name) do
+          raise Legate::ToolArgumentError, 'Missing required parameter: target_agent_name'
+        end.to_s # Ensure it's a string for store lookup
+
+        task_to_delegate = params.fetch(:task) { raise Legate::ToolArgumentError, 'Missing required parameter: task' }
+        use_calling_session = params.fetch(:use_calling_session, false)
+
+        Legate.logger.info("AgentTool: Attempting to delegate task '#{task_to_delegate}' to agent '#{target_agent_name_str}' (Session reuse: #{use_calling_session})")
+
+        # Load definition from the GlobalDefinitionRegistry
+        agent_definition_object = Legate::GlobalDefinitionRegistry.find(target_agent_name_str.to_sym)
+
+        # If not found as AgentDefinition, try getting as hash
+        definition_hash = (Legate::GlobalDefinitionRegistry.get_definition(target_agent_name_str.to_sym) if agent_definition_object)
+
+        unless definition_hash
+          msg = "Target agent definition '#{target_agent_name_str}' could not be loaded from registry."
+          Legate.logger.error("AgentTool: #{msg}")
+          raise Legate::ToolArgumentError, msg
+        end
+
+        # Ensure we have essential fields for a valid definition
+        definition_hash = definition_hash.transform_keys(&:to_sym) if definition_hash.respond_to?(:transform_keys)
+
+        # Ensure the definition has all required fields
+        definition_hash[:name] = target_agent_name_str.to_sym unless definition_hash.key?(:name)
+        definition_hash[:description] = definition_hash[:description] || "Delegated agent #{target_agent_name_str}"
+        definition_hash[:instruction] = definition_hash[:instruction] || "Perform the delegated task: #{task_to_delegate}"
+
+        # Handle 'tools' field: parse if JSON string, convert to array of symbols
+        if definition_hash.key?(:tools)
+          tool_array = if definition_hash[:tools].is_a?(String)
+                         begin
+                           parsed = JSON.parse(definition_hash[:tools])
+                           parsed.is_a?(Array) ? parsed : []
+                         rescue JSON::ParserError
+                           Legate.logger.warn("AgentTool: Could not parse :tools JSON for agent '#{target_agent_name_str}'. Defaulting to empty tools array.")
+                           []
+                         end
+                       else
+                         Array(definition_hash[:tools])
+                       end
+
+          # Convert to symbols for the definition
+          definition_hash[:tools] = tool_array.map(&:to_sym)
+        elsif !definition_hash.key?(:tool_names) # Ensure some form of tools field exists
+          definition_hash[:tools] = []
+        end
+
+        # Handle 'mcp_servers_json' field: if present and no mcp_servers, rename
+        definition_hash[:mcp_servers] = definition_hash.delete(:mcp_servers_json) if definition_hash.key?(:mcp_servers_json) && !definition_hash.key?(:mcp_servers)
+
+        # Ensure fallback_mode is symbolized
+        definition_hash[:fallback_mode] = definition_hash[:fallback_mode].to_sym if definition_hash[:fallback_mode].is_a?(String)
+
+        # Convert hash to an Legate::AgentDefinition object
+        target_definition_object = Legate::AgentDefinition.from_hash(definition_hash)
+
+        unless target_definition_object
+          msg = "Failed to create a valid AgentDefinition object for target '#{target_agent_name_str}' from loaded hash."
+          Legate.logger.error("AgentTool: #{msg} Hash was: #{definition_hash.inspect}")
+          raise Legate::ToolError, msg # More generic error as it's post-load
+        end
+
+        Legate.logger.debug("AgentTool: Instantiating target agent '#{target_definition_object.name}' using its definition object.")
+
+        # Determine session service and session ID to use
+        delegate_session_service = nil
+        delegate_session_id = nil
+
+        if use_calling_session
+          if context.session_service
+            delegate_session_service = context.session_service
+            delegate_session_id = context.session_id
+            Legate.logger.debug("AgentTool: Reusing session service and session ID '#{delegate_session_id}' from caller.")
+          else
+            Legate.logger.warn('AgentTool: use_calling_session is true but context has no session_service. Falling back to new isolated session.')
+          end
+        end
+
+        # Fallback if reuse failed or not requested
+        unless delegate_session_service
+          delegate_session_service = Legate::SessionService::InMemory.new
+          # Create a new session
+          new_session = delegate_session_service.create_session(
+            app_name: target_definition_object.name.to_s,
+            user_id: "delegation_#{SecureRandom.hex(4)}"
+          )
+          delegate_session_id = new_session.id
+          Legate.logger.debug("AgentTool: Created new isolated session '#{delegate_session_id}' for target agent.")
+        end
+
+        # Create the ephemeral agent using its definition object
+        target_agent = Legate::Agent.new(
+          definition: target_definition_object,
+          session_service: delegate_session_service
+        )
+
+        # Check if tools are configured for this agent
+        Legate.logger.warn("AgentTool: Target agent '#{target_agent_name_str}' has no tools configured.") if target_definition_object.tool_names.empty?
+
+        # Register tools - get the class objects for each tool name and register with the agent
+        tool_names = Array(definition_hash[:tools] || definition_hash[:tool_names] || [])
+        tool_names.each do |tool_name|
+          tool_class = Legate::GlobalToolManager.find_class(tool_name.to_sym)
+          if tool_class
+            target_agent.register_tool_class(tool_class)
+            Legate.logger.debug("AgentTool: Registered tool '#{tool_name}' with target agent.")
+          else
+            Legate.logger.warn("AgentTool: Could not find tool class for '#{tool_name}' in GlobalToolManager.")
+          end
+        end
+
+        target_agent.start
+        Legate.logger.info("AgentTool: Running task '#{task_to_delegate}' on target agent '#{target_agent.name}' (Session: #{delegate_session_id})")
+
+        agent_event = target_agent.run_task(
+          session_id: delegate_session_id,
+          user_input: task_to_delegate,
+          session_service: delegate_session_service # Pass the correct service
+        )
+
+        target_result = agent_event.respond_to?(:content) ? agent_event.content : agent_event
+        Legate.logger.info("AgentTool: Target agent '#{target_agent.name}' finished task. Result: #{target_result.inspect}")
+
+        { status: :success, result: target_result }
+      rescue Legate::ToolArgumentError => e
+        Legate.logger.error("AgentTool ArgumentError: #{e.message}")
+        raise e
+      rescue Legate::ToolError => e
+        Legate.logger.error("AgentTool ToolError: #{e.message}")
+        raise e
+      rescue StandardError => e
+        msg = "AgentTool: Unexpected error during delegation to '#{target_agent_name_str}': #{e.class} - #{e.message}"
+        Legate.logger.error(msg)
+        Legate.logger.error(e.backtrace.first(5).join("\n"))
+        raise Legate::ToolError, msg
+      end # end perform_execution
+    end # End AgentTool class
+  end # End Tools module
+end # End Legate module

data/lib/legate/tools/base/http_client.rb

@@ -0,0 +1,319 @@
+# File: lib/legate/tools/base/http_client.rb
+# frozen_string_literal: true
+
+require 'excon'
+require 'json'
+require 'uri' # For URI.join
+
+# Tool errors are defined in legate/errors.rb (loaded by lib/legate.rb)
+require_relative '../../version'
+
+module Legate
+  module Tools
+    module Base
+      # Mixin module providing standardized, reusable HTTP client capabilities
+      # for Legate tools, built upon the Excon gem.
+      #
+      # Include this module in your Tool class and call `setup_http_client`
+      # in your `initialize` method.
+      #
+      # It offers helper methods (http_get, http_head, http_post, etc.) for common requests,
+      # handles base URL joining, JSON encoding/decoding (optional), logging,
+      # and wraps Excon errors into standardized Legate::ToolError subclasses.
+      module HttpClient
+        # Custom instrumentor that only logs errors
+        class QuietInstrumentor < Excon::StandardInstrumentor
+          def instrument(name, params = {})
+            # Only log if there's an error
+            Legate.logger.error("[#{name}] #{params[:error]}") if params[:error]
+            yield if block_given?
+          end
+        end
+
+        attr_reader :http_client, :http_base_url
+
+        # Make request helpers public API for tools including this module
+
+        def http_get(path, query: {}, headers: {}, options: {})
+          make_request(:get, path, query: query, headers: headers, options: options)
+        end
+
+        def http_head(path, query: {}, headers: {}, options: {})
+          make_request(:head, path, query: query, headers: headers, options: options)
+        end
+
+        def http_post(path, body: nil, query: {}, headers: {}, options: {})
+          make_request(:post, path, body: body, query: query, headers: headers, options: options)
+        end
+
+        def http_put(path, body: nil, query: {}, headers: {}, options: {})
+          make_request(:put, path, body: body, query: query, headers: headers, options: options)
+        end
+
+        def http_delete(path, query: {}, headers: {}, options: {})
+          make_request(:delete, path, query: query, headers: headers, options: options)
+        end
+
+        protected
+
+        # Initializes the Excon HTTP client instance.
+        # Should be called by the including tool, typically in its `initialize` method.
+        # Stores the connection instance in `@http_client` and base URL in `@http_base_url`.
+        #
+        # @param base_url [String] The base URL for the API. Must be a valid URI string.
+        # @param headers [Hash] Default headers to include in every request (merged with defaults).
+        # @param options [Hash] Options passed directly to `Excon.new`. See Excon documentation for available options
+        #   (e.g., :read_timeout, :write_timeout, :connect_timeout, :persistent, :proxy, :ssl_verify_peer).
+        #   Allows overriding the default instrumentor via `:instrumentor` key.
+        # @return [void]
+        # @raise [Legate::ToolError] If the base_url is invalid or Excon initialization fails.
+        def setup_http_client(base_url:, headers: {}, options: {})
+          # Revert: base_url is required again
+          begin
+            @http_base_url = URI.parse(base_url.to_s)
+            raise URI::InvalidURIError, 'Scheme must be http or https' unless @http_base_url.is_a?(URI::HTTP) || @http_base_url.is_a?(URI::HTTPS)
+          rescue URI::InvalidURIError => e
+            raise Legate::ToolError.new("Invalid base_url provided: #{base_url} - #{e.message}", cause: e)
+          end
+
+          default_user_agent = "Legate-Ruby/#{Legate::VERSION} #{Excon::USER_AGENT}"
+          default_headers = { 'User-Agent' => default_user_agent }
+          merged_headers = default_headers.merge(headers)
+          default_options = { persistent: true, connect_timeout: 5, read_timeout: 15, write_timeout: 15,
+                              instrumentor: QuietInstrumentor.new }
+          final_options = default_options.merge(options)
+          final_options[:headers] = merged_headers unless merged_headers.empty?
+
+          # Store connection options for potential use in make_request for absolute URLs
+          @http_connection_options = final_options.dup
+
+          begin
+            log_options_for_debug = final_options.dup
+            log_options_for_debug[:headers] = '[REDACTED]' unless Legate.logger.level == Logger::DEBUG
+            Legate.logger.debug("Setting up Excon client for #{self.class.name} with base URL: #{@http_base_url}")
+            Legate.logger.debug("Excon options: #{log_options_for_debug}")
+
+            # Create connection using the (mandatory) base URL
+            @http_client = Excon.new(@http_base_url.to_s, final_options)
+
+            # Store default *request* options and headers separately
+            @http_default_request_options = final_options.reject { |k, _|
+              %i[headers instrumentor instrumentor_params].include?(k)
+            }
+            @http_default_headers = merged_headers
+          rescue Excon::Error::Socket => e
+            err_msg = "Failed to initialize Excon connection for #{self.class.name} to #{@http_base_url}: #{e.message}"
+            Legate.logger.error(err_msg)
+            @http_client = nil
+            raise Legate::ToolNetworkError.new(err_msg, cause: e)
+          rescue StandardError => e
+            err_msg = "Unexpected error initializing Excon for #{self.class.name}: #{e.class} - #{e.message}"
+            Legate.logger.error(err_msg)
+            @http_client = nil
+            raise Legate::ToolError.new(err_msg, cause: e)
+          end
+        end
+
+        # TODO: Add any private helper methods if needed
+
+        private
+
+        def resolve_target_uri(path)
+          parsed_path = URI.parse(path.to_s)
+          if parsed_path.is_a?(URI::HTTP) || parsed_path.is_a?(URI::HTTPS)
+            [parsed_path, true]
+          else
+            [URI.join(@http_base_url, path), false]
+          end
+        rescue URI::InvalidURIError => e
+          raise Legate::ToolError.new("Invalid URL or path provided: #{path} - #{e.message}", cause: e)
+        end
+
+        # Centralized method for making HTTP requests and handling common errors/wrapping.
+        def make_request(method, path, body: nil, query: {}, headers: {}, options: {})
+          # Extract SSRF protection options before merging into Excon params
+          resolved_ip = options.delete(:resolved_ip)
+          original_host = options.delete(:original_host)
+
+          # Ensure setup was called, but @http_client might not be used if path is absolute
+          unless @http_connection_options
+            raise Legate::ToolError,
+                  'HTTP client options not initialized. Call setup_http_client first.'
+          end
+          raise Legate::ToolError, 'Base URL not set properly during setup.' unless @http_base_url
+
+          request_params = @http_default_request_options.merge(options)
+          request_params[:method] = method
+
+          target_uri, is_absolute = resolve_target_uri(path)
+
+          # Path/Query setup differs slightly for absolute vs relative
+          if is_absolute
+          # For absolute URLs, the full path/query is part of target_uri
+          # We don't need to set host/scheme/port in request_params
+          # as Excon.new will use the full target_uri.to_s
+          else
+            # For relative URLs, use the persistent client and set path/query
+          end
+          request_params[:path] = target_uri.request_uri
+
+          # Merge explicit query params with any existing in the URI
+          uri_query = URI.decode_www_form(target_uri.query || '').to_h
+          final_query = uri_query.merge(query)
+          request_params[:query] = final_query unless final_query.empty?
+          # Update path if query was added/changed (remove original query part if exists)
+          request_params[:path] = target_uri.path
+
+          # 3. Merge Headers
+          request_params[:headers] = @http_default_headers.merge(headers)
+
+          # Determine if Content-Type was explicitly passed
+          custom_content_type_provided = headers.keys.any? { |k| k.to_s.casecmp('Content-Type').zero? }
+          content_type_key = request_params[:headers].keys.find { |k|
+            k.to_s.casecmp('Content-Type').zero?
+          } || 'Content-Type'
+
+          # 4. Handle Request Body and Content-Type logic
+          if body.is_a?(Hash) && %i[post put patch].include?(method)
+            # Only default to application/json if Content-Type was not explicitly provided
+            request_params[:headers][content_type_key] = 'application/json; charset=utf-8' unless custom_content_type_provided
+            # Get the final effective content type for encoding check
+            final_content_type = request_params[:headers].find { |k, _| k.to_s.casecmp('Content-Type').zero? }&.last
+
+            if final_content_type&.start_with?('application/json')
+              # ... JSON encode body ...
+              begin
+                request_params[:body] = JSON.generate(body)
+              rescue JSON::GeneratorError => e
+                # raise Legate::ToolError, "Failed to encode request body as JSON: #{e.message}" # No cause
+                # Add cause for better debugging
+                raise Legate::ToolError.new("Failed to encode request body as JSON: #{e.message}", cause: e)
+              end
+            else
+              # ... Handle Hash body with non-JSON CT ...
+              Legate.logger.warn "Sending Hash body with non-JSON Content-Type (#{final_content_type}) for #{target_uri}"
+              request_params[:body] = body
+            end
+          elsif body # Body is not a Hash (likely a String)
+            request_params[:body] = body
+            # If body is string AND Content-Type wasn't explicitly passed, remove the default one.
+            unless custom_content_type_provided
+              key_to_delete = request_params[:headers].keys.find { |k| k.to_s.casecmp('Content-Type').zero? }
+              request_params[:headers].delete(key_to_delete) if key_to_delete
+            end
+          end
+
+          # 5. Execute Request: Choose client based on absolute vs relative path
+          Legate.logger.info "Executing HTTP #{method.to_s.upcase} request to #{target_uri}"
+
+          response = nil
+          if is_absolute
+            Legate.logger.debug "Using temporary Excon client for absolute URL: #{target_uri}"
+
+            # Prepare options for the temporary Excon client instance
+            temp_client_options = @http_connection_options.reject { |k, _| k == :headers }
+            # Deep duplicate headers hash to avoid modifying the original
+            final_headers_for_new = Marshal.load(Marshal.dump(@http_connection_options[:headers] || {}))
+            # Merge the fully processed request_params[:headers] (which includes defaults and customs)
+            final_headers_for_new.merge!(request_params[:headers].transform_keys(&:to_s))
+
+            # DNS pinning: connect to pre-resolved IP to prevent DNS rebinding (TOCTOU)
+            connect_uri = target_uri
+            if resolved_ip
+              connect_uri = target_uri.dup
+              # #hostname= brackets IPv6 literals so the URI stays valid.
+              connect_uri.hostname = resolved_ip
+              host_for_tls = original_host || target_uri.host
+              final_headers_for_new['Host'] ||= host_for_tls
+              if target_uri.scheme == 'https'
+                # Use the real hostname for SNI and certificate verification even
+                # though we connect to the pinned IP (otherwise the cert check
+                # compares against the IP and every HTTPS request fails).
+                temp_client_options[:hostname] = host_for_tls
+                temp_client_options[:ssl_verify_peer_host] = host_for_tls
+              end
+            end
+
+            temp_client_options[:headers] = final_headers_for_new
+
+            temp_client = Excon.new(connect_uri.to_s, temp_client_options)
+
+            # Prepare the params for the .request call (method, body, query, etc., NO headers)
+            request_params_for_absolute = request_params.reject { |k, _| k == :headers }
+
+            Legate.logger.debug "Excon Temp Request Params (for .request call): #{request_params_for_absolute.inspect}"
+            Legate.logger.debug "Excon Temp Client Options (for .new call): #{temp_client_options.inspect}"
+            response = temp_client.request(request_params_for_absolute)
+          else
+            Legate.logger.debug "Using persistent Excon client for relative path: #{target_uri}"
+            # Use the persistent client setup with the base URL
+            raise Legate::ToolError, 'Persistent HTTP client not initialized.' unless @http_client
+
+            Legate.logger.debug "Excon Persistent Request Params: #{request_params.inspect}"
+            response = @http_client.request(request_params)
+          end
+
+          Legate.logger.info "Received HTTP response: Status #{response.status}"
+          Legate.logger.debug "Response Body: #{response.body[0..500]}..."
+
+          unless (200..299).cover?(response.status)
+            err_msg = "HTTP Error: Received status #{response.status} for #{method.to_s.upcase} #{target_uri}"
+            Legate.logger.error(err_msg)
+            raise Excon::Error::HTTPStatus.new(err_msg, nil, response)
+          end
+
+          response
+
+        # Step 7: Error Wrapping Logic
+        rescue Excon::Error::Timeout => e
+          err_msg = "Timeout during #{method.to_s.upcase} request to #{target_uri || path}: #{e.message}"
+          Legate.logger.error(err_msg)
+          raise Legate::ToolTimeoutError.new(err_msg, cause: e)
+        rescue Excon::Error::Socket => e
+          err_msg = "Network/Socket error during #{method.to_s.upcase} request to #{target_uri || path}: #{e.message}"
+          Legate.logger.error(err_msg)
+          raise Legate::ToolNetworkError.new(err_msg, cause: e)
+        rescue Excon::Error::Certificate => e
+          err_msg = "SSL Certificate error during #{method.to_s.upcase} request to #{target_uri || path}: #{e.message}"
+          Legate.logger.error(err_msg)
+          raise Legate::ToolCertificateError.new(err_msg, cause: e)
+        rescue Excon::Error::HTTPStatus => e
+          status = e.response&.status || 'N/A'
+          body_preview = e.response&.body&.slice(0, 500)
+          err_msg = "HTTP Error: Received status #{status} for #{method.to_s.upcase} #{target_uri || path}"
+          Legate.logger.error("#{err_msg} - Response Body: #{body_preview}...")
+          raise Legate::ToolHttpError.new(err_msg, response: e.response, cause: e)
+        rescue Excon::Error => e
+          status = e.respond_to?(:response) && e.response ? e.response.status : 'N/A'
+          err_msg = "Excon error during #{method.to_s.upcase} request to #{target_uri || path} (Status: #{status}): #{e.class} - #{e.message}"
+          Legate.logger.error(err_msg)
+          raise Legate::ToolError.new(err_msg, cause: e)
+        # Catch Legate::ToolError explicitly first to prevent re-wrapping
+        rescue Legate::ToolError => e
+          raise e
+        # Catch StandardError last, covering errors during setup (like URI.join, JSON.generate if not caught above)
+        rescue StandardError => e
+          # Avoid re-wrapping Legate::ToolErrors that might bubble up (e.g., from URI.join failure)
+          # raise if e.is_a?(Legate::ToolError) # Handled by the rescue above now
+
+          # Make error message generation safer but include original message
+          error_class_name = begin
+            e.class.name
+          rescue StandardError
+            'UnknownError'
+          end
+          error_message = begin
+            e.message
+          rescue StandardError
+            'No message available'
+          end
+          err_msg = "Unexpected error during #{method.to_s.upcase} request logic: #{error_class_name} - #{error_message}"
+          Legate.logger.error(err_msg)
+          # Safely log backtrace if available - REMOVED as it might cause issues with already wrapped Legate::ToolErrors
+          # Raise without cause for StandardError as it can cause issues
+          raise Legate::ToolError, err_msg
+        end
+      end
+    end
+  end
+end

data/lib/legate/tools/base/safe_url.rb

@@ -0,0 +1,56 @@
+# File: lib/legate/tools/base/safe_url.rb
+# frozen_string_literal: true
+
+require 'uri'
+require 'ipaddr'
+require_relative '../../auth/url_guard'
+require_relative '../../errors'
+
+module Legate
+  module Tools
+    module Base
+      # SSRF guard for outbound tool requests.
+      #
+      # Validates a URL and returns the IP to pin the connection to (defeating
+      # DNS-rebinding TOCTOU). It reuses the canonical {Legate::Auth::UrlGuard}
+      # block-list so tools and the auth layer can never drift out of sync, and
+      # raises a tool-appropriate {Legate::ToolArgumentError} on a bad target.
+      #
+      # Set LEGATE_ALLOW_PRIVATE_TOOL_URLS=1 to reach private/loopback hosts in
+      # development (returns no pin so the request connects directly).
+      module SafeUrl
+        module_function
+
+        # @param url [String] the target URL
+        # @return [Array(URI, String|nil)] the parsed URI and the IP to pin to
+        #   (nil when the dev bypass is active)
+        # @raise [Legate::ToolArgumentError] if the URL is not http(s), cannot be
+        #   resolved, or resolves to a restricted (loopback / private / link-local
+        #   / CGNAT / 0.0.0.0-8) address
+        def resolve!(url)
+          uri = URI.parse(url.to_s)
+          raise Legate::ToolArgumentError, "URL must use http or https: #{url}" unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+
+          return [uri, nil] if ENV['LEGATE_ALLOW_PRIVATE_TOOL_URLS']
+
+          ips = Legate::Auth::UrlGuard.resolved_ips(uri.host)
+          raise Legate::ToolArgumentError, "Could not resolve host: #{uri.host}" if ips.empty?
+
+          ips.each do |ip_str|
+            ip = IPAddr.new(ip_str)
+            next unless Legate::Auth::UrlGuard.restricted?(ip)
+
+            raise Legate::ToolArgumentError,
+                  "Blocked request to restricted network address (#{uri.host} -> #{ip_str})"
+          rescue IPAddr::InvalidAddressError
+            raise Legate::ToolArgumentError, "Invalid IP resolved for #{uri.host}: #{ip_str}"
+          end
+
+          [uri, ips.first]
+        rescue URI::InvalidURIError => e
+          raise Legate::ToolArgumentError.new("Invalid URL: #{url} - #{e.message}", cause: e)
+        end
+      end
+    end
+  end
+end

data/lib/legate/tools/base_async_job_tool.rb

@@ -0,0 +1,91 @@
+# File: lib/legate/tools/base_async_job_tool.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative '../errors'
+require 'concurrent'
+require 'securerandom'
+require 'json'
+
+module Legate
+  module Tools
+    # Abstract base class for tools that initiate asynchronous background tasks via threads.
+    class BaseAsyncJobTool < Legate::Tool
+      tool_description "Base class for tools that initiate long-running tasks via background threads. Subclasses must implement `worker_class` and `prepare_job_arguments`. Use 'check_job_status' tool to retrieve results."
+
+      # --- In-Memory Job Results Storage ---
+      class << self
+        def job_results
+          @job_results ||= Concurrent::Map.new
+        end
+      end
+
+      # Subclasses MUST override this method to return the worker class
+      # that should be executed.
+      # @return [Class] The worker class (must respond to #perform).
+      def worker_class
+        raise NotImplementedError, "#{self.class.name} must implement #worker_class"
+      end
+
+      # Subclasses MUST override this method to prepare the arguments
+      # for the worker's perform method based on the Legate tool's parameters and context.
+      # Note: Arguments must be simple types serializable to JSON (strings, numbers, bools, arrays, hashes).
+      # @param params [Hash] The validated parameters passed to the Legate tool.
+      # @param context [Legate::ToolContext] Contextual information (session_id, etc.).
+      # @return [Array] An array of arguments to be passed to the worker's perform method.
+      def prepare_job_arguments(params, context)
+        raise NotImplementedError, "#{self.class.name} must implement #prepare_job_arguments(params, context)"
+      end
+
+      # Overrides Legate::Tool#perform_execution to spawn a background thread.
+      # @param params [Hash] The validated parameters.
+      # @param context [Legate::ToolContext] The execution context.
+      # @return [Hash] { status: :pending, job_id: ... } or { status: :error, ... }
+      private def perform_execution(params, context)
+        jid = SecureRandom.uuid
+        worker = worker_class.new
+        args = prepare_job_arguments(params, context)
+
+        BaseAsyncJobTool.job_results[jid] = { 'status' => 'pending' }
+
+        Legate.logger.info("Spawning background task for worker '#{worker_class.name}' for tool '#{name}'. Job ID: #{jid}")
+        Legate.logger.debug("Job Args: #{args.inspect}")
+
+        Concurrent::Promises.future do
+          worker.perform(jid, *args)
+        rescue StandardError => e
+          BaseAsyncJobTool.job_results[jid] = { 'status' => 'error', 'error_message' => "#{e.class}: #{e.message}" }
+        end
+
+        { status: :pending, job_id: jid, message: "Job #{jid} has been submitted." }
+      end
+
+      # --- Static Helpers for Workers to Store Status/Results --- #
+
+      # Helper method for workers to call at the beginning of their perform method
+      # to indicate the job has started processing.
+      # @param jid [String] The Job ID.
+      def self.store_job_pending(jid)
+        job_results[jid] = { 'status' => 'pending' }
+        Legate.logger.debug("Stored pending status for job #{jid}")
+      end
+
+      # Helper method for workers to call upon completion to store their results.
+      # @param jid [String] The Job ID.
+      # @param result [Object] The result data.
+      def self.store_job_result(jid, result)
+        job_results[jid] = { 'status' => 'completed', 'result' => result.is_a?(String) ? result : result.to_json }
+        Legate.logger.debug("Stored successful result for job #{jid}")
+      end
+
+      # Helper method for workers to call upon failure to store error information.
+      # @param jid [String] The Job ID.
+      # @param error_message [String] The error message.
+      # @param _error_class [String] The class name of the error (kept for API compatibility).
+      def self.store_job_error(jid, error_message, _error_class = 'StandardError')
+        job_results[jid] = { 'status' => 'error', 'error_message' => error_message }
+        Legate.logger.debug("Stored error result for job #{jid}")
+      end
+    end
+  end
+end