chat_sdk 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc45b8149b772db87ae0793f070a3f068353ef09a177d59c3526eb0ec37d1fb9
-  data.tar.gz: 16eb68d587eb53a43337f22dd2cd7d5b564383d892ecda9b64b77b5ae45a05a0
+  metadata.gz: 729c1baa552d9bad38924b1f026c75c769bb26b6dc3b4784e5e900ca66c93d21
+  data.tar.gz: 677e7b87d6177385e6a0b3fbe52da890a3238c31dd36c754c62d09e224ba385c
 SHA512:
-  metadata.gz: 7a6cb0121846bf8a75b849f0d6bedfc48601c738dba99c3ad838ecdcb3b31fd7b4a27cd16bfa75cee66a4f70e62b62ae1c4730546b22f430e72d1af1bf6219c2
-  data.tar.gz: 602d33c5bba332dac427d61e8566c396f10c057e6b17a3422d1ab4846e4d7e8857ece123b50d2d357e310072f119bee00436db593e6138e46aabc34ba65f777c
+  metadata.gz: 50cb4ab19ee8b817e4395030a9ca15ddd8980d785d0bff8f0dabb13462b636259fd6ff42afca5c2cfece542e74dd50224188dd2090e3bbf3378e558045cb4bf3
+  data.tar.gz: 13183055e0ce37f542350374d6210f8ec6dd2b63c34a0acef2629515cf0009bbcc7e93d03c64b39b96d16982dbce8f0904c1a7a51f1661f267f9880bf59d56bc

data/lib/chat_sdk/adapter/base.rb

@@ -22,7 +22,7 @@ module ChatSDK
         nil
       end
 
-      def webhook_response(_events)
+      def webhook_response(_events, _request = nil)
         nil
       end
 
@@ -35,6 +35,12 @@ module ChatSDK
         raise NotImplementedError
       end
 
+      # Stream using a platform-native API, or return nil before consuming
+      # chunks to delegate to the core post+edit fallback.
+      def stream(channel_id:, thread_id:, stream:, options: {})
+        nil
+      end
+
       def reply_message(channel_id:, message_id:, message:, thread_id: nil)
         require_capability!(:replies)
         raise NotImplementedError

data/lib/chat_sdk/ai/stream_handler.rb

@@ -3,9 +3,9 @@
 module ChatSDK
   module AI
     class StreamHandler
-      def self.stream_to_thread(thread, enumerable, placeholder: "Thinking...")
-        thread.post_stream(placeholder: placeholder) do |stream|
-          enumerable.each { |chunk| stream << chunk.to_s }
+      def self.stream_to_thread(thread, enumerable, placeholder: "Thinking...", **plan_options)
+        thread.post_stream(placeholder: placeholder, **plan_options) do |stream|
+          enumerable.each { |chunk| stream << chunk }
         end
       end
     end

data/lib/chat_sdk/cards/actions_context.rb

@@ -9,30 +9,50 @@ module ChatSDK
         @nodes = []
       end
 
-      def button(text, id:, style: nil, value: nil, tooltip: nil, visible_to: nil)
+      def button(text, id:, style: nil, value: nil, tooltip: nil, visible_to: nil, disabled: nil)
         attrs = {text: text, id: id}
         attrs[:style] = style if style
         attrs[:value] = value if value
         attrs[:tooltip] = tooltip if tooltip
         attrs[:visible_to] = visible_to if visible_to
+        attrs[:disabled] = disabled unless disabled.nil?
         @nodes << Node.new(:button, attributes: attrs)
       end
 
-      def link_button(text, url:, id: nil, tooltip: nil, visible_to: nil)
+      def link_button(text, url:, id: nil, style: nil, tooltip: nil, visible_to: nil)
         attrs = {text: text, url: url}
         attrs[:id] = id if id
+        attrs[:style] = style if style
         attrs[:tooltip] = tooltip if tooltip
         attrs[:visible_to] = visible_to if visible_to
         @nodes << Node.new(:link_button, attributes: attrs)
       end
 
-      def select(id:, placeholder: nil, &block)
+      def select(id:, placeholder: nil, label: nil, initial_option: nil, optional: nil, dispatch_action: nil, &block)
         ctx = SelectContext.new
