legate 0.1.0

data/lib/legate/errors.rb

@@ -0,0 +1,118 @@
+# File: lib/legate/errors.rb
+# frozen_string_literal: true
+
+# Single authoritative error hierarchy for the Legate framework.
+# All Legate error classes are defined here.
+
+module Legate
+  # Base error class for all Legate errors.
+  class Error < StandardError; end
+
+  # --- Configuration Errors ---
+
+  # Raised when a required configuration is missing or invalid.
+  class ConfigurationError < Error; end
+
+  # --- State Errors ---
+
+  # Raised when an invalid prefix is used in state keys.
+  class InvalidPrefixError < Error; end
+
+  # Raised when state value cannot be serialized.
+  class SerializationError < Error; end
+
+  # --- Tool Errors ---
+
+  # Base class for errors raised during tool execution.
+  # Supports wrapping an original cause exception for debugging.
+  class ToolError < Error
+    # @param message [String] The error message.
+    # @param cause [Exception, nil] The original exception that triggered this error.
+    def initialize(message = nil, cause: nil)
+      super(message)
+      @cause = cause
+      set_backtrace(cause.backtrace) if cause&.backtrace
+    end
+
+    # The explicit wrapped cause if one was passed, otherwise Ruby's implicit
+    # cause (set automatically when the error is raised inside a rescue). Falling
+    # back to `super` means a caller that does `raise ToolError, msg` inside a
+    # rescue still surfaces the real cause instead of nil.
+    # @return [Exception, nil] The original exception that caused this error.
+    def cause
+      @cause || super
+    end
+  end
+
+  # Raised when tool arguments are invalid (e.g., missing, wrong type).
+  class ToolArgumentError < ToolError; end
+
+  # Raised when a tool encounters a network-related issue (connection failures, DNS, SSL errors).
+  class ToolNetworkError < ToolError; end
+
+  # Raised when SSL/TLS certificate verification fails during an HTTP request.
+  class ToolCertificateError < ToolNetworkError; end
+
+  # Raised when a tool operation times out (connection, read, or write timeout).
+  class ToolTimeoutError < ToolError; end
+
+  # Raised when an HTTP request receives an unsuccessful status code (4xx or 5xx).
+  class ToolHttpError < ToolError
+    # @return [Object, nil] The HTTP response object (provides status, headers, body).
+    attr_reader :response
+
+    # @param message [String] The error message.
+    # @param response [Object, nil] The HTTP response object.
+    # @param cause [Exception, nil] The original exception.
+    def initialize(message = nil, response: nil, cause: nil)
+      super(message, cause: cause)
+      @response = response
+    end
+  end
+
+  # --- Webhook Errors ---
+
+  # Raised for webhook configuration or processing errors within the listener.
+  class WebhookConfigurationError < Error; end
+
+  # --- Storage Errors ---
+
+  # Raised for definition or session storage operation failures.
+  class StoreError < Error; end
+
+  # --- Definition Store Errors ---
+  module DefinitionStore
+    class Error < Legate::Error; end
+    class StoreError < Error; end
+  end
+
+  # --- MCP Errors ---
+  module Mcp
+    # Base class for MCP-specific errors.
+    class Error < Legate::Error; end
+
+    # Raised when an MCP connection cannot be established.
+    class ConnectionError < Error; end
+
+    # Raised for MCP protocol violations or JSON-RPC formatting errors.
+    class ProtocolError < Error; end
+
+    # Error received from a remote MCP server during a tool call.
+    class RemoteToolError < Error
+      attr_reader :code, :data
+
+      def initialize(message, code = nil, data = nil)
+        super(message)
+        @code = code
+        @data = data
+      end
+
+      def to_s
+        str = super
+        str += " (Code: #{@code})" if @code
+        str += " Data: #{@data.inspect}" if @data
+        str
+      end
+    end
+  end
+end

data/lib/legate/event.rb

