legate 0.1.0

data/lib/legate/tool_context.rb

@@ -0,0 +1,350 @@
+# File: lib/legate/tool_context.rb
+# frozen_string_literal: true
+
+module Legate
+  # Provides contextual information to Legate::Tool#perform_execution
+  # Includes session details and a reference to the agent's tool registry.
+  # Read-only.
+  class ToolContext
+    attr_reader :session_id, :user_id, :app_name, :tool_registry, :session_service, :logger, :invocation_id
+
+    # Expose pending state delta for inspection but not direct modification
+    attr_reader :pending_state_delta
+
+    # Agent-specific authentication configuration
+    # @return [Hash, nil] The agent's auth config or nil if not configured
+    attr_reader :agent_auth_config
+
+    # @param session_id [String] The ID of the current session.
+    # @param user_id [String] The user ID associated with the session.
+    # @param app_name [String] The application/agent name associated with the session.
+    # @param tool_registry [Legate::ToolRegistry] The tool registry instance of the agent executing the tool.
+    # @param session_service [Legate::SessionService::Base, nil] The session service instance.
+    # @param logger [Logger, nil] The logger instance.
+    # @param invocation_id [String, nil] The ID of the current agent invocation.
+    # @param agent_auth_config [Hash, nil] Agent-specific authentication configuration.
+    def initialize(session_id:, user_id:, app_name:, tool_registry: nil, session_service: nil, logger: Legate.logger, invocation_id: nil, agent_auth_config: nil)
+      @session_id = session_id
+      @user_id = user_id
+      @app_name = app_name
+      @tool_registry = tool_registry
+      @session_service = session_service
+      @invocation_id = invocation_id
+      @pending_state_delta = {}
+      @token_manager = nil
+      @agent_auth_config = agent_auth_config
+    end
+
+    # Retrieves a value from the session state via the session_service.
+    # @param key [Symbol, String] The key to retrieve
+    # @return [Object, nil] The value or nil if not found
+    def state_get(key)
+      unless @session_service
+        Legate.logger.warn { '[ToolContext] state_get called but no session_service available.' }
+        return nil
+      end
+
+      Legate.logger.debug { "[ToolContext] state_get for key: #{key} in session: #{@session_id}" }
+      @session_service.get_state(session_id: @session_id, key: key)
+    rescue StandardError => e
+      Legate.logger.error { "[ToolContext] Error in state_get for key '#{key}': #{e.message}" }
+      nil
+    end
+
+    # Sets a value in the pending state delta for this context.
+    # @param key [Symbol, String] The key to set
+    # @param value [Object] The value to store (should be serializable)
+    def state_set(key, value)
+      Legate.logger.debug { "[ToolContext] state_set for key: #{key} to value: #{value.inspect} (pending)" }
+      @pending_state_delta[key.to_sym] = value
+    end
+
+    # Merges a hash into the pending state delta for this context.
+    # @param hash_to_merge [Hash] The hash to merge into the pending state delta
+    def state_update(hash_to_merge)
+      unless hash_to_merge.is_a?(Hash)
+        Legate.logger.warn { "[ToolContext] state_update called with non-hash: #{hash_to_merge.class}" }
+        return
+      end
+
+      Legate.logger.debug { "[ToolContext] state_update with hash: #{hash_to_merge.inspect} (pending)" }
+      @pending_state_delta.merge!(hash_to_merge.transform_keys(&:to_sym))
+    end
+
+    # Clears any accumulated pending state changes within this context instance.
+    def clear_pending_state_delta!
+      @pending_state_delta = {}
+    end
+
+    # Authentication-related methods
+
+    # Apply authentication to a request using the specified scheme and credential
+    # @param request [Hash] The request to authenticate
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme to use
+    # @param credential [Legate::Auth::Credential] The credential to use
+    # @return [Hash] The authenticated request
+    def authenticate_request(request, scheme, credential)
+      require_relative 'auth/tool_integration'
+
+      # Try to use token manager if available
+      token_manager = get_token_manager
+      if token_manager
+        # First get the token from token manager
+        token = token_manager.get_token(scheme, credential, force_refresh: false)
+
+        # Then apply authentication
+        return Legate::Auth::ToolIntegration.apply_authentication(
+          request,
+          scheme,
+          credential,
+          nil,
+          token_manager
+        )
+      end
+
+      # Fall back to token store if token manager not available
+      token_store = get_token_store
+
+      # Apply authentication
+      Legate::Auth::ToolIntegration.apply_authentication(request, scheme, credential, token_store)
+    end
+
+    # Check if a response indicates an authentication error
+    # @param response [Hash] The response to check
+    # @return [Boolean] True if the response indicates an authentication error
+    def authentication_error?(response)
+      require_relative 'auth/tool_integration'
+      Legate::Auth::ToolIntegration.authentication_error?(response)
+    end
+
+    # Check if a request likely requires authentication
+    # @param request [Hash] The request to check
+    # @return [Boolean] True if the request likely requires authentication
+    def requires_authentication?(request)
+      require_relative 'auth/tool_integration'
+      Legate::Auth::ToolIntegration.requires_authentication?(request)
+    end
+
+    # Get an authentication token from the session cache
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme
+    # @param credential [Legate::Auth::Credential] The credential
+    # @param force_refresh [Boolean] Whether to force a token refresh
+    # @return [Legate::Auth::ExchangedCredential, nil] The token if available
+    def get_token(scheme, credential, force_refresh: false)
+      # Try to use token manager if available
+      token_manager = get_token_manager
+      return token_manager.get_token(scheme, credential, force_refresh: force_refresh) if token_manager
+
+      # Fall back to old mechanism if token manager not available
+      token_store = get_token_store
+      return nil unless token_store
+
+      require_relative 'auth/tool_integration'
+      cache_key = Legate::Auth::ToolIntegration.generate_cache_key(scheme, credential)
+      token_store.get(cache_key)
+    end
+
+    # Refresh an authentication token
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme
+    # @param credential [Legate::Auth::Credential] The credential
+    # @param token [Legate::Auth::ExchangedCredential, nil] The current token, if available
+    # @return [Legate::Auth::ExchangedCredential, nil] The refreshed token if successful
+    def refresh_token(scheme, credential, token = nil)
+      # Try to use token manager if available
+      token_manager = get_token_manager
+      return token_manager.refresh_token(scheme, credential, token) if token_manager
+
+      # Fall back to direct refresh if token manager not available
+      if token && scheme.supports_refresh? && token.refreshable?
+        begin
+          refreshed = scheme.refresh_token(token, credential)
+          store_token(scheme, credential, refreshed)
+          return refreshed
+        rescue Legate::Auth::TokenRefreshError => e
+          Legate.logger.error("Failed to refresh token: #{e.message}")
+          return nil
+        end
+      end
+
+      nil
+    end
+
+    # Store an authentication token in the session cache
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme
+    # @param credential [Legate::Auth::Credential] The credential
+    # @param token [Legate::Auth::ExchangedCredential] The token to cache
+    # @return [Boolean] True if the token was stored successfully
+    def store_token(scheme, credential, token)
+      token_store = get_token_store
+      return false unless token_store
+
+      require_relative 'auth/tool_integration'
+      cache_key = Legate::Auth::ToolIntegration.generate_cache_key(scheme, credential)
+      token_store.store(cache_key, token)
+      true
+    end
+
+    # Clear a cached authentication token
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme
+    # @param credential [Legate::Auth::Credential] The credential
+    # @return [Boolean] True if the token was cleared successfully
+    def clear_token(scheme, credential)
+      token_store = get_token_store
+      return false unless token_store
+
+      require_relative 'auth/tool_integration'
+      cache_key = Legate::Auth::ToolIntegration.generate_cache_key(scheme, credential)
+      token_store.clear(cache_key)
+      true
+    end
+
+    # Revoke a token with the authentication provider
+    # @param scheme [Legate::Auth::Scheme] The authentication scheme
+    # @param credential [Legate::Auth::Credential] The credential
+    # @param token [Legate::Auth::ExchangedCredential] The token to revoke
+    # @return [Boolean] True if the token was revoked successfully
+    def revoke_token(scheme, credential, token)
+      # Try to use token manager if available
+      token_manager = get_token_manager
+      return token_manager.revoke_token(scheme, credential, token) if token_manager
+
+      # Fall back to direct revocation if token manager not available
+      unless scheme.respond_to?(:revoke_token)
+        Legate.logger.warn("Scheme #{scheme.scheme_type} does not support token revocation")
+        return false
+      end
+
+      begin
+        result = scheme.revoke_token(token, credential)
+        clear_token(scheme, credential) if result
+        result
+      rescue Legate::Auth::Error => e
+        Legate.logger.error("Failed to revoke token: #{e.message}")
+        false
+      end
+    end
+
+    # Handle authentication for a request, automatically selecting the appropriate scheme and credential
+    # Checks agent-specific auth config first, then falls back to global Auth::Manager
+    # @param request [Hash] The request to authenticate
+    # @param options [Hash] Options for authentication (e.g., credential_name, scheme_type)
+    # @return [Hash] The authenticated request or the original request if authentication not possible
+    def handle_request_auth(request, options = {})
+      # Skip if request doesn't need authentication
+      return request unless requires_authentication?(request)
+
+      require_relative 'auth/manager'
+
+      begin
+        auth_manager = Legate::Auth::Manager.instance
+        scheme = nil
+        credential = nil
+
+        # First, check agent-specific URL mappings
+        if @agent_auth_config && @agent_auth_config[:url_mappings]&.any?
+          scheme, credential = find_agent_auth_for_url(request[:url], auth_manager)
+          if scheme && credential
+            Legate.logger.debug { "[ToolContext] Using agent-specific auth for URL: #{request[:url]}" }
+            return authenticate_request(request, scheme, credential)
+          end
+        end
+
+        # Fall back to global Auth::Manager lookup
+        scheme, credential = auth_manager.find_scheme_and_credential(
+          url: request[:url],
+          scheme_type: options[:scheme_type],
+          credential_name: options[:credential_name]
+        )
+
+        # Apply authentication if found
+        return authenticate_request(request, scheme, credential) if scheme && credential
+      rescue StandardError => e
+        Legate.logger.error("Error in automatic authentication: #{e.message}")
+      end
+
+      # Return the original request if no authentication applied
+      request
+    end
+
+    # Find authentication for a URL using agent-specific mappings
+    # @param url [String] The URL to find authentication for
+    # @param auth_manager [Legate::Auth::Manager] The auth manager to resolve schemes/credentials
+    # @return [Array<Legate::Auth::Scheme, Legate::Auth::Credential>, nil] The scheme and credential, or nil if not found
+    def find_agent_auth_for_url(url, auth_manager)
+      return nil unless @agent_auth_config && @agent_auth_config[:url_mappings]
+
+      @agent_auth_config[:url_mappings].each do |mapping|
+        pattern = mapping[:pattern]
+        next unless pattern
+
+        matched = if pattern.is_a?(Regexp)
+                    !!(url =~ pattern)
+                  elsif pattern.is_a?(String)
+                    if pattern.include?('*')
+                      # Convert glob pattern to regex
+                      regex = Regexp.new('^' + Regexp.escape(pattern).gsub('\\*', '.*') + '$')
+                      !!(url =~ regex)
+                    else
+                      url == pattern || url.start_with?(pattern)
+                    end
+                  else
+                    false
+                  end
+
+        next unless matched
+
+        scheme_name = mapping[:scheme_name]
+        credential_name = mapping[:credential_name]
+
+        # Resolve from Auth::Manager
+        scheme = auth_manager.get_scheme(scheme_name)
+        credential = auth_manager.get_credential(credential_name)
+
+        return [scheme, credential] if scheme && credential
+
+        Legate.logger.warn { "[ToolContext] Agent auth mapping matched but scheme '#{scheme_name}' or credential '#{credential_name}' not found in Auth::Manager" }
+      end
+
+      nil
+    end
+
+    # Create or get the token manager for this context
+    # @return [Legate::Auth::TokenManager, nil] The token manager if available
+    def get_token_manager
+      return @token_manager if @token_manager
+
+      token_store = get_token_store
+      return nil unless token_store
+
+      require_relative 'auth/token_manager'
+      @token_manager = Legate::Auth::TokenManager.new(token_store)
+    end
+
+    def to_h
+      {
+        session_id: @session_id,
+        user_id: @user_id,
+        app_name: @app_name,
+        invocation_id: @invocation_id,
+        tool_registry_object_id: @tool_registry&.object_id,
+        session_service_present: !@session_service.nil?
+      }
+    end
+
+    private
+
+    # Get the token store for caching authentication tokens
+    # @return [Legate::Auth::TokenStore, nil] The token store if available
+    def get_token_store
+      return nil unless @session_service
+
+      # TokenStore works with any session service that supports save_scoped_state/load_scoped_state
+      if @session_service.respond_to?(:save_scoped_state) && @session_service.respond_to?(:load_scoped_state)
+        require_relative 'auth/token_store'
+        return Legate::Auth::TokenStore.new(@session_service)
+      end
+
+      nil
+    end
+  end
+end

