activematrix 0.0.7 → 0.0.8

data/lib/active_matrix/agent_manager.rb

@@ -1,43 +1,88 @@
 # frozen_string_literal: true
 
 require 'singleton'
+require 'async'
+require 'async/barrier'
+require 'async/semaphore'
 
 module ActiveMatrix
-  # Manages the lifecycle of Matrix bot agents
+  # Manages the lifecycle of Matrix bot agents using async fibers
   class AgentManager
     include Singleton
     include ActiveMatrix::Logging
 
+    # OpenTelemetry semantic conventions for messaging
+    OTEL_ATTRS = {
+      service: 'activematrix.agent_manager',
+      messaging_system: 'matrix'
+    }.freeze
+
     attr_reader :registry, :config
 
     def initialize
       @registry = AgentRegistry.instance
       @config = ActiveMatrix.config
-      @shutdown = false
-      @monitor_thread = nil
+      @barrier = nil
+      @monitor_task = nil
+      @running = false
+    end
 
-      setup_signal_handlers
+    # Install signal handlers for graceful shutdown.
+    # Call this explicitly if you want the gem to handle SIGINT/SIGTERM.
+    # By default, signal handling is left to the host application.
+    def install_signal_handlers!
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) do
+          stop_all
+          exit # rubocop:disable Rails/Exit
+        end
+      end
     end
 
     # Start all agents marked as active in the database
+    # This is the main entry point - runs the async reactor
     def start_all
-      return if @shutdown
+      agents = ActiveMatrix::Agent.where.not(state: :offline)
+      start_agents(agents)
+    end
 
-      logger.info 'Starting all active agents...'
+    # Start specific agents (used by daemon workers)
+    # @param agents [ActiveRecord::Relation, Array<Agent>] Agents to start
+    def start_agents(agents)
+      return if @running
 
-      agents = defined?(MatrixAgent) ? MatrixAgent.where.not(state: :offline) : []
-      agents.each_with_index do |agent, index|
-        sleep(config.agent_startup_delay || 2) if index.positive?
-        start_agent(agent)
-      end
+      @running = true
+      agents_array = agents.respond_to?(:to_a) ? agents.to_a : agents
+      logger.info "Starting #{agents_array.size} agents..."
+
+      Sync do
+        @barrier = Async::Barrier.new
+
+        # Start the event router for routing Matrix events
+        EventRouter.instance.start
 
-      start_monitor_thread
-      logger.info "Started #{@registry.count} agents"
+        startup_delay = config.agent_startup_delay || 2
+
+        agents_array.each_with_index do |agent, index|
+          sleep(startup_delay) if index.positive?
+          start_agent(agent)
+        end
+
+        start_monitor_task
+
+        logger.info "Started #{@registry.count} agents"
+
+        # Wait for all agent tasks to complete (blocks until shutdown)
+        @barrier.wait
+      ensure
+        @barrier&.stop
+        @running = false
+      end
     end
 
-    # Start a specific agent
+    # Start a specific agent as an async task
     def start_agent(agent)
-      return if @shutdown
+      return false unless @running
 
       if @registry.running?(agent)
         logger.warn "Agent #{agent.name} is already running"
@@ -47,51 +92,15 @@ module ActiveMatrix
       logger.info "Starting agent: #{agent.name}"
 
       begin
-        # Update state
         agent.connect!
 