@@ -0,0 +1,161 @@
+# File: lib/legate/event.rb
+# frozen_string_literal: true
+
+require 'time'
+require 'json' # Needed for serialization examples/potential
+require 'securerandom' # Required for SecureRandom
+
+module Legate
+  # Represents a single interaction or step within a Session's history.
+  # Immutable object after creation.
+  #
+  # @!attribute [r] role
+  #   @return [Symbol] The origin of the event (:user, :agent, :tool_request, :tool_result).
+  # @!attribute [r] content
+  #   @return [String, Hash] The payload of the event (e.g., user text, agent text, tool params, tool result hash).
+  # @!attribute [r] timestamp
+  #   @return [Time] The UTC time the event occurred.
+  # @!attribute [r] tool_name
+  #   @return [Symbol, nil] The name of the tool involved (for :tool_request, :tool_result roles).
+  # @!attribute [r] state_delta
+  #   @return [Hash, nil] Optional hash representing state changes associated with this event. Keys should be symbols.
+  # @!attribute [r] event_id
+  #   @return [String] A unique ID for this specific event instance.
+  Event = Struct.new(:role, :content, :timestamp, :tool_name, :state_delta, :event_id, keyword_init: true) do
+    # @param role [Symbol] :user, :agent, :tool_request, :tool_result
+    # @param content [String, Hash] Event payload. Should be JSON-serializable.
+    # @param timestamp [Time, nil] Timestamp (defaults to Time.now.utc).
+    # @param tool_name [Symbol, nil] Name of the tool if role is tool related.
+    # @param state_delta [Hash, nil] State changes to apply with this event.
+    # @param event_id [String, nil] Unique event ID (defaults to SecureRandom.uuid).
+    def initialize(role:, content:, timestamp: nil, tool_name: nil, state_delta: nil, event_id: nil)
+      # Basic validation
+      raise ArgumentError, "Invalid role: #{role}. Must be :user, :agent, :tool_request, or :tool_result." unless %i[user agent tool_request tool_result].include?(role)
+
+      Legate.logger.warn("Event: :#{role} event created without a valid :tool_name symbol.") if %i[tool_request tool_result].include?(role) && (tool_name.nil? || !tool_name.is_a?(Symbol))
+
+      # Validate state_delta is a Hash or nil
+      unless state_delta.nil? || state_delta.is_a?(Hash)
+        Legate.logger.warn("Event: :state_delta must be a Hash or nil, received #{state_delta.class}.")
+        state_delta = nil # Force to nil if invalid
+      end
+
+      # Ensure content is somewhat reasonable (avoids deep inspection for performance)
+      Legate.logger.warn("Event: Content is of unusual type (#{content.class}): #{content.inspect}") unless content.is_a?(String) || content.is_a?(Hash) || content.is_a?(Array) || content.is_a?(NilClass) || content.is_a?(Numeric) || content.is_a?(TrueClass) || content.is_a?(FalseClass)
+
+      super(
+        role: role,
+        content: deep_freeze(content),
+        timestamp: timestamp || Time.now.utc,
+        tool_name: tool_name,
+        state_delta: deep_freeze(state_delta&.transform_keys(&:to_sym)),
+        event_id: event_id || SecureRandom.uuid
+      )
+      freeze
+    end
+
+    private
+
+    def deep_freeze(obj)
+      case obj
+      when Hash
+        obj.each_value { |v| deep_freeze(v) }
+        obj.freeze
+      when Array
+        obj.each { |v| deep_freeze(v) }
+        obj.freeze
+      when String
+        obj.freeze
+      else
+        obj
+      end
+    end
+
+    public
+
+    # Helper to check if the event represents a final agent response to the user.
+    # @return [Boolean]
+    def final_agent_response?
+      role == :agent
+    end
+
+    # --- Result accessors ---
+    # Convenience readers over the standard { status:, result: / error_message: }
+    # content hash, so callers don't reach into it. Meaningful on a final agent
+    # event (e.g. the return of Agent#ask / #run_task); harmless elsewhere.
+
+    # @return [Boolean] true if this carries a successful result
+    def success?
+      content.is_a?(Hash) && content[:status] == :success
+    end
+
+    # @return [Boolean] true if this carries an error result
+    def error?
+      content.is_a?(Hash) && content[:status] == :error
+    end
+
+    # The successful result value (nil on error). Non-Hash content is returned
+    # as-is (e.g. a scalar result stored directly).
+    # @return [Object, nil]
+    def answer
+      content.is_a?(Hash) ? content[:result] : content
+    end
+
+    # @return [String, nil] the error message, or nil when not an error
+    def error_message
+      content.is_a?(Hash) ? content[:error_message] : nil
+    end
+
+    # Basic serialization for storage (e.g., in Redis).
+    # @return [Hash] A hash representation suitable for JSON conversion.
+    def to_h
+      {
+        role: role,
+        content: content, # Assumes content is already JSON-serializable
+        timestamp: timestamp.iso8601(3), # Use ISO8601 format with milliseconds
+        tool_name: tool_name,
+        state_delta: state_delta, # Store the hash directly (must be JSON-serializable)
+        event_id: event_id
+      }
+    end
+
+    # Basic deserialization from a hash (e.g., after reading from JSON).
+    # @param hash [Hash] The hash containing event data (uses symbolized keys).
+    # @return [Legate::Event] A new Event object.
+    def self.from_h(hash)
+      # Optimized: Extract fields manually to avoid full hash allocation via transform_keys
+      role = hash.key?(:role) ? hash[:role] : hash['role']
+      content = hash.key?(:content) ? hash[:content] : hash['content']
+      ts_val = hash.key?(:timestamp) ? hash[:timestamp] : hash['timestamp']
+      tool_name = hash.key?(:tool_name) ? hash[:tool_name] : hash['tool_name']
+      state_delta = hash.key?(:state_delta) ? hash[:state_delta] : hash['state_delta']
+
+      # Validate state_delta type to preserve strict behavior (fail on invalid type)
+      if state_delta && !state_delta.is_a?(Hash)
+        Legate.logger.error("Event.from_h: Type error during deserialization (check state_delta?): state_delta must be a Hash. Hash: #{hash.inspect}")
+        return nil
+      end
+
+      event_id = hash.key?(:event_id) ? hash[:event_id] : hash['event_id']
+
+      new(
+        role: role&.to_sym,
+        content: content,
+        # Safely parse timestamp
+        timestamp: ts_val ? Time.iso8601(ts_val) : Time.now.utc,
+        tool_name: tool_name&.to_sym,
+        # Pass state_delta directly; initialize handles validation and symbolization/copy
+        state_delta: state_delta,
+        event_id: event_id
+      )
+    rescue ArgumentError => e
+      Legate.logger.error("Event.from_h: Failed to parse timestamp or invalid role: #{e.message}. Hash: #{hash.inspect}")
+      # Decide on fallback: return nil, raise, or return partial object?
+      # Returning nil might be safest to signal deserialization failure.
+      nil
+    rescue TypeError, NoMethodError => e # Also rescue NoMethodError
+      Legate.logger.error("Event.from_h: Type error during deserialization (check state_delta?): #{e.message}. Hash: #{hash.inspect}")
+      nil
+    end
+  end
+end