data/lib/legate/tool_loader.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Legate
+  # Responsible for discovering and loading tool definition files from the filesystem.
+  # This decouples filesystem traversal and file loading from the Agent execution logic.
+  module ToolLoader
+    # Discovers and loads tool definition files from specified paths.
+    # @param paths [Array<String>] An array of directory paths to search.
+    # @return [void]
+    def self.load_from_paths(paths)
+      return if paths.nil? || paths.empty?
+
+      Legate.logger.debug("Starting tool discovery in paths: #{paths.inspect}")
+
+      paths.each do |path|
+        absolute_dir_path = File.expand_path(path, Dir.pwd)
+
+        unless Dir.exist?(absolute_dir_path)
+          Legate.logger.warn("Tool discovery path does not exist or is not a directory: '#{path}' (resolved to '#{absolute_dir_path}'). Skipping.")
+          next
+        end
+
+        Dir.glob(File.join(absolute_dir_path, '*.rb')).each do |absolute_file_path|
+          Legate.logger.debug("Attempting to load tool file using 'require': #{absolute_file_path}")
+          # Use require instead of load to prevent re-registration issues
+          require absolute_file_path
+          Legate.logger.debug("Successfully required (or already required): #{absolute_file_path}")
+        rescue LoadError, SyntaxError => e
+          Legate.logger.error("Failed to require/eval tool file '#{absolute_file_path}': #{e.class} - #{e.message}")
+        rescue StandardError => e
+          Legate.logger.error("Error encountered while requiring/processing tool file '#{absolute_file_path}': #{e.class} - #{e.message}")
+        end
+      end
+      Legate.logger.debug('Finished tool discovery.')
+    end
+  end
+end