-        ctx.instance_eval(&block)
+        ctx.instance_eval(&block) if block
+        raise ArgumentError, "Select requires at least one option" if ctx.nodes.empty?
+
         attrs = {id: id}
         attrs[:placeholder] = placeholder if placeholder
+        attrs[:label] = label unless label.nil?
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
         @nodes << Node.new(:select, attributes: attrs, children: ctx.nodes)
       end
+
+      def radio_select(id:, label:, initial_option: nil, optional: nil, dispatch_action: nil, &block)
+        ctx = SelectContext.new
+        ctx.instance_eval(&block) if block
+        raise ArgumentError, "RadioSelect requires at least one option" if ctx.nodes.empty?
+
+        attrs = {id: id, label: label}
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
+        @nodes << Node.new(:radio_select, attributes: attrs, children: ctx.nodes)
+      end
     end
   end
 end

data/lib/chat_sdk/cards/builder.rb

@@ -5,10 +5,11 @@ module ChatSDK
     class Builder
       RESERVED_TEXT_INPUT_IDS = %w[actionId value msteams].freeze
 
-      def initialize(title: nil, subtitle: nil, width: nil, &block)
+      def initialize(title: nil, subtitle: nil, width: nil, image_url: nil, &block)
         @title = title
         @subtitle = subtitle
         @width = width
+        @image_url = image_url
         @children = []
         instance_eval(&block) if block
       end
@@ -18,11 +19,18 @@ module ChatSDK
         attrs[:title] = @title if @title
         attrs[:subtitle] = @subtitle if @subtitle
         attrs[:width] = @width if @width
+        attrs[:image_url] = @image_url if @image_url
         Node.new(:card, attributes: attrs, children: @children)
       end
 
-      def text(content)
-        @children << Node.new(:text, attributes: {content: content})
+      def text(content, style: nil)
+        attrs = {content: content}
+        attrs[:style] = style unless style.nil?
+        @children << Node.new(:text, attributes: attrs)
+      end
+
+      def link(url:, label:)
+        @children << Node.new(:link, attributes: {url: url, label: label})
       end
 
       def divider
@@ -33,7 +41,7 @@ module ChatSDK
         @children << Node.new(:image, attributes: {url: url, alt: alt})
       end
 
-      def text_input(id:, label:, placeholder: nil, multiline: false, optional: false, value: nil)
+      def text_input(id:, label:, placeholder: nil, multiline: false, optional: false, value: nil, max_length: nil)
         if RESERVED_TEXT_INPUT_IDS.include?(id.to_s)
           raise ArgumentError, "Text input id #{id.inspect} is reserved"
         end
@@ -41,6 +49,7 @@ module ChatSDK
         attrs = {id: id, label: label, multiline: multiline, optional: optional}
         attrs[:placeholder] = placeholder if placeholder
         attrs[:value] = value unless value.nil?
+        attrs[:max_length] = max_length unless max_length.nil?
         @children << Node.new(:text_input, attributes: attrs)
       end
 

data/lib/chat_sdk/cards/node.rb

@@ -27,6 +27,8 @@ module ChatSDK
           case node.type
           when :text
             [node.attributes[:content]]
+          when :link
+            ["#{node.attributes[:label]} (#{node.attributes[:url]})"]
           when :field
             ["#{node.attributes[:label]}: #{node.attributes[:value]}"]
           when :button, :link_button

data/lib/chat_sdk/cards/renderer.rb

@@ -9,6 +9,7 @@ module ChatSDK
         when :text then node.attributes[:content]
         when :divider then "---"
         when :image then "![#{node.attributes[:alt]}](#{node.attributes[:url]})"
+        when :link then "[#{node.attributes[:label]}](#{node.attributes[:url]})"
         when :fields then render_fields(node)
         when :field then "**#{node.attributes[:label]}**: #{node.attributes[:value]}"
         when :section then render_section(node)
@@ -17,6 +18,7 @@ module ChatSDK
         when :link_button then "[#{node.attributes[:text]}](#{node.attributes[:url]})"
         when :text_input then node.attributes[:label]
         when :select then "_#{node.attributes[:placeholder] || "Select"}_"
+        when :radio_select then "_#{node.attributes[:label] || "Select"}_"
         when :table then render_table(node)
         when :chart then render_chart(node)
         else ""