-        # Create bot instance in a new thread
-        thread = Thread.new do
-          Thread.current.name = "agent-#{agent.name}"
-
-          begin
-            # Create client and bot instance
-            client = create_client_for_agent(agent)
-            bot_class = agent.bot_class.constantize
-            bot_instance = bot_class.new(client)
-
-            # Register the agent
-            @registry.register(agent, bot_instance)
-
-            # Authenticate if needed
-            if agent.access_token.present?
-              client.access_token = agent.access_token
-            else
-              client.login(agent.username, agent.password)
-              agent.update(access_token: client.access_token)
-            end
-
-            # Restore sync token if available
-            client.sync_token = agent.last_sync_token if agent.last_sync_token.present?
-
-            # Mark as online
-            agent.connection_established!
-
-            # Start the sync loop
-            client.start_listener_thread
-            client.instance_variable_get(:@sync_thread).join
-          rescue StandardError => e
-            logger.error "Error in agent #{agent.name}: #{e.message}"
-            logger.error e.backtrace.join("\n")
-            agent.encounter_error!
-            raise
-          ensure
-            @registry.unregister(agent)
-            agent.disconnect! if agent.may_disconnect?
-          end
+        task = @barrier.async do |subtask|
+          subtask.annotate "agent-#{agent.name}"
+          run_agent(agent)
         end
 
-        thread.abort_on_exception = true
+        # Store task reference for later control
+        @registry.register_task(agent, task)
         true
       rescue StandardError => e
         logger.error "Failed to start agent #{agent.name}: #{e.message}"
@@ -109,18 +118,15 @@ module ActiveMatrix
 
       begin
         # Stop the client sync
-        client = entry[:instance].client
-        client.stop_listener_thread if client.listening?
+        client = entry[:instance]&.client
+        client&.stop_listener if client&.listening?
 
         # Save sync token
-        agent.update(last_sync_token: client.sync_token) if client.sync_token.present?
+        agent.update(last_sync_token: client.sync_token) if client&.sync_token.present?
 
-        # Kill the thread if still alive
-        thread = entry[:thread]
-        if thread&.alive?
-          thread.kill
-          thread.join(5) # Wait up to 5 seconds
-        end
+        # Stop the async task gracefully
+        task = entry[:task]
+        task&.stop
 
         # Update state
         agent.disconnect! if agent.may_disconnect?
@@ -135,16 +141,17 @@ module ActiveMatrix
     # Stop all running agents
     def stop_all
       logger.info 'Stopping all agents...'
-      @shutdown = true
 
-      # Stop monitor thread
-      @monitor_thread&.kill
+      # Stop monitor task
+      @monitor_task&.stop
 
-      # Stop all agents
-      @registry.all_records.each do |agent|
-        stop_agent(agent)
-      end
+      # Stop event router
+      EventRouter.instance.stop
 
+      # Stop all agent tasks via barrier
+      @barrier&.stop
+
+      @running = false
       logger.info 'All agents stopped'
     end
 
@@ -164,8 +171,8 @@ module ActiveMatrix
 
       logger.info "Pausing agent: #{agent.name}"
 
-      client = entry[:instance].client
-      client.stop_listener_thread if client.listening?
+      client = entry[:instance]&.client
+      client&.stop_listener if client&.listening?
       agent.pause!
 
       true
@@ -181,8 +188,8 @@ module ActiveMatrix
       logger.info "Resuming agent: #{agent.name}"
 
       agent.resume!
-      client = entry[:instance].client
-      client.start_listener_thread
+      client = entry[:instance]&.client
+      client&.start_listener
       agent.connection_established!
 
       true
@@ -193,41 +200,79 @@ module ActiveMatrix
       {
         running: @registry.count,
         agents: @registry.health_status,
-        monitor_active: @monitor_thread&.alive? || false,
-        shutdown: @shutdown
+        monitor_active: @monitor_task&.alive? || false,
+        shutdown: !@running
       }
     end
 
+    # Check if currently running
+    def running?
+      @running
+    end
+
     private
 
