legate 0.1.0

data/lib/legate/session_service/base.rb

@@ -0,0 +1,68 @@
+# File: lib/legate/session_service/base.rb
+# frozen_string_literal: true
+
+module Legate
+  module SessionService
+    # Base class for session services
+    class Base
+      # Returns whether this service persists state
+      # @return [Boolean] true if state is persisted, false otherwise
+      def persistent?
+        false
+      end
+
+      # Saves scoped state
+      # @param scope [String] The scope of the state ('user', 'app', or 'temp')
+      # @param key [String] The key to save
+      # @param value [Object] The value to save
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def save_scoped_state(scope, key, value)
+        raise NotImplementedError, "#{self.class} must implement #save_scoped_state"
+      end
+
+      # Loads scoped state
+      # @param scope [String] The scope of the state ('user', 'app', or 'temp')
+      # @param key [String] The key to load
+      # @return [Object, nil] The loaded value or nil if not found
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def load_scoped_state(scope, key)
+        raise NotImplementedError, "#{self.class} must implement #load_scoped_state"
+      end
+
+      # Clears scoped state
+      # @param scope [String] The scope of the state ('user', 'app', or 'temp')
+      # @param key [String] The key to clear
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def clear_scoped_state(scope, key)
+        raise NotImplementedError, "#{self.class} must implement #clear_scoped_state"
+      end
+
+      def append_event(session_id:, event:)
+        raise NotImplementedError, "#{self.class.name} must implement #append_event."
+      end
+
+      # Sets a key-value pair in the state associated with the session.
+      # This typically involves finding the session and then calling the session object's
+      # own state management methods (e.g., session.set_state(key, value)).
+      # @param session_id [String] The ID of the session.
+      # @param key [Symbol] The key for the state entry (should not have service-level prefixes like user: or app:).
+      # @param value [Object] The value to store.
+      # @return [void]
+      # @raise [NotImplementedError] If the subclass does not implement this method.
+      def set_state(session_id:, key:, value:)
+        raise NotImplementedError, "#{self.class.name} must implement #set_state."
+      end
+
+      # Retrieves a value from the state associated with the session.
+      # This typically involves finding the session and then calling the session object's
+      # own state management methods (e.g., session.get_state(key)).
+      # @param session_id [String] The ID of the session.
+      # @param key [Symbol] The key for the state entry (should not have service-level prefixes).
+      # @return [Object, nil] The value if found, or nil.
+      # @raise [NotImplementedError] If the subclass does not implement this method.
+      def get_state(session_id:, key:)
+        raise NotImplementedError, "#{self.class.name} must implement #get_state."
+      end
+    end
+  end
+end

data/lib/legate/session_service/event_broadcast.rb

@@ -0,0 +1,74 @@
+# File: lib/legate/session_service/event_broadcast.rb
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Legate
+  module SessionService
+    # Session-scoped pub/sub for streaming agent events (R3).
+    #
+    # A session service includes this mixin and calls {#broadcast_event} right
+    # after persisting an event in #append_event. Consumers (a Sinatra SSE
+    # response, a CLI, a test) {#subscribe} to a session_id and receive each
+    # event as it is appended, then {#unsubscribe} when done.
+    #
+    # Delivery is synchronous and in-order on the appending thread; a subscriber
+    # that raises is isolated (logged, never breaks persistence or other
+    # subscribers). Subscribers are keyed by session_id, so concurrent runs on
+    # different sessions never cross.
+    module EventBroadcast
+      # Guards the one-time creation of the subscriber registry. Shared across
+      # instances, but only contended on each instance's very first subscribe —
+      # negligible, and it avoids depending on the including class's #initialize.
+      INIT_LOCK = Mutex.new
+      private_constant :INIT_LOCK
+
+      # @param session_id [String]
+      # @yieldparam event [Legate::Event] each event appended to this session
+      # @return [Object] an opaque handle to pass to {#unsubscribe}
+      def subscribe(session_id, &listener)
+        raise ArgumentError, 'subscribe requires a block' unless listener
+
+        key = session_id.to_s
+        subscribers = event_subscribers.compute_if_absent(key) { Concurrent::Array.new }
+        subscribers << listener
+        [key, listener]
+      end
+
+      # Removes a subscription created by {#subscribe}. Safe to call twice / with nil.
+      # @param handle [Object] the value returned by {#subscribe}
+      def unsubscribe(handle)
+        return unless handle.is_a?(Array)
+
+        key, listener = handle
+        subscribers = event_subscribers[key]
+        return unless subscribers
+
+        subscribers.delete(listener)
+        event_subscribers.delete(key) if subscribers.empty?
+      end
+
+      # Notifies subscribers of `session_id` that `event` was appended.
+      # @return [void]
+      def broadcast_event(session_id, event)
+        subscribers = event_subscribers[session_id.to_s]
+        return if subscribers.nil? || subscribers.empty?
+
+        subscribers.each do |listener|
+          listener.call(event)
+        rescue StandardError => e
+          Legate.logger.error("EventBroadcast: subscriber raised #{e.class}: #{e.message}")
+        end
+      end
+
+      private
+
+      # Thread-safe lazy registry: the fast path is lock-free; the first caller
+      # per instance takes INIT_LOCK so concurrent first-subscribers can't each
+      # create (and orphan) a separate map.
+      def event_subscribers
+        @event_subscribers || INIT_LOCK.synchronize { @event_subscribers ||= Concurrent::Map.new }
+      end
+    end
+  end
+end