data/lib/chat_sdk/chat.rb

@@ -3,18 +3,27 @@
 module ChatSDK
   class Chat
     attr_reader :config, :state, :history
+    # @api private
+    attr_reader :error_reporter
 
     def initialize(user_name:, adapters:, state:, **options)
       @config = Config.new(user_name: user_name, adapters: adapters, state: state, **options)
       @state = state
+      ChatSDK::Log.logger = @config.logger if @config.logger
+      ChatSDK::Log.level = @config.log_level if @config.log_level
       @adapters = adapters
       @adapters.each_value { |adapter| adapter.set_state(state) if adapter.respond_to?(:set_state) }
       @registry = EventRegistry.new
       @history = History.new(self)
       @webhooks = {}
-      @dispatcher = Dispatcher.new(chat: self, config: @config, state: @state, registry: @registry)
-
-      ChatSDK::Log.level = @config.log_level
+      @error_reporter = ErrorReporter.new(@config.on_error)
+      @dispatcher = Dispatcher.new(
+        chat: self,
+        config: @config,
+        state: @state,
+        registry: @registry,
+        error_reporter: @error_reporter
+      )
     end
 
     # Event registration
@@ -67,6 +76,22 @@ module ChatSDK
       @registry.register(:uninstalled, &block)
     end
 
+    def on_assistant_thread_started(&block)
+      @registry.register(:assistant_thread_started, &block)
+    end
+
+    def on_assistant_context_changed(&block)
+      @registry.register(:assistant_context_changed, &block)
+    end
+
+    def on_app_home_opened(&block)
+      @registry.register(:app_home_opened, &block)
+    end
+
+    def on_member_joined_channel(&block)
+      @registry.register(:member_joined_channel, &block)
+    end
+
     # Adapter access
     def adapter(name)
       @adapters.fetch(name) { raise ChatSDK::ConfigurationError, "Unknown adapter: #{name}" }
@@ -97,7 +122,28 @@ module ChatSDK
     # Event dispatch (called by webhook endpoints)
     def dispatch(event, adapter_name:)
       adp = adapter(adapter_name)
-      @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
+      executor = @config.handler_executor
+      return @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name) if executor == :inline
+
+      if executor == :thread
+        ::Thread.new { run_background_dispatch(event, adp, adapter_name) }
+      else
+        payload = {"adapter_name" => adapter_name.to_s, "event" => EventSerializer.dump(event)}
+        begin
+          executor.call(payload)
+        rescue => e
+          raise HandlerExecutorError, "handler_executor failed for #{event.type}: #{e.class}: #{e.message}"
+        end
+      end
+      nil
+    end
+
+    # Runs a payload produced for a callable handler_executor, such as from a background job.
+    def dispatch_serialized(payload)
+      payload = payload.transform_keys(&:to_s)
+      adapter_name = payload.fetch("adapter_name").to_sym
+      event = EventSerializer.load(payload.fetch("event"))
+      @dispatcher.dispatch(event, adapter: adapter(adapter_name), adapter_name: adapter_name)
     end
 
     # Deprecated compatibility alias for Vercel Chat SDK's former API.
@@ -106,6 +152,21 @@ module ChatSDK
     end
 
     private
+
+    def run_background_dispatch(event, adp, adapter_name)
+      @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
+    rescue => e
+      # Nothing above this background thread can rescue errors raised during dispatch.
+      @error_reporter.report(
+        e,
+        "Background dispatch error (#{event.type})",
+        source: :dispatch,
+        adapter: adapter_name,
+        event_type: event.type,
+        thread_id: event.respond_to?(:thread_id) ? event.thread_id : nil,
+        channel_id: event.respond_to?(:channel_id) ? event.channel_id : nil
+      )
+    end
   end
 
   class WebhookAccessor

data/lib/chat_sdk/config.rb

@@ -15,7 +15,7 @@ module ChatSDK
 
     attr_reader :user_name, :adapters, :state, :on_lock_conflict,
       :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level,
-      :history_user, :concurrency
+      :history_user, :concurrency, :logger, :on_error
 
     def initialize(user_name:, adapters:, state:, **options)
       raise ConfigurationError, "user_name is required" if user_name.nil? || user_name.empty?