-    def create_client_for_agent(agent)
-      # Use shared client pool if available
-      if defined?(ClientPool)
-        ClientPool.instance.get_client(agent.homeserver)
-      else
-        ActiveMatrix::Client.new(agent.homeserver,
-                                 client_cache: :some,
-                                 sync_filter_limit: 20)
+    def run_agent(agent)
+      Telemetry.trace('agent.run', attributes: agent_attributes(agent)) do |span|
+        # Create client and bot instance
+        client = create_client_for_agent(agent)
+        bot_class = agent.bot_class.constantize
+        bot_instance = bot_class.new(client)
+
+        # Register the agent
+        @registry.register(agent, bot_instance)
+
+        # Authenticate if needed
+        if agent.access_token.present?
+          client.access_token = agent.access_token
+        else
+          Telemetry.trace('agent.login', attributes: agent_attributes(agent)) do
+            client.login(agent.username, agent.password)
+            agent.update(access_token: client.access_token)
+          end
+        end
+
+        # Restore sync token if available
+        client.sync_token = agent.last_sync_token if agent.last_sync_token.present?
+
+        # Mark as online
+        agent.connection_established!
+        span&.add_event('agent.connected')
+
+        # Run the sync loop (blocks until stopped)
+        client.listen_forever
       end
+    rescue Async::Stop
+      logger.info "Agent #{agent.name} stopping gracefully"
+    rescue StandardError => e
+      Telemetry.record_exception(e, attributes: agent_attributes(agent))
+      logger.error "Error in agent #{agent.name}: #{e.message}"
+      logger.error e.backtrace.first(10).join("\n")
+      agent.encounter_error!
+      raise
+    ensure
+      @registry.unregister(agent)
+      agent.disconnect! if agent.may_disconnect?
     end
 
-    def start_monitor_thread
-      return if @monitor_thread&.alive?
+    def create_client_for_agent(agent)
+      ClientPool.instance.get_client(agent.homeserver)
+    end
 
-      @monitor_thread = Thread.new do
-        Thread.current.name = 'agent-monitor'
+    def start_monitor_task
+      return if @monitor_task&.alive?
 
-        loop do
-          break if @shutdown
+      health_interval = config.agent_health_check_interval || 30
 
-          begin
-            check_agent_health
-            cleanup_stale_data
-          rescue StandardError => e
-            logger.error "Monitor thread error: #{e.message}"
-          end
+      @monitor_task = Async(transient: true) do |task|
+        task.annotate 'agent-monitor'
 
-          sleep(config.agent_health_check_interval || 30)
+        loop do
+          sleep(health_interval)
+          check_agent_health
+          cleanup_stale_data
+        rescue StandardError => e
+          logger.error "Monitor task error: #{e.message}"
         end
       end
     end
@@ -235,41 +280,35 @@ module ActiveMatrix
     def check_agent_health
       @registry.find_each do |entry|
         agent = entry[:record]
-        thread = entry[:thread]
+        task = entry[:task]
 
-        # Check if thread is alive
-        unless thread&.alive?
-          logger.warn "Agent #{agent.name} thread died, restarting..."
+        # Check if task is alive
+        unless task&.alive?
+          logger.warn "Agent #{agent.name} task died, restarting..."
           @registry.unregister(agent)
           agent.encounter_error!
-          start_agent(agent) unless @shutdown
+          start_agent(agent) if @running
           next
         end
 
         # Check last activity
-        if agent.last_active_at && agent.last_active_at < 5.minutes.ago
-          logger.warn "Agent #{agent.name} seems inactive"
-          # Could implement additional health checks here
-        end
+        logger.warn "Agent #{agent.name} seems inactive" if agent.last_active_at && agent.last_active_at < 5.minutes.ago
       end
     end
 
     def cleanup_stale_data
-      # Clean up old conversation contexts
-      ConversationContext.cleanup_stale! if defined?(ConversationContext)
-
-      # Clean up expired memories
-      AgentMemory.cleanup_expired! if defined?(AgentMemory)
-      GlobalMemory.cleanup_expired! if defined?(GlobalMemory)
+      ActiveMatrix::ChatSession.cleanup_stale!
+      ActiveMatrix::AgentStore.cleanup_expired!
+      ActiveMatrix::KnowledgeBase.cleanup_expired!
     end
 
