chat_sdk 1.0.0 → 1.1.0

data/lib/chat_sdk/dispatcher.rb

@@ -1,34 +1,160 @@
 # frozen_string_literal: true
 
+require "securerandom"
+require "time"
+
 module ChatSDK
   class Dispatcher
+    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:)
       @chat = chat
       @config = config
       @state = state
       @registry = registry
+      @slot_mutex = Mutex.new
+      @slot_condition = ConditionVariable.new
+      @active_slots = Hash.new(0)
     end
 
     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))
+        end
+
         return unless dedupe(event, adapter_name)
 
         thread = build_thread(event, adapter)
         thread_key = thread_key_for(event, adapter_name)
+        strategy = @config.concurrency[:strategy]
 
-        return unless acquire_lock(thread_key, event)
+        if strategy == :concurrent
+          return with_concurrent_slot(thread_key) { execute_event(event, thread) }
+        end
 
-        begin
-          handlers = @registry.handlers_for(event)
-          handlers.each { |handler| execute_handler(handler, event, thread) }
-        ensure
-          release_lock(thread_key)
+        owner = "#{Process.pid}:#{::Thread.current.object_id}:#{SecureRandom.uuid}"
+        if %i[queue burst debounce].include?(strategy)
+          dispatch_queued(event, adapter, thread_key, owner, strategy)
+        else
+          dispatch_locked(event, thread, thread_key, owner, strategy)
         end
       end
     end
 
     private
 
+    def dispatch_locked(event, thread, 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)
+    ensure
+      stop_lock_heartbeat(heartbeat)
+      release_lock(thread_key, owner) if acquired
+    end
+
+    def dispatch_queued(event, adapter, 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
+
+      unless acquired
+        enqueue(queue_key, event)
+        pre_enqueued = true
+        acquired = acquire_lock(thread_key, event, owner, apply_conflict_policy: false)
+        return unless acquired
+      end
+
+      heartbeat = start_lock_heartbeat(thread_key, owner)
+      if strategy == :queue
+        execute_event(event, build_thread(event, adapter)) 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)
+      else
+        drain_loop(queue_key, adapter, strategy, heartbeat)
+      end
+    ensure
+      stop_lock_heartbeat(heartbeat)
+      release_lock(thread_key, owner) if acquired
+    end
+
+    def drain_loop(queue_key, adapter, strategy, heartbeat)
+      loop do
+        break if heartbeat&.ownership_lost?
+
+        entries = fresh_entries(@state.drain_queue(queue_key))
+        break if entries.empty?
+
+        events = entries.map { |entry| EventSerializer.load(entry.fetch("event")) }
+        current = events.last
+        skipped = if strategy == :debounce
+          []
+        else
+          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)
+        ::Thread.pass
+      end
+    end
+
+    def debounce_loop(queue_key, adapter, heartbeat)
+      skipped = []
+      loop do
+        sleep(@config.concurrency[:debounce].to_f)
+        break if heartbeat&.ownership_lost?
+
+        entries = fresh_entries(@state.drain_queue(queue_key))
+        break if entries.empty?
+
+        events = entries.map { |entry| EventSerializer.load(entry.fetch("event")) }
+        latest = events.last
+        skipped.concat(events[0...-1].filter_map { |queued| queued.message if queued.respond_to?(:message) })
+
+        if @state.queue_depth(queue_key).positive?
+          skipped << latest.message if latest.respond_to?(:message)
+          next
+        end
+
+        relevant = skipped.select do |message|
+          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)
+        skipped.clear
+      end
+    end
+
+    def enqueue(queue_key, event)
+      entry = {"event" => EventSerializer.dump(event), "enqueued_at" => Time.now.iso8601}
+      @state.enqueue(
+        queue_key,
+        entry,
+        max_size: @config.concurrency[:max_queue_size],
+        drop: @config.concurrency[:on_queue_full]
+      )
+    end
+
+    def fresh_entries(entries)
+      cutoff = Time.now - @config.concurrency[:queue_entry_ttl].to_f
+      entries.select do |entry|
+        Time.iso8601(entry.fetch("enqueued_at")) >= cutoff
+      rescue ArgumentError, KeyError
+        false
+      end
+    end
+
     def dedupe(event, adapter_name)
       event_id = extract_event_id(event)
       return true unless event_id
@@ -45,6 +171,8 @@ module ChatSDK
     def extract_event_id(event)
       if event.respond_to?(:message) && event.message
         event.message.id