@@ -26,6 +26,8 @@ module ChatSDK
       @adapters = adapters
       @state = state
       merged = DEFAULTS.merge(options)
+      @logger = merged[:logger]
+      @on_error = merged[:on_error]
       @on_lock_conflict = merged[:on_lock_conflict]
       @concurrency = normalize_concurrency(merged[:concurrency], lock_scope: merged[:lock_scope])
       @dedupe_ttl = merged[:dedupe_ttl]
@@ -38,13 +40,43 @@ module ChatSDK
         retention: user_history.fetch(:retention, user_history.fetch("retention", 30 * 24 * 3600)),
         max_per_user: user_history.fetch(:max_per_user, user_history.fetch("max_per_user", 200))
       }
-      @log_level = merged[:log_level]
+      @log_level = if !@logger.nil? && !options.key?(:log_level)
+        nil
+      else
+        merged[:log_level]
+      end
 
+      validate_handler_executor!
+      validate_logger!
+      validate_on_error!
       validate_lock_conflict!
     end
 
     private
 
+    def validate_handler_executor!
+      return if %i[inline thread].include?(@handler_executor) || @handler_executor.respond_to?(:call)
+
+      raise ConfigurationError, "handler_executor must be :inline, :thread, or a callable"
+    end
+
+    def validate_logger!
+      return if @logger.nil?
+      unless %i[debug info warn error].all? { |level| @logger.respond_to?(level) }
+        raise ConfigurationError, "logger must respond to debug, info, warn, and error"
+      end
+
+      if !@log_level.nil? && !@logger.respond_to?(:level=)
+        raise ConfigurationError, "logger must respond to level= when log_level is set"
+      end
+    end
+
+    def validate_on_error!
+      return if @on_error.nil? || @on_error.respond_to?(:call)
+
+      raise ConfigurationError, "on_error must be a callable"
+    end
+
     def validate_lock_conflict!
       return if %i[drop force].include?(@on_lock_conflict) || @on_lock_conflict.respond_to?(:call)
       raise ConfigurationError, "on_lock_conflict must be :drop, :force, or a callable"

data/lib/chat_sdk/dispatcher.rb

@@ -5,17 +5,25 @@ require "time"
 
 module ChatSDK
   class Dispatcher
+    LIFECYCLE_EVENT_TYPES = %i[
+      assistant_thread_started
+      assistant_context_changed
+      app_home_opened
+      member_joined_channel
+    ].freeze
+
     LockHeartbeat = Struct.new(:thread, :mutex, :condition, :stop, :ownership_lost) do
       def ownership_lost?
         mutex.synchronize { ownership_lost }
       end
     end
 
-    def initialize(chat:, config:, state:, registry:)
+    def initialize(chat:, config:, state:, registry:, error_reporter:)
       @chat = chat
       @config = config
       @state = state
       @registry = registry
+      @error_reporter = error_reporter
       @slot_mutex = Mutex.new
       @slot_condition = ConditionVariable.new
       @active_slots = Hash.new(0)
@@ -24,7 +32,13 @@ module ChatSDK
     def dispatch(event, adapter:, adapter_name:)
       ChatSDK::Instrumentation.instrument("dispatch.chat_sdk", adapter: adapter_name, event_type: event.type) do
         if %i[message_updated message_deleted].include?(event.type)
-          return execute_event(event, build_thread(event, adapter))
+          return execute_event(event, build_thread(event, adapter), adapter_name: adapter_name)
+        end
+
+        if LIFECYCLE_EVENT_TYPES.include?(event.type)
+          return unless dedupe(event, adapter_name, adapter.concurrency_scope(event))
+
+          return execute_event(event, build_thread(event, adapter), adapter_name: adapter_name)
         end
 
         concurrency_scope = adapter.concurrency_scope(event)
@@ -35,32 +49,32 @@ module ChatSDK
         strategy = @config.concurrency[:strategy]
 
         if strategy == :concurrent
-          return with_concurrent_slot(thread_key) { execute_event(event, thread) }
+          return with_concurrent_slot(thread_key) { execute_event(event, thread, adapter_name: adapter_name) }
         end
 
         owner = "#{Process.pid}:#{::Thread.current.object_id}:#{SecureRandom.uuid}"
         if %i[queue burst debounce].include?(strategy)