data/lib/legate/tool_registry.rb

@@ -0,0 +1,73 @@
+# File: lib/legate/tool_registry.rb
+# frozen_string_literal: true
+
+# require 'logger' # Not needed directly if only using Legate.logger
+
+module Legate
+  # Manages a collection of tool definitions for a specific agent instance.
+  class ToolRegistry
+    attr_reader :tools # Make tools readable
+
+    # Initialize an empty tool registry.
+    def initialize
+      @tools = {} # Stores { name_symbol => tool_class } for this instance
+    end
+
+    # Register a tool class with this registry instance.
+    # @param name [Symbol] The symbolic name of the tool.
+    # @param klass [Class] The tool class (must inherit from Legate::Tool).
+    def register(name, klass)
+      logger = Legate.logger # Get the central logger instance
+
+      unless klass < Legate::Tool
+        logger.error("ToolRegistry: Attempted to register non-tool class: #{klass.inspect} for name '#{name}'.")
+        return false
+      end
+
+      name_symbol = name.to_sym # Ensure it's a symbol
+
+      if @tools.key?(name_symbol)
+        # Use the local variable 'logger'
+        logger.warn("ToolRegistry: Tool '#{name_symbol}' is already registered in this registry. Overwriting with class #{klass}.")
+      else
+        # Use the local variable 'logger'
+        logger.info("ToolRegistry: Registering tool '#{name_symbol}' with class #{klass} in this registry.")
+      end
+      @tools[name_symbol] = klass
+      true # Indicate success
+    end
+
+    # Find a tool class by its name symbol within this registry.
+    # @param name_symbol [Symbol] The symbolic name of the tool.
+    # @return [Class, nil] The tool class or nil if not found.
+    def find_class(name_symbol)
+      found_class = @tools[name_symbol.to_sym]
+      Legate.logger.debug("[ToolRegistry #{@object_id}] find_class(#{name_symbol.inspect}): Found class in @tools: #{found_class.inspect}")
+      found_class
+    end
+
+    # Create an instance of a tool by its name symbol using the class registered here.
+    # @param name_symbol [Symbol] The symbolic name of the tool.
+    # @return [Legate::Tool, nil] An instance of the tool or nil if instantiation fails or class not found.
+    def create_instance(name_symbol)
+      klass = find_class(name_symbol)
+      Legate.logger.debug("[ToolRegistry #{@object_id}] create_instance(#{name_symbol.inspect}): Found class: #{klass.inspect}")
+      klass&.new
+    end
+
+    # Get the set of registered tool name symbols.
+    # @return [Array<Symbol>] The registered tool names.
+    def available_tool_names
+      @tools.keys
+    end
+
+    # Get a list of available tools registered in this instance with basic info.
+    # @return [Array<Hash>] An array of hashes, each with :name and :description.
+    def list_tools
+      @tools.values.map do |klass|
+        metadata = klass.tool_metadata # Get the full { name:, description:, parameters: } hash
+        metadata # Return the full hash
+      end.sort_by { |t| t[:name].to_s }
+    end
+  end # End ToolRegistry class
+end # End Legate module