-    def setup_signal_handlers
-      %w[INT TERM].each do |signal|
-        Signal.trap(signal) do
-          Thread.new { stop_all }.join
-          exit # rubocop:disable Rails/Exit
-        end
-      end
+    def agent_attributes(agent)
+      OTEL_ATTRS.merge(
+        'agent.id' => agent.id,
+        'agent.name' => agent.name,
+        'agent.homeserver' => agent.homeserver,
+        'agent.bot_class' => agent.bot_class
+      )
     end
   end
 end

data/lib/active_matrix/agent_registry.rb

@@ -11,32 +11,33 @@ module ActiveMatrix
 
     def initialize
       @agents = Concurrent::Hash.new
-      @mutex = Mutex.new
     end
 
     # Register a running agent
     def register(agent_record, bot_instance)
-      @mutex.synchronize do
-        raise AgentAlreadyRunningError, "Agent #{agent_record.name} is already running" if @agents.key?(agent_record.id)
-
-        @agents[agent_record.id] = {
-          record: agent_record,
-          instance: bot_instance,
-          thread: Thread.current,
-          started_at: Time.current
-        }
+      raise AgentAlreadyRunningError, "Agent #{agent_record.name} is already running" if @agents.key?(agent_record.id)
 
-        logger.info "Registered agent: #{agent_record.name} (#{agent_record.id})"
-      end
+      @agents[agent_record.id] = {
+        record: agent_record,
+        instance: bot_instance,
+        task: nil,
+        started_at: Time.current
+      }
+
+      logger.info "Registered agent: #{agent_record.name} (#{agent_record.id})"
+    end
+
+    # Register an async task for an agent
+    def register_task(agent_record, task)
+      entry = @agents[agent_record.id]
+      entry[:task] = task if entry
     end
 
     # Unregister an agent
     def unregister(agent_record)
-      @mutex.synchronize do
-        entry = @agents.delete(agent_record.id)
-        logger.info "Unregistered agent: #{agent_record.name} (#{agent_record.id})" if entry
-        entry
-      end
+      entry = @agents.delete(agent_record.id)
+      logger.info "Unregistered agent: #{agent_record.name} (#{agent_record.id})" if entry
+      entry
     end
 
     # Get a running agent by ID
@@ -123,9 +124,7 @@ module ActiveMatrix
 
     # Clear all agents (used for testing)
     def clear!
-      @mutex.synchronize do
-        @agents.clear
-      end
+      @agents.clear
     end
 
     # Get health status of all agents
@@ -135,13 +134,18 @@ module ActiveMatrix
           id: id,
           name: entry[:record].name,
           state: entry[:record].state,
-          thread_alive: entry[:thread]&.alive?,
+          task_alive: entry[:task]&.alive?,
           uptime: Time.current - entry[:started_at],
           last_active: entry[:record].last_active_at
         }
       end
     end
 
+    # Iterate through all agents
+    def find_each(&)
+      @agents.values.each(&)
+    end
+
     private
 
     def by_name_pattern(pattern)

data/lib/active_matrix/api.rb

@@ -10,7 +10,7 @@ module ActiveMatrix
     extend ActiveMatrix::Extensions
     include ActiveMatrix::Logging
 