-          dispatch_queued(event, adapter, thread_key, owner, strategy)
+          dispatch_queued(event, adapter, adapter_name, thread_key, owner, strategy)
         else
-          dispatch_locked(event, thread, thread_key, owner, strategy)
+          dispatch_locked(event, thread, adapter_name, thread_key, owner, strategy)
         end
       end
     end
 
     private
 
-    def dispatch_locked(event, thread, thread_key, owner, strategy)
+    def dispatch_locked(event, thread, adapter_name, thread_key, owner, strategy)
       acquired = acquire_lock(thread_key, event, owner, force: strategy == :force)
       return unless acquired
 
       heartbeat = start_lock_heartbeat(thread_key, owner)
-      execute_event(event, thread)
+      execute_event(event, thread, adapter_name: adapter_name)
     ensure
       stop_lock_heartbeat(heartbeat)
       release_lock(thread_key, owner) if acquired
     end
 
-    def dispatch_queued(event, adapter, thread_key, owner, strategy)
+    def dispatch_queued(event, adapter, adapter_name, thread_key, owner, strategy)
       queue_key = "chat_sdk:queue:#{thread_key}"
       acquired = acquire_lock(thread_key, event, owner, apply_conflict_policy: false)
       pre_enqueued = false
@@ -74,23 +88,23 @@ module ChatSDK
 
       heartbeat = start_lock_heartbeat(thread_key, owner)
       if strategy == :queue
-        execute_event(event, build_thread(event, adapter)) unless pre_enqueued
+        execute_event(event, build_thread(event, adapter), adapter_name: adapter_name) unless pre_enqueued
       else
         enqueue(queue_key, event) unless pre_enqueued
         sleep(@config.concurrency[:debounce].to_f) if strategy == :burst
       end
 
       if strategy == :debounce
-        debounce_loop(queue_key, adapter, heartbeat)
+        debounce_loop(queue_key, adapter, adapter_name, heartbeat)
       else
-        drain_loop(queue_key, adapter, strategy, heartbeat)
+        drain_loop(queue_key, adapter, adapter_name, strategy, heartbeat)
       end
     ensure
       stop_lock_heartbeat(heartbeat)
       release_lock(thread_key, owner) if acquired
     end
 
-    def drain_loop(queue_key, adapter, strategy, heartbeat)
+    def drain_loop(queue_key, adapter, adapter_name, strategy, heartbeat)
       loop do
         break if heartbeat&.ownership_lost?
 
@@ -105,12 +119,12 @@ module ChatSDK
           events[0...-1].filter_map { |queued| queued.message if queued.respond_to?(:message) }
         end
         context = {skipped: skipped, total_since_last_handler: skipped.length + 1}
-        execute_event(current, build_thread(current, adapter), context: context)
+        execute_event(current, build_thread(current, adapter), adapter_name: adapter_name, context: context)
         ::Thread.pass
       end
     end
 
-    def debounce_loop(queue_key, adapter, heartbeat)
+    def debounce_loop(queue_key, adapter, adapter_name, heartbeat)
       skipped = []
       loop do
         sleep(@config.concurrency[:debounce].to_f)
@@ -132,7 +146,7 @@ module ChatSDK
           message.thread_id == latest.thread_id
         end
         context = {skipped: relevant, total_since_last_handler: relevant.length + 1}
-        execute_event(latest, build_thread(latest, adapter), context: context)
+        execute_event(latest, build_thread(latest, adapter), adapter_name: adapter_name, context: context)
         skipped.clear
       end
     end
@@ -262,29 +276,29 @@ module ChatSDK
       ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat, current_message: current_message)
     end
 
-    def execute_event(event, thread, context: nil)
+    def execute_event(event, thread, adapter_name:, context: nil)
       if %i[mention subscribed_message direct_message].include?(event.type)
-        route_message_event(event, thread, context)
+        route_message_event(event, thread, adapter_name, context)
         return
       end
 
       @registry.handlers_for(event).each do |handler|
-        execute_handler(handler, event, thread, context: context)
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
       end
     end
 
-    def route_message_event(event, thread, context)
+    def route_message_event(event, thread, adapter_name, context)
       message = event.message
       dm_handlers = @registry.handlers_for_type(:direct_message, event: event)
       if event.type == :direct_message && dm_handlers.any?