+      elsif event.respond_to?(:message_id) && event.message_id
+        "#{event.type}:#{event.message_id}:#{event.timestamp.to_f}"
       elsif event.respond_to?(:raw) && event.raw.is_a?(Hash)
         event.raw[:event_id] || event.raw["event_id"]
       end
@@ -53,33 +181,69 @@ module ChatSDK
     def thread_key_for(event, adapter_name)
       channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
       thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
-      "#{adapter_name}:#{channel_id}:#{thread_id}"
-    end
-
-    def lock_owner
-      @lock_owner ||= "#{Process.pid}:#{::Thread.current.object_id}"
+      lock_scope = @config.concurrency[:lock_scope]
+      scope_id = (lock_scope&.to_sym == :channel) ? channel_id : thread_id
+      "#{adapter_name}:#{channel_id}:#{scope_id}"
     end
 
-    def acquire_lock(thread_key, event)
+    def acquire_lock(thread_key, event, owner, force: false, apply_conflict_policy: true)
       lock_key = "chat_sdk:lock:#{thread_key}"
-      acquired = @state.acquire_lock(lock_key, owner: lock_owner, ttl: 30)
+      acquired = @state.acquire_lock(lock_key, owner: owner, ttl: @config.concurrency[:lock_ttl])
 
-      unless acquired
-        policy = @config.on_lock_conflict
+      if !acquired && apply_conflict_policy
+        policy = force ? :force : @config.on_lock_conflict
         policy = policy.call(thread_key, event) if policy.respond_to?(:call)
-
         if policy == :force
-          @state.force_lock(lock_key, owner: lock_owner, ttl: 30)
+          @state.force_lock(lock_key, owner: owner, ttl: @config.concurrency[:lock_ttl])
           acquired = true
         end
       end
 
-      ChatSDK::Instrumentation.instrument("lock.chat_sdk", key: thread_key, acquired: acquired, policy: acquired ? nil : policy)
+      ChatSDK::Instrumentation.instrument("lock.chat_sdk", key: thread_key, acquired: acquired)
       acquired
     end
 
-    def release_lock(thread_key)
-      @state.release_lock("chat_sdk:lock:#{thread_key}", owner: lock_owner)
+    def release_lock(thread_key, owner)
+      @state.release_lock("chat_sdk:lock:#{thread_key}", owner: owner)
+    end
+
+    def start_lock_heartbeat(thread_key, owner)
+      lock_ttl = @config.concurrency[:lock_ttl].to_f
+      max_lifetime = @config.concurrency[:max_lock_lifetime].to_f
+      mutex = Mutex.new
+      condition = ConditionVariable.new
+      heartbeat = LockHeartbeat.new(mutex: mutex, condition: condition, stop: false, ownership_lost: false)
+      heartbeat.thread = ::Thread.new do
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        interval = [lock_ttl / 3.0, 0.01].max
+        loop do
+          should_stop = mutex.synchronize do
+            condition.wait(mutex, interval) unless heartbeat.stop
+            heartbeat.stop
+          end
+          break if should_stop
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) - started >= max_lifetime
+
+          extended = @state.extend_lock("chat_sdk:lock:#{thread_key}", owner: owner, ttl: lock_ttl)
+          unless extended
+            mutex.synchronize { heartbeat.ownership_lost = true }
+            break
+          end
+        rescue NotImplementedError
+          break
+        end
+      end
+      heartbeat
+    end
+
+    def stop_lock_heartbeat(heartbeat)
+      return unless heartbeat
+
+      heartbeat.mutex.synchronize do
+        heartbeat.stop = true
+        heartbeat.condition.signal
+      end
+      heartbeat.thread.join
     end
 
     def build_thread(event, adapter)
@@ -87,17 +251,28 @@ module ChatSDK
       channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
       return nil unless thread_id && channel_id
 
-      ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat)
+      current_message = event.respond_to?(:message) ? event.message : nil
+      ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat, current_message: current_message)
     end
 
-    def execute_handler(handler, event, thread)
+    def execute_event(event, thread, context: nil)
+      @registry.handlers_for(event).each do |handler|
+        execute_handler(handler, event, thread, context: context)
+      end
+    end
+
+    def execute_handler(handler, event, thread, context: nil)
       ChatSDK::Instrumentation.instrument("handler.chat_sdk", handler_type: event.type) do