-    USER_AGENT = "Ruby Matrix SDK v#{ActiveMatrix::VERSION}".freeze
+    USER_AGENT = "ActiveMatrix v#{ActiveMatrix::VERSION}".freeze
     DEFAULT_HEADERS = {
       'accept' => 'application/json',
       'user-agent' => USER_AGENT
@@ -287,7 +287,7 @@ module ActiveMatrix
       end
 
       failures = 0
-      loop do
+      loop do # rubocop:disable Metrics/BlockLength
         raise MatrixConnectionError, "Server still too busy to handle request after #{failures} attempts, try again later" if failures >= 10
 
         req_id = ('A'..'Z').to_a.sample(4).join
@@ -343,6 +343,12 @@ module ActiveMatrix
         end
         raise MatrixRequestError.new_by_code(data, response.code) if data
 
+        # For 4xx errors without JSON body, construct a synthetic error
+        if response.code.to_i >= 400 && response.code.to_i < 500
+          synthetic_error = { errcode: 'M_UNKNOWN', error: "HTTP #{response.code} #{response.message}" }
+          raise MatrixRequestError.new_by_code(synthetic_error, response.code)
+        end
+
         raise MatrixConnectionError.class_by_code(response.code), response
       end
     end

data/lib/active_matrix/async_query.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  # Helper methods for async ActiveRecord queries (Rails 8.0+)
+  module AsyncQuery
+    module_function
+
+    # Load records asynchronously
+    # @param relation [ActiveRecord::Relation] The relation to load
+    # @return [Array] The loaded records
+    def load_async(relation)
+      relation.load_async.to_a
+    end
+
+    # Count records asynchronously
+    # @param relation [ActiveRecord::Relation] The relation to count
+    # @return [Integer] The count
+    def async_count(relation)
+      relation.async_count.value
+    end
+
+    # Sum column asynchronously
+    # @param relation [ActiveRecord::Relation] The relation
+    # @param column [Symbol] The column to sum
+    # @return [Numeric] The sum
+    def async_sum(relation, column)
+      relation.async_sum(column).value
+    end
+
+    # Pluck columns asynchronously
+    # @param relation [ActiveRecord::Relation] The relation
+    # @param columns [Array<Symbol>] The columns to pluck
+    # @return [Array] The plucked values
+    def async_pluck(relation, *columns)
+      relation.async_pluck(*columns).value
+    end
+
+    # Check existence asynchronously
+    # @param relation [ActiveRecord::Relation] The relation
+    # @return [Boolean] Whether records exist
+    def async_exists?(relation)
+      relation.async_count.value.positive?
+    end
+
+    # Execute multiple async queries in parallel and wait for all results
+    # @param queries [Hash<Symbol, Proc>] Named queries to execute
+    # @return [Hash<Symbol, Object>] Results keyed by query name
+    # @example
+    #   results = AsyncQuery.parallel(
+    #     agents: -> { MatrixAgent.where(state: :online).load_async },
+    #     count: -> { MatrixAgent.async_count }
+    #   )
+    def parallel(**queries)
+      promises = queries.transform_values(&:call)
+      promises.transform_values { |result| result.respond_to?(:value) ? result.value : result }
+    end
+  end
+end

data/lib/active_matrix/bot/base.rb

@@ -377,7 +377,7 @@ module ActiveMatrix::Bot
         if settings.store_sync_token
           begin
             active_bot.client.api.set_account_data(
-              active_bot.client.mxid, "dev.ananace.ruby-sdk.#{settings.bot_name}",
+              active_bot.client.mxid, "com.seuros.active_matrix.#{settings.bot_name}",
               { sync_token: active_bot.client.sync_token }
             )
           rescue StandardError => e
@@ -466,7 +466,7 @@ module ActiveMatrix::Bot
           bot.client.instance_variable_set(:@next_batch, settings.sync_token)
         elsif settings.store_sync_token?
           begin
-            data = bot.client.api.get_account_data(bot.client.mxid, "dev.ananace.ruby-sdk.#{bot_name}")
+            data = bot.client.api.get_account_data(bot.client.mxid, "com.seuros.active_matrix.#{bot_name}")
             bot.client.sync_token = data[:sync_token]
           rescue ActiveMatrix::MatrixNotFoundError
             # Valid
@@ -479,7 +479,7 @@ module ActiveMatrix::Bot
 
         bot.client.start_listener_thread
 
-        bot.client.instance_variable_get(:@sync_thread).join
+        bot.client.sync_thread&.join
       rescue Interrupt
         # Happens when killed
       rescue StandardError => e