data/lib/legate/gemini_ai_beta_patch.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Monkey patch for the gemini-ai gem to use the v1beta API endpoint, which
+# exposes newer models. It reaches into gemini-ai's private @service /
+# @service_version / @base_address ivars, so it is written defensively: if a
+# future gemini-ai release renames those internals, the patch degrades to a
+# logged warning instead of crashing planning at require time. gemini-ai is
+# pinned (~> 4.2.0) to keep this stable.
+
+require 'gemini-ai'
+
+if defined?(Gemini::Controllers::Client)
+  module Gemini
+    module Controllers
+      class Client
+        # Store the original initialize method
+        alias original_initialize initialize
+
+        def initialize(config)
+          original_initialize(config)
+
+          # Force v1beta when talking to the generative-language API. Guard the
+          # ivar pokes so a gemini-ai internals change can't break construction.
+          return unless instance_variable_defined?(:@service) && @service == 'generative-language-api'
+
+          @service_version = 'v1beta'
+          @base_address = "https://generativelanguage.googleapis.com/#{@service_version}"
+          Legate.logger&.debug('Gemini AI Client patched to use v1beta API endpoint') if defined?(Legate)
+        rescue StandardError => e
+          Legate.logger&.warn("Gemini v1beta patch could not apply (gemini-ai internals may have changed): #{e.message}") if defined?(Legate)
+        end
+      end
+    end
+  end
+
+  Legate.logger&.debug('Gemini AI Beta patch loaded - API will use v1beta endpoint') if defined?(Legate) && Legate.respond_to?(:logger)
+elsif defined?(Legate)
+  Legate.logger&.warn('Gemini::Controllers::Client not found; skipping v1beta patch (gemini-ai may have changed).')
+end