-        case event.type
-        when :mention, :subscribed_message, :direct_message
-          handler.block.call(thread, event.message)
-        when :reaction, :action, :slash_command
-          add_thread_to_event(event, thread)
-          handler.block.call(event)
+        ChatSDK::AI::ConversationScope.with(thread) do
+          case event.type
+          when :mention, :subscribed_message, :direct_message
+            handler.block.call(thread, event.message, context)
+          when :message_updated
+            handler.block.call(thread, event.message, event.previous_message)
+          when :reaction, :action, :slash_command, :message_deleted
+            add_thread_to_event(event, thread)
+            handler.block.call(event)
+          end
         end
       end
     rescue => e
@@ -108,5 +283,23 @@ module ChatSDK
     def add_thread_to_event(event, thread)
       event.thread = thread if event.respond_to?(:thread=)
     end
+
+    def with_concurrent_slot(key)
+      max = @config.concurrency[:max_concurrent]
+      return yield unless max
+
+      @slot_mutex.synchronize do
+        @slot_condition.wait(@slot_mutex) while @active_slots[key] >= max
+        @active_slots[key] += 1
+      end
+      yield
+    ensure
+      if max
+        @slot_mutex.synchronize do
+          @active_slots[key] -= 1
+          @slot_condition.broadcast
+        end
+      end
+    end
   end
 end

data/lib/chat_sdk/event_serializer.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module ChatSDK
+  class EventSerializer
+    class << self
+      def dump(event)
+        data = common_event(event)
+        case event.type
+        when :mention, :subscribed_message, :direct_message, :message_updated
+          data["message"] = dump_message(event.message)
+          data["previous_message"] = dump_message(event.previous_message) if event.respond_to?(:previous_message) && event.previous_message
+        when :message_deleted
+          data.merge!(
+            "message_id" => event.message_id,
+            "previous_message" => dump_message(event.previous_message),
+            "deleted_at" => event.deleted_at&.iso8601
+          )
+        when :reaction
+          data.merge!("emoji" => event.emoji, "user_id" => event.user_id, "message_id" => event.message_id, "added" => event.added?)
+        when :action
+          data.merge!("action_id" => event.action_id, "value" => event.value, "user" => dump_author(event.user), "trigger_id" => event.trigger_id)
+        when :slash_command
+          data.merge!("command" => event.command, "text" => event.text, "user_id" => event.user_id, "trigger_id" => event.trigger_id)
+        end
+        data
+      end
+
+      def load(data)
+        data = data.transform_keys(&:to_s)
+        type = data.fetch("type").to_sym
+        common = {
+          thread_id: data["thread_id"],
+          channel_id: data["channel_id"],
+          platform: data["platform"].to_sym,
+          adapter_name: data["adapter_name"].to_sym,
+          raw: data["raw"],
+          timestamp: parse_time(data["timestamp"])
+        }
+        case type
+        when :mention, :subscribed_message, :direct_message
+          class_name = {mention: Events::Mention, subscribed_message: Events::SubscribedMessage, direct_message: Events::DirectMessage}.fetch(type)
+          class_name.new(message: load_message(data["message"]), **common)
+        when :message_updated
+          Events::MessageUpdated.new(message: load_message(data["message"]), previous_message: load_message(data["previous_message"]), **common)
+        when :message_deleted
+          Events::MessageDeleted.new(
+            message_id: data["message_id"],
+            previous_message: load_message(data["previous_message"]),
+            deleted_at: parse_time(data["deleted_at"]),
+            **common
+          )
+        when :reaction
+          Events::Reaction.new(emoji: data["emoji"], user_id: data["user_id"], message_id: data["message_id"], added: data["added"], **common)
+        when :action
+          Events::Action.new(action_id: data["action_id"], value: data["value"], user: load_author(data["user"]), trigger_id: data["trigger_id"], **common)
+        when :slash_command
+          common.delete(:thread_id)
+          Events::SlashCommand.new(command: data["command"], text: data["text"], user_id: data["user_id"], trigger_id: data["trigger_id"], **common)
+        else
+          raise ArgumentError, "unsupported queued event type: #{type}"
+        end
+      end
+
+      private
+
+      def common_event(event)
+        {
+          "type" => event.type.to_s,
+          "platform" => event.platform.to_s,
+          "adapter_name" => event.adapter_name.to_s,
+          "thread_id" => event.respond_to?(:thread_id) ? event.thread_id : nil,
+          "channel_id" => event.respond_to?(:channel_id) ? event.channel_id : nil,
+          "raw" => json_safe(event.raw),
+          "timestamp" => event.timestamp&.iso8601
+        }
+      end
+
+      def dump_message(message)
+        return unless message
+
+        {
+          "id" => message.id,
+          "text" => message.text,
+          "author" => dump_author(message.author),
+          "thread_id" => message.thread_id,
+          "channel_id" => message.channel_id,
+          "platform" => message.platform.to_s,
+          "attachments" => json_safe(message.attachments),
+          "links" => json_safe(message.links),
+          "reply_to" => dump_message(message.reply_to),
+          "subject" => json_safe(message.subject),
+          "raw" => json_safe(message.raw),
+          "timestamp" => message.timestamp&.iso8601
+        }
+      end
+
+      def load_message(data)
+        return unless data
+
+        data = data.transform_keys(&:to_s)
+        Message.new(
+          id: data["id"],
+          text: data["text"],
+          author: load_author(data["author"]),
+          thread_id: data["thread_id"],
+          channel_id: data["channel_id"],
+          platform: data["platform"].to_sym,
+          attachments: data["attachments"] || [],
+          links: data["links"] || [],
+          reply_to: load_message(data["reply_to"]),
+          subject: data["subject"],
+          raw: data["raw"],
+          timestamp: parse_time(data["timestamp"])
+        )
+      end
+
+      def dump_author(author)
+        return unless author
+
+        {
+          "id" => author.id,
+          "name" => author.name,
+          "platform" => author.platform.to_s,
+          "bot" => author.bot?,
+          "system" => author.system?,
+          "locale" => author.locale,
+          "email" => author.email,
+          "raw" => json_safe(author.raw)
+        }
+      end
+
+      def load_author(data)
+        return unless data
+
+        data = data.transform_keys(&:to_s)
+        Author.new(
+          id: data["id"],
+          name: data["name"],
+          platform: data["platform"].to_sym,
+          bot: data["bot"],
+          system: data["system"],
+          locale: data["locale"],
+          email: data["email"],
+          raw: data["raw"]
+        )
+      end
+
+      def parse_time(value)
+        Time.iso8601(value) if value
+      end
+
+      def json_safe(value)
+        JSON.parse(JSON.generate(value))
+      rescue JSON::GeneratorError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/message_deleted.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class MessageDeleted < Base
+      attr_reader :message_id, :previous_message, :thread_id, :channel_id, :deleted_at
+      attr_accessor :thread
+
+      def initialize(message_id:, thread_id:, channel_id:, previous_message: nil, deleted_at: nil, **kwargs)
+        super(type: :message_deleted, **kwargs)
+        @message_id = message_id
+        @previous_message = previous_message
+        @thread_id = thread_id
+        @channel_id = channel_id
+        @deleted_at = deleted_at
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/message_updated.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class MessageUpdated < Base
+      attr_reader :message, :previous_message, :thread_id, :channel_id
+
+      def initialize(message:, thread_id:, channel_id:, previous_message: nil, **kwargs)
+        super(type: :message_updated, **kwargs)
+        @message = message
+        @previous_message = previous_message
+        @thread_id = thread_id
+        @channel_id = channel_id
+      end
+    end
+  end
+end