data/lib/legate/tool_result.rb

@@ -0,0 +1,61 @@
+# File: lib/legate/tool_result.rb
+# frozen_string_literal: true
+
+module Legate
+  # A typed, immutable result a tool's #perform_execution may return instead of
+  # building the canonical `{ status:, result:/error_message:/job_id: }` hash by
+  # hand (R11, additive). Tool#execute normalizes it to that hash, so everything
+  # downstream is unchanged — this is purely an authoring convenience.
+  #
+  #   def perform_execution(params, _context)
+  #     ToolResult.success("Hello, #{params[:name]}!")
+  #   end
+  #
+  # Pairs with the Event#answer / #success? / #error? accessors.
+  ToolResult = Data.define(:status, :result, :error_message, :job_id, :message) do
+    # @return [ToolResult] a successful result carrying an optional value
+    def self.success(value = nil)
+      new(status: :success, result: value, error_message: nil, job_id: nil, message: nil)
+    end
+
+    # @return [ToolResult] an error result
+    def self.error(message)
+      new(status: :error, result: nil, error_message: message.to_s, job_id: nil, message: nil)
+    end
+
+    # @return [ToolResult] a pending (async) result referencing a job
+    def self.pending(job_id:, message: nil)
+      new(status: :pending, result: nil, error_message: nil, job_id: job_id, message: message)
+    end
+
+    def success?
+      status == :success
+    end
+
+    def error?
+      status == :error
+    end
+
+    def pending?
+      status == :pending
+    end
+
+    # The canonical result hash the rest of Legate speaks. Only the keys relevant
+    # to the status are included, matching what hand-built tool hashes produce.
+    # @return [Hash]
+    def to_h
+      case status
+      when :success
+        { status: :success, result: result }
+      when :error
+        { status: :error, error_message: error_message }
+      when :pending
+        out = { status: :pending, job_id: job_id }
+        out[:message] = message unless message.nil?
+        out
+      else
+        { status: status }
+      end
+    end
+  end
+end