data/lib/legate/session_service/in_memory.rb

@@ -0,0 +1,188 @@
+# File: lib/legate/session_service/in_memory.rb
+# frozen_string_literal: true
+
+require 'concurrent'
+require_relative 'base'
+require_relative 'event_broadcast'
+require_relative '../session'
+require_relative '../event'
+
+module Legate
+  module SessionService
+    # Stores sessions entirely in memory. Data is lost on application restart.
+    # Useful for local development, testing, and simple use cases.
+    class InMemory < Base
+      include EventBroadcast
+
+      attr_reader :sessions, :scoped_states
+
+      def initialize
+        @sessions = Concurrent::Map.new
+        @scoped_states = Concurrent::Map.new
+        Legate.logger.info('InMemorySessionService initialized.')
+      end
+
+      def persistent?
+        false
+      end
+
+      # Creates a new session in memory.
+      # @param app_name [String] Identifier for the agent application.
+      # @param user_id [String] Identifier for the user initiating the session.
+      # @param session_id [String, nil] Optional explicit session id (defaults to a generated UUID).
+      # @param initial_state [Hash] Optional initial data for the session state.
+      # @return [Legate::Session] The newly created session object.
+      def create_session(app_name:, user_id:, session_id: nil, initial_state: {})
+        # Fix: Ensure keys are symbols before passing to Session constructor
+        symbolized_state = initial_state.transform_keys { |k|
+          begin
+            k.to_sym
+          rescue StandardError
+            k
+          end
+        }
+        session = Legate::Session.new(
+          app_name: app_name,
+          user_id: user_id,
+          id: session_id,
+          initial_state: symbolized_state,
+          session_service: self
+        )
+        @sessions[session.id] = session
+        Legate.logger.info("Created session: #{session.id} for app:#{app_name}, user:#{user_id}")
+        session
+      end
+
+      # Retrieves a session from memory by its ID.
+      # @param session_id [String] The unique ID of the session to retrieve.
+      # @return [Legate::Session, nil] The session object if found, otherwise nil.
+      def get_session(session_id:)
+        session = @sessions[session_id]
+        if session
+          Legate.logger.debug("Retrieved session: #{session_id}")
+        else
+          Legate.logger.warn("Session not found: #{session_id}")
+        end
+        session
+      end
+
+      # --- DEPRECATED ---
+      # Saves the session state (in memory this just means it's already updated).
+      # In a persistent store, this would write changes. Here, we just update the timestamp.
+      # NOTE: Events and state updates should be done via #append_event for atomicity.
+      # This method mainly exists for interface compatibility if needed but should be avoided.
+      # @param session [Legate::Session] The session object to "save".
+      # @return [Boolean] True if the session exists in memory.
+      def save_session(session:)
+        if @sessions.key?(session.id)
+          session.updated_at = Time.now.utc # Ensure timestamp reflects save attempt
+          Legate.logger.warn('InMemorySessionService#save_session called (likely unnecessary). Use append_event.')
+          true
+        else
+          Legate.logger.error("Attempted to save non-existent session: #{session.id}")
+          false
+        end
+      end
+
+      # --- REVISED METHOD ---
+      # Appends an event to a session and merges state updates from the event's state_delta.
+      # This should be the primary way to modify a session during a turn.
+      # @param session_id [String] The ID of the session to update.
+      # @param event [Legate::Event] The event to append. Must be an instance of Legate::Event.
+      # @return [Boolean] True if successful, false if session not found or event is invalid.
+      def append_event(session_id:, event:)
+        session = get_session(session_id: session_id)
+        return false unless session
+
+        session.add_event(event)
+        broadcast_event(session_id, event) # notify any streaming subscribers (R3)
+        true
+      end
+
+      # Deletes a session from memory.
+      # @param session_id [String] The ID of the session to delete.
+      # @return [Boolean] True if a session was deleted, false otherwise.
+      def delete_session(session_id:)
+        deleted_session = @sessions.delete(session_id)
+        if deleted_session
+          Legate.logger.info("Deleted session: #{session_id}")
+          true
+        else
+          Legate.logger.warn("Attempted to delete non-existent session: #{session_id}")
+          false
+        end
+      end
+
+      # Lists sessions (in this implementation, just returns all session objects).
+      # Filtering could be added later if needed.
+      # @param app_name [String, nil] Optional filter by app name.
+      # @param user_id [String, nil] Optional filter by user ID.
+      # @return [Array<Legate::Session>] An array of session objects matching filters.
+      def list_sessions(app_name: nil, user_id: nil)
+        filtered = @sessions.values # Get all session objects
+        filtered.select! { |s| s.app_name == app_name } if app_name
+        filtered.select! { |s| s.user_id == user_id } if user_id
+        Legate.logger.debug("Listing #{filtered.count} sessions.")
+        filtered
+      end
+
+      def save_scoped_state(scope, key, value)
+        state_key = "#{scope}:#{key}"
+        @scoped_states[state_key] = value
+      end
+
+      def load_scoped_state(scope, key)
+        state_key = "#{scope}:#{key}"
+        @scoped_states[state_key]
+      end
+
+      def clear_scoped_state(scope, key)
+        if key == '*'
+          # Clear all states for the given scope
+          @scoped_states.keys.each do |state_key|
+            @scoped_states.delete(state_key) if state_key.start_with?("#{scope}:")
+          end
+        else
+          state_key = "#{scope}:#{key}"
+          @scoped_states.delete(state_key)
+        end
+      end
+
+      # Sets a key-value pair in the state associated with the session.
+      # Delegates to the Legate::Session instance's set_state method.
+      # @param session_id [String] The ID of the session.
+      # @param key [Symbol] The key for the state entry.
+      # @param value [Object] The value to store.
+      # @return [void]
+      def set_state(session_id:, key:, value:)
+        session = get_session(session_id: session_id)
+        if session
+          begin
+            session.set_state(key, value) # Legate::Session#set_state handles its own logging
+          rescue Legate::SerializationError => e # Catch potential serialization errors from session.set_state
+            Legate.logger.error("InMemorySessionService: Error setting state for session '#{session_id}', key '#{key}': #{e.message}")
+            # Depending on desired behavior, could re-raise or just log
+          end
+        else
+          Legate.logger.warn("InMemorySessionService: Session not found '#{session_id}' when trying to set state for key '#{key}'.")
+        end
+        nil # Return void consistent with base
+      end
+
+      # Retrieves a value from the state associated with the session.
+      # Delegates to the Legate::Session instance's get_state method.
+      # @param session_id [String] The ID of the session.
+      # @param key [Symbol] The key for the state entry.
+      # @return [Object, nil] The value if found, or nil.
+      def get_state(session_id:, key:)
+        session = get_session(session_id: session_id)
+        if session
+          session.get_state(key) # Legate::Session#get_state handles its own logic
+        else
+          Legate.logger.warn("InMemorySessionService: Session not found '#{session_id}' when trying to get state for key '#{key}'.")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/legate/tool/metadata_dsl.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legate
+  class Tool
+    # Module to provide a more concise DSL for defining tool metadata.
+    module MetadataDsl
+      def self.included(base)
+        base.extend ClassMethods
+
+        # Define class instance variable accessors on the base class singleton
+        # These are primarily for the *new* DSL
+        class << base
+          # Replaced attr_accessor with manual methods to handle cache invalidation
+          # attr_accessor :explicit_tool_name, :description, :parameters_definition
+
+          attr_reader :explicit_tool_name, :description, :parameters_definition
+
+          def explicit_tool_name=(value)
+            @explicit_tool_name = value
+            @_tool_metadata_cache = nil # Invalidate cache
+          end
+
+          def description=(value)
+            @description = value
+            @_tool_metadata_cache = nil # Invalidate cache
+          end
+
+          def parameters_definition=(value)
+            @parameters_definition = value
+            @_tool_metadata_cache = nil # Invalidate cache
+          end
+
+          # Initialize with default values to ensure methods don't fail on nil
+          # Note: These are instance variables of the singleton class (class instance variables)
+          def initialize_dsl_storage
+            @explicit_tool_name ||= nil
+            @description ||= nil # DSL description storage
+            @parameters_definition ||= {} # DSL parameters storage
+          end
+        end
+      end
+
+      module ClassMethods
+        # DSL method for setting description
+        def tool_description(text)
+          initialize_dsl_storage # Ensure vars exist
+          self.description = text.to_s
+        end
+
+        # DSL method for defining a parameter
+        def parameter(name, options = {})
+          initialize_dsl_storage # Ensure hash exists
+          raise ArgumentError, 'Parameter name must be a Symbol' unless name.is_a?(Symbol)
+
+          @parameters_definition[name] = options
+          @_tool_metadata_cache = nil # Invalidate cache on modification
+        end
+
+        # Get the inferred name (logic unchanged)
+        def inferred_name
+          class_name_str = Module.instance_method(:name).bind(self).call
+          return nil unless class_name_str && !class_name_str.empty? && class_name_str.is_a?(String)
+          return nil if class_name_str.start_with?('#<Class:')
+
+          inferred = class_name_str.split('::').last
+          return nil if inferred.nil? || inferred.empty?
+
+          inferred = inferred.dup
+          inferred.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          inferred.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+          inferred.tr!('-', '_')
+          inferred.downcase!
+          inferred.to_sym
+        end
+
+        # Get the final tool name with priority:
+        # 1. DSL's explicit_tool_name
+        # 2. define_metadata's @tool_name
+        # 3. Inferred name
+        def effective_tool_name
+          initialize_dsl_storage # Ensure @explicit_tool_name exists
+          explicit_dsl = explicit_tool_name
+          return explicit_dsl if explicit_dsl && explicit_dsl != :''
+
+          # Check define_metadata's variable if explicit DSL name wasn't set
+          # Use instance_variable_get as @tool_name is not directly accessible via reader here
+          if instance_variable_defined?(:@tool_name)
+            explicit_old = instance_variable_get(:@tool_name)
+            return explicit_old if explicit_old && explicit_old != :''
+          end
+
+          # Fallback to inferred name
+          inferred_name
+        end
+
+        # Retrieve consolidated metadata, preferring DSL values but falling back to define_metadata values.
+        # Cached for performance.
+        def tool_metadata
+          @_tool_metadata_cache ||= begin
+            initialize_dsl_storage # Ensure DSL variables exist
+
+            # Get description: Prefer DSL, fallback to define_metadata's @description
+            dsl_desc = description
+            old_desc = instance_variable_get(:@description) if instance_variable_defined?(:@description) && dsl_desc.nil?
+            final_desc = dsl_desc || old_desc
+
+            # Get parameters: Prefer DSL, fallback to define_metadata's @parameters_definition
+            dsl_params = parameters_definition
+            old_params = instance_variable_get(:@parameters_definition) if instance_variable_defined?(:@parameters_definition) && (dsl_params.nil? || dsl_params.empty?)
+            final_params = dsl_params && !dsl_params.empty? ? dsl_params : (old_params || {})
+
+            {
+              name: effective_tool_name,
+              description: final_desc,
+              parameters: final_params
+            }
+          end
+        end
+      end # End ClassMethods
+    end
+  end
+end