data/lib/chat_sdk/history.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "time"
+require "securerandom"
+
+module ChatSDK
+  class History
+    attr_reader :user, :thread, :channel
+
+    def initialize(chat)
+      @user = UserHistory.new(chat)
+      @thread = ThreadHistory.new(chat)
+      @channel = ChannelHistory.new(chat)
+    end
+
+    class UserHistory
+      def initialize(chat)
+        @chat = chat
+      end
+
+      def append(thread, message, user_key: nil)
+        user_key ||= resolve_user_key(thread, message)
+        return nil unless user_key
+
+        entry = normalize_entry(thread, message, user_key)
+        entries = Array(@chat.state.get(storage_key(user_key)))
+        entries << entry
+        max = @chat.config.history_user[:max_per_user]
+        entries = entries.last(max) if max && max != false
+        @chat.state.set(storage_key(user_key), entries, ttl: @chat.config.history_user[:retention])
+        entry
+      end
+
+      def list(user_key:, limit: 50, platforms: nil, thread_id: nil, roles: nil)
+        entries = Array(@chat.state.get(storage_key(user_key)))
+        entries = entries.select { |entry| Array(platforms).map(&:to_s).include?(entry["platform"].to_s) } if platforms
+        entries = entries.select { |entry| entry["thread_id"] == thread_id } if thread_id
+        entries = entries.select { |entry| Array(roles).map(&:to_s).include?(entry["role"].to_s) } if roles
+        limit ? entries.last(limit) : entries
+      end
+
+      def count(user_key:)
+        Array(@chat.state.get(storage_key(user_key))).length
+      end
+
+      def delete(user_key:)
+        count = Array(@chat.state.get(storage_key(user_key))).length
+        @chat.state.delete(storage_key(user_key))
+        {deleted: count}
+      end
+
+      def to_prompt_entries(entries)
+        entries.map { |entry| {role: entry["role"], content: entry["text"]} }
+      end
+
+      private
+
+      def resolve_user_key(thread, message)
+        resolver = @chat.config.history_user[:identity]
+        return resolver.call(thread, message) if resolver
+        message.author.email if message.is_a?(Message) && message.author&.email
+      rescue => e
+        ChatSDK::Log.warn("History identity resolver failed: #{e.message}")
+        nil
+      end
+
+      def normalize_entry(thread, message, user_key)
+        if message.is_a?(Message)
+          {
+            "id" => SecureRandom.uuid,
+            "platform_message_id" => message.id,
+            "user_key" => user_key,
+            "role" => message.author&.bot? ? "assistant" : "user",
+            "text" => message.text.to_s,
+            "platform" => message.platform.to_s,
+            "thread_id" => thread.id,
+            "timestamp" => (message.timestamp || Time.now).iso8601
+          }
+        else
+          data = message.transform_keys(&:to_sym)
+          {
+            "id" => SecureRandom.uuid,
+            "platform_message_id" => data[:platform_message_id] || data[:id],
+            "user_key" => user_key,
+            "role" => (data[:role] || "assistant").to_s,
+            "text" => data[:text].to_s,
+            "platform" => (data[:platform] || thread.adapter.name).to_s,
+            "thread_id" => thread.id,
+            "timestamp" => (data[:timestamp] || Time.now).iso8601
+          }
+        end
+      end
+
+      def storage_key(user_key)
+        "chat_sdk:history:user:#{user_key}"
+      end
+    end
+
+    class ThreadHistory
+      def initialize(chat)
+        @chat = chat
+      end
+
+      def list(thread, cursor: nil, limit: 50)
+        unless thread.is_a?(ChatSDK::Thread)
+          raise ArgumentError, "thread history requires a ChatSDK::Thread"
+        end
+
+        messages, next_cursor = thread.adapter.fetch_messages(
+          channel_id: thread.channel_id,
+          thread_id: thread.id,
+          cursor: cursor,
+          limit: limit
+        )
+        {messages: messages, next_cursor: next_cursor}
+      end
+    end
+
+    class ChannelHistory
+      def initialize(chat)
+        @chat = chat
+      end
+
+      def list_messages(channel, cursor: nil, limit: 50)
+        unless channel.is_a?(ChatSDK::Channel)
+          raise ArgumentError, "channel history requires a ChatSDK::Channel"
+        end
+
+        messages, next_cursor = channel.adapter.fetch_channel_messages(
+          channel_id: channel.id,
+          cursor: cursor,
+          limit: limit
+        )
+        {messages: messages, next_cursor: next_cursor}
+      end
+
+      def list_threads(channel, cursor: nil, limit: 50)
+        unless channel.is_a?(ChatSDK::Channel)
+          raise ArgumentError, "channel history requires a ChatSDK::Channel"
+        end
+
+        threads, next_cursor = channel.adapter.list_threads(
+          channel_id: channel.id,
+          cursor: cursor,
+          limit: limit
+        )
+        {threads: threads, next_cursor: next_cursor}
+      end
+    end
+  end
+end

data/lib/chat_sdk/message.rb

@@ -3,10 +3,10 @@
 module ChatSDK
   class Message
     attr_reader :id, :text, :author, :thread_id, :channel_id,
-      :platform, :attachments, :raw, :timestamp
+      :platform, :attachments, :links, :reply_to, :subject, :raw, :timestamp
 
     def initialize(id:, text:, author:, thread_id:, channel_id:, platform:,
-      attachments: [], raw: nil, timestamp: nil)
+      attachments: [], links: [], reply_to: nil, subject: nil, raw: nil, timestamp: nil)
       @id = id
       @text = text
       @author = author
@@ -14,6 +14,9 @@ module ChatSDK
       @channel_id = channel_id
       @platform = platform
       @attachments = attachments
+      @links = links
+      @reply_to = reply_to
+      @subject = subject
       @raw = raw
       @timestamp = timestamp
     end