-        run_handlers(dm_handlers, event, thread, context)
+        run_handlers(dm_handlers, event, thread, adapter_name, context)
         return
       end
 
       message.is_mention = true if event.type == :direct_message
 
       if thread&.subscribed?
-        run_handlers(@registry.handlers_for_type(:subscribed_message, event: event), event, thread, context)
+        run_handlers(@registry.handlers_for_type(:subscribed_message, event: event), event, thread, adapter_name, context)
         return
       end
 
@@ -297,17 +311,19 @@ module ChatSDK
       end
 
       if message.is_mention
-        run_handlers(@registry.handlers_for_type(:mention, event: event), event, thread, context)
+        run_handlers(@registry.handlers_for_type(:mention, event: event), event, thread, adapter_name, context)
         return
       end
 
       @registry.handlers_for_type(:new_message, event: event).each do |handler|
-        execute_handler(handler, event, thread, context: context)
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
       end
     end
 
-    def run_handlers(handlers, event, thread, context)
-      handlers.each { |handler| execute_handler(handler, event, thread, context: context) }
+    def run_handlers(handlers, event, thread, adapter_name, context)
+      handlers.each do |handler|
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
+      end
     end
 
     def detect_mention(text)
@@ -315,7 +331,7 @@ module ChatSDK
       /(?<![[:word:]])@#{Regexp.escape(@config.user_name)}\b/i.match?(masked_text)
     end
 
-    def execute_handler(handler, event, thread, context: nil)
+    def execute_handler(handler, event, thread, adapter_name:, context: nil)
       ChatSDK::Instrumentation.instrument("handler.chat_sdk", handler_type: event.type) do
         ChatSDK::AI::ConversationScope.with(thread) do
           case event.type
@@ -326,12 +342,21 @@ module ChatSDK
           when :reaction, :action, :slash_command, :message_deleted, :installed, :uninstalled
             add_thread_to_event(event, thread)
             handler.block.call(event)
+          when *LIFECYCLE_EVENT_TYPES
+            handler.block.call(event)
           end
         end
       end
     rescue => e
-      ChatSDK::Log.error("Handler error (#{event.type}): #{e.message}")
-      ChatSDK::Log.debug(e.backtrace&.first(5)&.join("\n"))
+      @error_reporter.report(
+        e,
+        "Handler error (#{event.type})",
+        source: :handler,
+        adapter: adapter_name,
+        event_type: event.type,
+        thread_id: event.respond_to?(:thread_id) ? event.thread_id : nil,
+        channel_id: event.respond_to?(:channel_id) ? event.channel_id : nil
+      )
     end
 
     def add_thread_to_event(event, thread)

data/lib/chat_sdk/error_reporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class ErrorReporter
+    def initialize(callback = nil)
+      @callback = callback
+    end
+
+    def report(error, message, **context)
+      context = context.compact
+      ChatSDK::Log.error(format_entry(error, message, context))
+      reporter = @callback || self.class.default_callback
+      reporter&.call(error, context)
+    rescue => e
+      ChatSDK::Log.error("on_error callback failed: #{e.class}: #{e.message}")
+    end
+
+    def self.default_callback
+      return unless defined?(::Rails) && ::Rails.respond_to?(:error)
+
+      rails_reporter = ::Rails.error
+      return unless rails_reporter.respond_to?(:report)
+
+      ->(error, context) { rails_reporter.report(error, handled: true, severity: :error, context: context) }
+    end
+
+    private
+
+    def format_entry(error, message, context)
+      details = context.empty? ? "" : " (#{context.map { |key, value| "#{key}=#{value}" }.join(" ")})"
+      entry = "#{message}#{details}: #{error.class}: #{error.message}"
+      backtrace = error.backtrace
+      backtrace ? "#{entry}\n#{backtrace.join("\n")}" : entry
+    end
+  end
+end

data/lib/chat_sdk/errors.rb

@@ -15,6 +15,7 @@ module ChatSDK
 
   class LockConflictError < Error; end
   class SignatureVerificationError < Error; end
+  class HandlerExecutorError < Error; end
 
   class PlatformError < Error
     attr_reader :status, :body, :adapter_name