ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/active_record/chat_methods.rb

@@ -2,6 +2,18 @@
 
 require 'active_support/concern'
 require 'ruby_llm/active_record/attachment_helpers'
+require 'ruby_llm/active_record/claim_heartbeat'
+require 'ruby_llm/active_record/run_claims'
+require 'ruby_llm/active_record/chat_approvals'
+require 'ruby_llm/active_record/chat_questions'
+require 'ruby_llm/active_record/chat_cancellation'
+require 'ruby_llm/active_record/chat_placeholders'
+require 'ruby_llm/active_record/chat_reply_error'
+require 'ruby_llm/active_record/system_instructions'
+require 'ruby_llm/active_record/chat_queue'
+require 'ruby_llm/active_record/chat_tool_call_state'
+require 'ruby_llm/active_record/chat_run'
+require 'ruby_llm/active_record/chat_agent_hooks'
 
 module RubyLLM
   module ActiveRecord
@@ -13,22 +25,57 @@ module RubyLLM
     #     acts_as_chat
     #   end
     #
-    #   chat = Chat.create!(model: 'gpt-5.6-luna')
+    #   chat = Chat.create!(model: 'gpt-6-luna')
     #   chat.ask "What is the capital of France?"
     #   chat.messages.count # => 2
     #
     module ChatMethods
       extend ActiveSupport::Concern
-      include Enumerable
+      include RubyLLM::Support::DeprecatedEnumerable
       include AttachmentHelpers
+      include RunClaims
+      include ChatApprovals
+      include ChatQuestions
+      include ChatCancellation
+      include ChatPlaceholders
+      include ChatReplyError
+      include SystemInstructions
+      prepend ChatAgentHooks
 
       CANCELLATION_POLL_INTERVAL = 1.0 # :nodoc:
       COMPLETION_ERRORS = [ # :nodoc:
-        RubyLLM::CancelledError, RubyLLM::Error, Faraday::Error, Timeout::Error, Errno::ETIMEDOUT
+        CancelledError, Error, ConfigurationError, Faraday::Error, Timeout::Error, Errno::ETIMEDOUT
       ].freeze
 
+      ##
+      # :singleton-method: interrupted
+      #
+      # Returns the chats whose run died holding its claim: a crash, or a
+      # deploy that stopped the process, left the claim behind, and its
+      # lease has expired. A run that ends any other way releases its
+      # claim, whether it completes, pauses on a question or a task, is
+      # cancelled, or fails, so none of those chats are returned, nor a
+      # chat whose job hasn't started yet, nor one someone stopped. No job
+      # backend runs such a reply again by itself, so a recurring job
+      # completes them:
+      #
+      #   Chat.interrupted.find_each { |chat| ChatResponseJob.perform_later(chat.id) }
+      #
+      # Chains with other scopes. Returns none when the chats table has no
+      # claim columns, since then no process records that it runs a chat.
+
       included do
+        scope :interrupted, -> { RunClaims.interrupted(self) }
         before_save :resolve_model
+        after_commit :remember_model_registry_stored, if: -> { @model_registry_loaded_into }
+        after_rollback -> { @model_registry_loaded_into = nil }
+      end
+
+      # Returns the record's attributes as a Hash, accepting the same options
+      # as any Active Record model, rather than the message list Enumerable
+      # would serialize.
+      def as_json(options = nil)
+        ActiveModel::Serializers::JSON.instance_method(:as_json).bind_call(self, options)
       end
 
       # When +true+, skips the model registry lookup so unregistered model ids
@@ -38,24 +85,27 @@ module RubyLLM
       # Overrides the wire protocol the provider would pick for the model, such
       # as +:responses+ or +:chat_completions+ for OpenAI, or +nil+ for the
       # provider default. Not persisted; set it again after reloading the record.
-      attr_accessor :protocol
+      attr_reader :protocol
 
-      # An optional RubyLLM::Context supplying per-chat configuration, used
-      # when building the underlying chat. Not persisted; set it again after
-      # reloading the record.
-      attr_accessor :context
+      # Sets the protocol override, switching the underlying chat to it when
+      # that is already built.
+      def protocol=(value)
+        @protocol = value
+        @chat_model_stale = true if @chat
+      end
 
-      # Requests cancellation of the current in-flight chat operation. The
-      # request is persisted so a background job can observe it from another
-      # process.
-      def cancel
-        if persisted?
-          update_column(:cancelled, true)
-        else
-          self[:cancelled] = true
-        end
+      # An optional RubyLLM::Context supplying per-chat configuration. Not
+      # persisted; set it again after reloading the record. Assigning one
+      # rebinds the underlying chat, like #with_context.
+      attr_reader :context
 
-        @chat&.cancel
+      # Requests cancellation of the current in-flight chat operation, or of
+      # the run that will answer a message still waiting for one. The request
+      # is persisted so a background job can observe it from another process.
+      # Does nothing when no run holds the chat and nothing waits to run.
+      # Returns +self+.
+      def cancel
+        request_cancellation
         self
       end
 
@@ -65,56 +115,84 @@ module RubyLLM
         @chat&.cancelled? || self[:cancelled]
       end
 
-      # Records approval for +tool_call+ (a ToolCall, a tool call record, or
-      # an id) on the persisted tool call, so the next #complete executes it
-      # from any process. Returns +self+.
+      # Records approval for +tool_call+ (an approval RubyLLM::Question, a
+      # ToolCall, a tool call record, or an id) on the persisted tool call,
+      # so the next #complete executes it from any process. Approving a call
+      # that is running or answered changes nothing. With
+      # <tt>remember: true</tt>, later calls to the same tool run without
+      # asking for the rest of the chat, as RubyLLM::Chat#approve describes,
+      # in every process. Returns +self+.
       #
       #   chat.approve(params[:tool_call_id])
+      #   chat.approve(params[:tool_call_id], remember: true)
       #   CompleteJob.perform_later(chat.id)
       #
-      def approve(tool_call)
-        record_tool_call_decision(tool_call, 'approved')
-      end
-
-      # Records denial for +tool_call+ (a ToolCall, a tool call record, or
-      # an id) on the persisted tool call. The next #complete appends a
-      # structured denial result instead of executing the tool. Returns
-      # +self+.
-      def deny(tool_call)
-        record_tool_call_decision(tool_call, 'denied')
+      def approve(tool_call, remember: false)
+        record = tool_call_record(RubyLLM::Question.decided_call(tool_call, 'answer'))
+        to_llm.approve(record.to_llm, remember:) if record.result_id.nil?
+        record_tool_call_decision(record, remember ? 'remembered' : 'approved')
+        self
       end
 
-      # Returns whether the conversation is waiting on tool calls that
-      # require approval and have no recorded decision. See
-      # RubyLLM::Chat#awaiting_approval?.
-      def awaiting_approval?
-        to_llm.awaiting_approval?
+      def claiming_delivery(&) # :nodoc:
+        exclusively(-> { false }) { transaction(requires_new: true, &) }
       end
 
-      # Returns the persisted tool call records that require approval and
-      # have no recorded decision, ready to render as approval cards. Pass
-      # a record (or its tool_call_id) to #approve or #deny.
-      # A record's +remote?+ identifies a provider-executed call.
+      # Returns whether a process is running this chat's conversation loop:
+      # calling the model or running tools from #complete, #step, #generate,
+      # #run_tools, or #compact. Reads the database, so it sees runs in
+      # other processes. While another process runs the chat, those methods
+      # return without doing anything and #waiting? is +true+. A process
+      # that dies stops counting as running within a minute.
       #
-      #   chat.pending_approvals.each { |record| render record }
+      #   retry_job wait: 1.minute if chat.running?
       #
-      def pending_approvals
-        ids = to_llm.pending_approvals.map(&:id)
-        RubyLLM::ActiveRecord::ToolCall.where(
-          tool_call_id: ids,
-          message_type: self.class.message_class.constantize.polymorphic_name,
+      def running?
+        return false unless run_claims?
+
+        claimed_until = self.class.uncached { chat_row.pick(:claimed_until) }
+        claimed_until&.future? || false
+      end
+
+      # Returns whether the conversation can't continue until something
+      # outside it happens, as RubyLLM::Chat#waiting? describes, or until
+      # the process that is #running? it finishes. Approvals, answers, and
+      # tasks persist on their tool calls, so any process sees what the
+      # chat waits on.
+      def waiting?
+        to_llm.waiting? || running_elsewhere?
+      end
+
+      def messages_association # :nodoc:
+        association(messages_association_name).reader
+      end
+
+      def find_tool_call(tool_call_id) # :nodoc:
+        RubyLLM::ActiveRecord::ToolCall.find_by(
+          tool_call_id: tool_call_id,
+          message_type: messages_association.klass.polymorphic_name,
           message_id: messages_association.select(:id)
         )
       end
 
-      def messages_association # :nodoc:
-        send(messages_association_name)
+      def persist_usage_entry(entry) # :nodoc:
+        usage_records_by_entry[entry] = Usage.transaction(requires_new: true) do
+          ruby_llm_usages.create!(Usage.attributes_for(entry))
+        end
+      rescue StandardError => e
+        RubyLLM.logger.warn("RubyLLM could not record #{entry.operation} usage: #{e.class}: #{e.message}")
+      end
+
+      def refresh_messages # :nodoc:
+        messages_association.reset
+        reload_usages
+        sync_messages if @chat
       end
 
       # Sets the chat's model from an id, a RubyLLM::Model value, or the
       # associated internal model record.
       #
-      #   chat.model = 'gpt-5.6-luna'
+      #   chat.model = 'gpt-6-luna'
       #
       def model=(value)
         if value.is_a?(RubyLLM::ActiveRecord::Model)
@@ -125,47 +203,59 @@ module RubyLLM
           @pending_model_id = value.respond_to?(:id) ? value.id : value
           @pending_provider = value.provider if value.respond_to?(:provider)
         end
+        @chat_model_stale = true if @chat
       end
 
       # Stores +value+ as the model id, resolved to a model record before save.
       def model_id=(value)
-        @pending_model_id = value
+        self.model = value
       end
 
-      # Returns the model id of the associated model record, or +nil+.
+      # Returns the model id assigned since the last save, or that of the
+      # associated model record, or +nil+.
       #
-      #   chat.model_id # => "gpt-5.6-luna"
+      #   chat.model_id # => "gpt-6-luna"
       #
       def model_id
-        model&.model_id || @pending_model_id
+        @pending_model_id || model&.model_id
       end
 
       # Stores +value+ as the provider used when resolving the model id
       # before save.
       def provider=(value)
         @pending_provider = value
+        @chat_model_stale = true if @chat
       end
 
-      # Returns the provider of the associated model record, or +nil+.
+      # Returns the provider assigned since the last save, or that of the
+      # associated model record, or +nil+. A model id assigned without a
+      # provider has none until save resolves it.
       def provider
-        model&.provider || @pending_provider
+        @pending_provider || (model&.provider unless @pending_model_id)
       end
 
       # Returns the underlying RubyLLM::Chat for this record, building it on
       # first call and memoizing it. The chat is loaded with the persisted
       # messages and wired to persist new ones. Subsequent calls return the
-      # same chat without touching the database; use #reload to refresh its
-      # message history from the record.
+      # same chat without touching the database, switched to any model
+      # assigned since; use #reload to refresh its message history from the
+      # record.
       def to_llm
-        @chat ||= build_llm_chat # rubocop:disable Naming/MemoizedInstanceVariableName
+        @chat ||= build_llm_chat
+        @chat.with_model(model_id, provider: provider&.to_sym, protocol:, assume_model_exists:) if @chat_model_stale
+        @chat_model_stale = false
+        @chat
       end
 
       # Reloads the record from the database, Rails-style, and refreshes the
-      # underlying chat's persisted message history to match. Runtime-only
-      # configuration such as tools, temperature, and callbacks is preserved.
+      # underlying chat's model and persisted message history to match. Runtime-only
+      # configuration such as tools, temperature, and callbacks is preserved;
+      # a model or provider assigned since the last save is discarded.
       # Returns +self+.
       def reload(...)
         super
+        @pending_model_id = @pending_provider = nil
+        @chat_model_stale = true if @chat && chat_model_moved?
         sync_messages if @chat
         self
       end
@@ -175,10 +265,11 @@ module RubyLLM
       # configuration. The Context itself is runtime-only and is not
       # persisted.
       def with_context(value)
-        self.context = value
+        @context = value
         @chat&.with_context(value)
         self
       end
+      alias context= with_context
 
       # Sets the system instructions, persisting them as a message with the
       # +:system+ role. Replaces any persisted system messages unless
@@ -213,13 +304,13 @@ module RubyLLM
       # RubyLLM::Chat. Each behaves exactly as documented on RubyLLM::Chat,
       # then returns the record so calls chain.
       CHAINABLE_CHAT_DELEGATES = %i[
-        with_tools with_mcp with_tool_options with_provider_tools with_fallbacks with_temperature answer decline
+        with_tools with_mcp with_tool_options with_provider_tools with_fallbacks with_temperature
         with_max_output_tokens with_thinking with_citations with_caching
-        with_end_user with_compaction
+        with_end_user with_owner with_compaction with_context_budget with_code_execution with_skills
         with_provider_options with_headers with_schema
         convert_unsupported_attachments
-        before_request before_message after_message before_tool_call after_tool_result after_tool_progress
-        before_fallback after_fallback
+        before_request before_message after_message before_tool_call around_tool_call after_tool_result
+        after_tool_progress before_fallback after_fallback around_join after_file_write
       ].freeze
 
       ##
@@ -234,19 +325,6 @@ module RubyLLM
       #
       # Applies Chat#with_mcp and returns this record.
 
-      ##
-      # :method: answer
-      # :call-seq: answer(request, **values)
-      #
-      # Applies Chat#answer and returns this record. The answer persists
-      # on the tool call, so any process can resume the call.
-
-      ##
-      # :method: decline
-      # :call-seq: decline(request)
-      #
-      # Applies Chat#decline and returns this record.
-
       ##
       # :method: with_tool_options
       # :call-seq: with_tool_options(**options)
@@ -261,7 +339,7 @@ module RubyLLM
 
       ##
       # :method: with_fallbacks
-      # :call-seq: with_fallbacks(*models, on: Fallback::DEFAULT_ERRORS)
+      # :call-seq: with_fallbacks(*models, on: Fallback::DEFAULT_ERRORS, drop_unsupported: false)
       #
       # Applies Chat#with_fallbacks and returns this record.
 
@@ -301,12 +379,48 @@ module RubyLLM
       #
       # Applies Chat#with_end_user and returns this record.
 
+      ##
+      # :method: with_owner
+      # :call-seq: with_owner(owner)
+      #
+      # Applies Chat#with_owner and returns this record. For this record
+      # instance, the owner wins over the association +acts_as_chat owner:+
+      # names, both for usage and for the files of the Active Storage
+      # store. It is not persisted, so a record loaded later works for that
+      # association again. Read it with <tt>to_llm.owner</tt>: the record
+      # defines no +owner+, so an association of yours by that name keeps
+      # working.
+
+      ##
+      # :method: with_context_budget
+      # :call-seq: with_context_budget(budget = {}, per_result: nil, per_request: nil, window: nil)
+      #
+      # Applies Chat#with_context_budget and returns this record.
+
       ##
       # :method: with_compaction
       # :call-seq: with_compaction(options = {})
       #
       # Applies Chat#with_compaction and returns this record.
 
+      ##
+      # :method: with_code_execution
+      # :call-seq: with_code_execution(enabled = true, **options)
+      #
+      # Applies Chat#with_code_execution and returns this record.
+
+      ##
+      # :method: with_skills
+      # :call-seq: with_skills(*skills)
+      #
+      # Applies Chat#with_skills and returns this record.
+
+      ##
+      # :method: after_file_write
+      # :call-seq: after_file_write(&block)
+      #
+      # Applies Chat#after_file_write and returns this record.
+
       ##
       # :method: with_provider_options
       # :call-seq: with_provider_options(provider_options)
@@ -361,6 +475,12 @@ module RubyLLM
       #
       # Applies Chat#after_tool_result and returns this record.
 
+      ##
+      # :method: around_tool_call
+      # :call-seq: around_tool_call(&block)
+      #
+      # Applies Chat#around_tool_call and returns this record.
+
       ##
       # :method: after_tool_progress
       # :call-seq: after_tool_progress(&block)
@@ -379,6 +499,25 @@ module RubyLLM
       #
       # Applies Chat#after_fallback and returns this record.
 
+      ##
+      # :method: around_join
+      # :call-seq: around_join(&block)
+      #
+      # Applies Chat#around_join and returns this record. The block
+      # receives the QueuedMessage record and +join+, in the process that
+      # runs the chat, inside the transaction that creates the message
+      # record and deletes the queued one. <tt>join.call</tt> takes
+      # attributes for the new message record and returns it, so the
+      # record is saved with your own columns set:
+      #
+      #   chat.around_join do |queued, join|
+      #     join.call(steered: queued.steer?)
+      #   end
+      #
+      # When the block raises, the transaction rolls back and the message
+      # stays queued. When it never calls +join+, the queued record is
+      # deleted without joining.
+
       ##
       # :method: caching
       # :call-seq: caching
@@ -391,12 +530,36 @@ module RubyLLM
       #
       # Delegates to Chat#citations. See that method for arguments and return values.
 
+      ##
+      # :method: code_execution
+      # :call-seq: code_execution
+      #
+      # Delegates to Chat#code_execution. See that method for arguments and return values.
+
+      ##
+      # :method: skills
+      # :call-seq: skills
+      #
+      # Delegates to Chat#skills. See that method for arguments and return values.
+
+      ##
+      # :method: file_store
+      # :call-seq: file_store
+      #
+      # Delegates to Chat#file_store. See that method for arguments and return values.
+
       ##
       # :method: compaction
       # :call-seq: compaction
       #
       # Delegates to Chat#compaction. See that method for arguments and return values.
 
+      ##
+      # :method: context_budget
+      # :call-seq: context_budget
+      #
+      # Delegates to Chat#context_budget. See that method for arguments and return values.
+
       ##
       # :method: concurrency
       # :call-seq: concurrency
@@ -481,32 +644,6 @@ module RubyLLM
       #
       # Delegates to Chat#mcp. See that method for arguments and return values.
 
-      ##
-      # :method: waiting?
-      # :call-seq: waiting?
-      #
-      # Delegates to Chat#waiting?. Approvals, answers, and tasks persist on
-      # their tool calls, so any process sees what the chat waits on.
-
-      ##
-      # :method: awaiting_input?
-      # :call-seq: awaiting_input?
-      #
-      # Delegates to Chat#awaiting_input?. See that method for arguments and return values.
-
-      ##
-      # :method: pending_inputs
-      # :call-seq: pending_inputs
-      #
-      # Delegates to Chat#pending_inputs. Requests persist on their tool
-      # calls, so they survive restarts.
-
-      ##
-      # :method: awaiting_tasks?
-      # :call-seq: awaiting_tasks?
-      #
-      # Delegates to Chat#awaiting_tasks?. See that method for arguments and return values.
-
       ##
       # :method: pending_tasks
       # :call-seq: pending_tasks
@@ -526,9 +663,11 @@ module RubyLLM
       # The public methods behave as documented on RubyLLM::Chat.
 
       PASSTHROUGH_CHAT_DELEGATES = %i[
-        caching citations compaction concurrency end_user fallbacks headers max_output_tokens provider_options
-        schema provider_tools temperature thinking tool_options tools deferred_tools mcp waiting? awaiting_input?
-        pending_inputs awaiting_tasks? pending_tasks add_completion count_tokens each render
+        caching citations code_execution compaction context_budget concurrency end_user fallbacks headers
+        max_output_tokens provider_options schema provider_tools temperature thinking tool_options tools deferred_tools
+        mcp skills file_store
+        pending_tasks add_completion count_tokens
+        render
       ].freeze
 
       ##
@@ -538,12 +677,6 @@ module RubyLLM
       # Returns the number of input tokens the next request would carry,
       # counted by the provider over the persisted conversation.
 
-      ##
-      # :method: each
-      # :call-seq: each(&block)
-      #
-      # Yields each message in the conversation. Returns an Enumerator without a block.
-
       ##
       # :method: render
       # :call-seq: render
@@ -573,7 +706,7 @@ module RubyLLM
         self.assume_model_exists = assume_model_exists
         resolve_model
         save!
-        to_llm.with_model(model_id, provider: provider&.to_sym, protocol:, assume_model_exists:)
+        to_llm
         self
       end
 
@@ -585,38 +718,52 @@ module RubyLLM
       #   chat.add_message(role: :user, content: long_context)
       #
       def add_message(message_or_attributes)
-        llm_message = message_or_attributes
-        llm_message = llm_message.to_llm if llm_message.respond_to?(:to_llm)
-        llm_message = RubyLLM::Message.new(llm_message) unless llm_message.is_a?(RubyLLM::Message)
+        persist_message(message_or_attributes)
+      end
 
-        message_record = messages_association.create!(message_attributes(llm_message))
+      # Persists +message_or_attributes+ like #add_message, assigning
+      # +record_attributes+ to the new record. Returns the message record.
+      def persist_message(message_or_attributes, record_attributes = {}) # :nodoc:
+        llm_message = to_llm.prepare_message(message_or_attributes) do |id|
+          RubyLLM::ActiveRecord::ToolCall.exists?(tool_call_id: id)
+        end
+
+        message_record = create_message_record(llm_message, record_attributes)
+        @last_message_id = message_record.id
 
-        if llm_message.tool_call_id && (tool_call = find_tool_call(llm_message.tool_call_id))
+        tool_call = find_tool_call(llm_message.tool_call_id) if llm_message.tool_call_id
+        if tool_call && tool_call.result_id.nil?
+          tool_call.mcp_result = llm_message.mcp_result&.dump if tool_call.has_attribute?(:mcp_result)
           tool_call.update!(result: message_record)
         end
 
         persist_content(message_record, llm_message.attachments) if llm_message.attachments.any?
         persist_tool_calls(llm_message.tool_calls, message_record:) if llm_message.tool_calls.present?
 
-        @chat&.add_message(llm_message)
+        @chat.add_message(llm_message)
 
-        message_record
+        bind_message_chat(message_record)
       end
 
-      # Marks the latest persisted message as a prompt cache boundary, or the
-      # latest in-memory message when none is persisted yet. Pass +ttl:+ to
-      # give the boundary its own cache lifetime. Returns +self+.
+      # Deprecated: mark the message itself, or pass +cache_until_here:+ to
+      # #with_instructions. Marks the latest persisted message as a prompt
+      # cache boundary, or the latest in-memory message when none is
+      # persisted yet. Warns through RubyLLM.deprecator. RubyLLM 3.0 removes
+      # it. Returns +self+.
       #
-      #   chat.with_instructions('Reusable analysis prompt').cache_until_here
-      #   chat.with_instructions('Reusable analysis prompt').cache_until_here(ttl: "1h")
+      #   chat.with_instructions('Reusable analysis prompt', cache_until_here: { ttl: "1h" })
+      #   chat.add_message(role: :user, content: long_context).cache_until_here
       #
       # Raises ArgumentError if the chat has no messages.
       def cache_until_here(ttl: nil)
+        RubyLLM.deprecator.deprecate("#{self.class}#cache_until_here",
+                                     replacement: 'Message#cache_until_here or with_instructions(cache_until_here:)',
+                                     removal: '3.0')
         message_record = messages_association.order(:id).last
         if message_record
-          message_record.cache_until_here(ttl:)
+          bind_message_chat(message_record).cache_until_here(ttl:)
         elsif @chat&.messages&.any?
-          @chat.cache_until_here(ttl:)
+          @chat.messages.last.cache_until_here(ttl:)
         else
           raise ArgumentError, 'No messages to cache'
         end
@@ -643,9 +790,16 @@ module RubyLLM
         RubyLLM::Cost.aggregate(records.map(&:cost), complete: records.all?(&:cost_available?))
       end
 
-      # Persists +message+ as a user message, then runs the conversation loop
-      # and returns the latest assistant RubyLLM::Message. The loop pauses
-      # when #awaiting_approval? is true. Yields streaming chunks to a block.
+      def ruby_llm_usage_entries # :nodoc:
+        records = ruby_llm_usages.to_a
+        ::ActiveRecord::Associations::Preloader.new(records:, associations: [:message, *Usage.owner_preload]).call
+        records.map(&:to_entry)
+      end
+
+      # Persists +message+ as a user message, after every queued message
+      # (see #queue), then runs the conversation loop and returns the latest
+      # assistant RubyLLM::Message. The loop pauses while a call waits on a
+      # person (see #pending_questions). Yields streaming chunks to a block.
       #
       #   chat.ask "What is the capital of France?"
       #   chat.ask "What's in this file?", with: "diagram.png"
@@ -657,14 +811,39 @@ module RubyLLM
 
       alias say ask
 
+      # Deprecated: iterate <tt>to_llm.messages</tt> for the same objects, or
+      # the message association for your records. Yields each RubyLLM::Message
+      # in the conversation, or returns an Enumerator without a block. The
+      # Enumerable methods built on it, such as +map+ and +count+, are
+      # deprecated with it. Warns through RubyLLM.deprecator. RubyLLM 3.0
+      # removes them.
+      def each(&)
+        RubyLLM.deprecator.deprecate("Enumerable on #{self.class}", replacement: "#{self.class}#to_llm.messages",
+                                                                    removal: '3.0')
+        to_llm.messages.each(&)
+      end
+
       # Persists +message+ as a user message without calling the model, so
-      # #complete can run later. Returns +self+.
+      # #complete can run later, usually in a job. Every queued message (see
+      # #queue) is persisted first, in order. Returns +self+.
       #
-      #   chat.ask_later "Summarize this document."
-      #   chat.complete
+      #   chat.ask_later params[:content]
+      #   ChatResponseJob.perform_later(chat.id)
       #
+      # While a run holds the chat, in this process or another, the message
+      # is queued instead, as #queue does, so the transcript that run writes
+      # stays whole. The run takes it at its next step, or the next
+      # #complete does. An MCP::Prompt, which the queue can't hold, is
+      # persisted either way.
+      #
+      # Raises PendingToolCallsError while the last response has tool calls
+      # waiting for their results and no run holds the chat.
       def ask_later(message = nil, with: nil)
+        return tap { queue(message, with:) } if running? && !message.is_a?(RubyLLM::MCP::Prompt)
+
         to_llm.raise_if_pending_tool_calls!
+        to_llm.raise_if_prompt_attachments!(message, with)
+        to_llm.take_queued_messages
         if message.is_a?(RubyLLM::MCP::Prompt)
           message.messages.each { |prompt_message| add_message(prompt_message) }
         else
@@ -675,41 +854,39 @@ module RubyLLM
 
       # Makes a single generation attempt, persists the response, and returns it as a
       # RubyLLM::Message. Tool calls in the response are not executed. See
-      # RubyLLM::Chat#generate.
-      def generate(...)
-        to_llm.generate(...)
-      rescue *COMPLETION_ERRORS => e
-        cleanup_after_failure(e)
-        raise
+      # RubyLLM::Chat#generate. Returns +nil+ without calling the model
+      # while another process is #running? the chat. A block receives the
+      # chunks as it does in #complete.
+      def generate(&block)
+        exclusively(-> {}) { completing(block) { |on_chunk| to_llm.generate(&on_chunk) } }
       end
 
       # Compacts the model context and persists its assistant Message without
-      # deleting earlier messages. See RubyLLM::Chat#compact.
+      # deleting earlier messages. See RubyLLM::Chat#compact. Returns +nil+
+      # without calling the model while another process is #running? the
+      # chat.
       def compact
-        to_llm.compact
-      rescue *COMPLETION_ERRORS => e
-        cleanup_after_failure(e)
-        raise
+        exclusively(-> {}) { completing { to_llm.compact } }
       end
 
       # Executes the pending tool calls and persists their results without
-      # calling the model. See RubyLLM::Chat#run_tools. Returns +self+.
+      # calling the model. See RubyLLM::Chat#run_tools. Does nothing while
+      # another process is #running? the chat. Returns +self+.
       def run_tools
-        to_llm.run_tools
+        exclusively(-> {}) { to_llm.run_tools }
         self
       end
 
       # Advances the conversation by one move: runs the pending tool calls if
       # there are any, otherwise generates a response. Returns +nil+ once the
-      # chat is complete or #waiting?. See RubyLLM::Chat#step.
+      # chat is complete or #waiting?, including while another process is
+      # #running? it. See RubyLLM::Chat#step. A block receives the chunks as
+      # it does in #complete.
       #
       #   chat.step until chat.complete? || chat.waiting?
       #
-      def step(...)
-        to_llm.step(...)
-      rescue *COMPLETION_ERRORS => e
-        cleanup_after_failure(e)
-        raise
+      def step(&block)
+        exclusively(-> {}) { completing(block) { |on_chunk| to_llm.step(&on_chunk) } }
       end
 
       # Returns whether the conversation has no pending work, neither a
@@ -720,31 +897,159 @@ module RubyLLM
       end
 
       # Runs the completion loop on the underlying chat, persisting each
-      # message, and returns the latest RubyLLM::Message. Pauses when a tool
-      # requires approval. When the API call fails, destroys the empty assistant
-      # message and any orphaned tool results, then re-raises the error.
-      def complete(...)
-        to_llm.complete(...)
-      rescue *COMPLETION_ERRORS => e
-        cleanup_after_failure(e)
+      # message, and returns the latest RubyLLM::Message. Pauses while a call
+      # waits on a person (see #pending_questions). When the API call fails,
+      # destroys the empty assistant message and any orphaned tool results,
+      # then re-raises the error. When the block raises, destroys the empty
+      # assistant message and re-raises. Tool calls paused on a task or a
+      # question stay, so the next #complete picks them up.
+      #
+      # Only one process runs a chat at a time. While another process is
+      # #running? it, returns the latest message without calling the model
+      # or running tools, and #waiting? is +true+. Work recorded while this
+      # process ran, such as an approval, continues before it returns. A job
+      # that finds the chat running tries again later, which also covers a
+      # process that dies, since its claim expires within a minute:
+      #
+      #   def perform(chat_id)
+      #     chat = ChatAgent.find(chat_id)
+      #     chat.complete(&:broadcast)
+      #     retry_job wait: 1.minute if chat.running?
+      #   end
+      #
+      # Each chunk passed to the block also answers +message+, the record
+      # it streams into, and +broadcast+ (see ChunkMethods). When the
+      # messages broadcast with Turbo, the chat's page refreshes once the
+      # run ends.
+      #
+      # Queued messages join as RubyLLM::Chat#complete describes, including
+      # those another process queues while this one runs. A message that
+      # steers, queued as the run ends, starts another loop before
+      # #complete returns. When #cancel stops the run while messages wait
+      # in the queue, the run goes on with them before #complete returns,
+      # as the next #complete would. It raises CancelledError when none
+      # wait, or when the stop came before the run began.
+      #
+      # When the chats table has a +reply_error+ column, a failed reply
+      # saves a short message for the person there before the error is
+      # raised, and the next run clears it, so the chat's page can show it
+      # whenever it loads. The message comes from I18n:
+      # +ruby_llm.reply_error.too_long+ for ContextLengthExceededError,
+      # +ruby_llm.reply_error.failed+ for any other error, with English
+      # defaults.
+      def complete(&block)
+        operation = :complete
+        loop do
+          busy = stopped_before_run = false
+          response = exclusively(-> { busy = true }) do
+            stopped_before_run = self[:cancelled]
+            clear_reply_error
+            completing(block) { |on_chunk| to_llm.public_send(operation, &on_chunk) }
+          end
+          return latest_message if busy
+          return response unless work_arrived_during_run?
+
+          operation = :continue_turn
+        rescue CancelledError
+          raise if stopped_before_run || ChatQueue.new(self).none?
+
+          operation = :complete
+        end
+      rescue StandardError => e
+        record_reply_error(e)
         raise
+      ensure
+        broadcast_refresh_to(self, request_id: nil) if broadcasts_messages?
+      end
+
+      # Queues +message+ in the chat's +ruby_llm_queued_messages+ table, as
+      # RubyLLM::Chat#queue describes, and returns the QueuedMessage record.
+      # Attachments given with +with:+ are stored with Active Storage and
+      # move to the message it becomes. +sender+ is any record, such as the
+      # user who asked. It is stored, and when your message model has a
+      # +sender+ association that can hold it, the message record is saved
+      # with it.
+      #
+      # Any process can queue a message. The process that runs the chat
+      # takes it at its next step; when none is running, run #complete,
+      # usually in a job. #ask_later queues for you while a run holds the
+      # chat, so reach for #queue when a message should wait for the turn
+      # to end (<tt>steer: false</tt>) or keep its +sender+.
+      #
+      #   chat.queue params[:content], sender: Current.user
+      #   ChatResponseJob.perform_later(chat.id)
+      #
+      def queue(message = nil, with: nil, steer: true, sender: nil)
+        to_llm.queue(message, with:, steer:, sender:)
+      end
+
+      # Returns the QueuedMessage records waiting in the queue, oldest
+      # first, ready to render.
+      def queued_messages = ruby_llm_queued_messages.scope.skip_query_cache!
+
+      # Takes +queued+, a QueuedMessage record or its id, out of the queue
+      # and deletes its attachments. Returns +true+, or +false+ once the
+      # loop has taken it into the conversation or it was withdrawn already.
+      # QueuedMessage#withdraw does the same from the record. See
+      # RubyLLM::Chat#withdraw.
+      def withdraw(queued)
+        to_llm.withdraw(queued)
+      end
+
+      # Persists every queued message as a user message record, without
+      # calling the model, and returns the records, oldest first. Each joins
+      # through #around_join and runs #after_message, as
+      # RubyLLM::Chat#join_queued_messages describes.
+      #
+      #   chat.join_queued_messages.map(&:content) # => ["Use the EU file"]
+      #
+      def join_queued_messages
+        to_llm.join_queued_messages
       end
 
       private
 
-      def persist_usage_entry(entry)
-        usage_records_by_entry[entry] = Usage.transaction(requires_new: true) do
-          ruby_llm_usages.create!(Usage.attributes_for(entry))
+      def create_message_record(llm_message, record_attributes)
+        transaction do
+          forget_stale_cancellation if llm_message.role == :user
+          messages_association.create!(message_attributes(llm_message).merge(record_attributes))
         end
-      rescue StandardError => e
-        RubyLLM.logger.warn("RubyLLM could not record #{entry.operation} usage: #{e.class}: #{e.message}")
+      end
+
+      def broadcasts_messages?
+        message_class = messages_association.klass
+        message_class.include?(MessageBroadcasting) && message_class.broadcasting?
+      end
+
+      def completing(block = nil)
+        yield ChunkMethods.streaming(block, on_error: method(:cleanup_after_block_failure)) { @message }
+      rescue *COMPLETION_ERRORS => e
+        cleanup_after_failure(e)
+        raise
+      end
+
+      def chat_model_moved?
+        [@chat.model.id, @chat.provider.slug] != [model_id, provider.to_s]
+      end
+
+      def latest_message
+        to_llm.messages.reverse.find { |message| message.role != :system } || to_llm.messages.last
+      end
+
+      def bind_message_chat(message)
+        message.association(message.chat_association_name).target = self
+        message
       end
 
       def link_usage_entries(message)
-        message.ruby_llm_usage_entries.each do |entry|
-          record = usage_records_by_entry[entry]
-          record&.update!(message: @message)
+        Usage.transaction(requires_new: true) do
+          message.ruby_llm_usage_entries.each do |entry|
+            record = usage_records_by_entry[entry]
+            record&.update!(message: @message)
+          end
         end
+      rescue StandardError => e
+        RubyLLM.logger.warn("RubyLLM could not link usage to message #{@message.id}: #{e.class}: #{e.message}")
       end
 
       def usage_records_by_entry
@@ -754,7 +1059,7 @@ module RubyLLM
       def resolve_model
         config = context&.config || RubyLLM.config
         @pending_model_id ||= config.default_model unless model
-        return unless @pending_model_id
+        return unless @pending_model_id || (@pending_provider && model)
 
         model_info = resolve_model_info
 
@@ -771,25 +1076,34 @@ module RubyLLM
         begin
           find_registered_model
         rescue RubyLLM::ModelNotFoundError
-          RubyLLM::Model.default(@pending_model_id, @pending_provider)
+          RubyLLM::Model.default(model_id, @pending_provider)
         end
       end
 
       def find_registered_model
-        RubyLLM.models.find(@pending_model_id, provider: @pending_provider, config: context&.config)
+        RubyLLM.models.find_configured(model_id, provider: @pending_provider, config: context&.config)
       end
 
       # An empty store would otherwise hold only this chat's model on the next
       # boot, since the registry reads whatever the store returns.
       def load_model_registry_into_store
         RubyLLM::ActiveRecord::Model.save_to_database(RubyLLM.models)
+        @model_registry_loaded_into = RubyLLM::ActiveRecord::Model.connection_db_config
       rescue ::ActiveRecord::RecordInvalid, ::ActiveRecord::RecordNotUnique
         nil
       end
 
+      def model_store_empty?
+        !RubyLLM::ActiveRecord::Model.registry_stored? && RubyLLM::ActiveRecord::Model.none?
+      end
+
+      def remember_model_registry_stored
+        RubyLLM::ActiveRecord::Model.registry_stored!(@model_registry_loaded_into)
+      end
+
       def find_or_create_model(model_info)
         attributes = { model_id: model_info.id, provider: model_info.provider }
-        load_model_registry_into_store if RubyLLM::ActiveRecord::Model.none?
+        load_model_registry_into_store if model_store_empty?
 
         RubyLLM::ActiveRecord::Model.find_or_create_by!(attributes) do |record|
           record.name = model_info.name || model_info.id
@@ -812,6 +1126,11 @@ module RubyLLM
         reason = error.is_a?(RubyLLM::CancelledError) ? 'chat cancelled' : 'API call failed'
         cleanup_failed_messages(reason:) if blank_placeholder?
         cleanup_orphaned_tool_results
+        resync_messages if @chat
+      end
+
+      def cleanup_after_block_failure
+        cleanup_failed_messages(reason: 'streaming block failed') if blank_placeholder?
       end
 
       def cleanup_failed_messages(reason:)
@@ -826,13 +1145,13 @@ module RubyLLM
         return unless last&.tool_call? || last&.tool_result?
 
         if last.tool_call?
-          last.destroy
-        elsif last.tool_result?
+          last.destroy unless last.ruby_llm_tool_calls.any?(&:paused?)
+        else
           parent = last.ruby_llm_parent_tool_call
           tool_call_message = parent.message
           calls = tool_call_message.ruby_llm_tool_calls
 
-          if calls.any? { |call| call.result.nil? }
+          if calls.any? { |call| call.result.nil? } && calls.none?(&:paused?)
             calls.filter_map(&:result).each(&:destroy)
             tool_call_message.destroy
           end
@@ -844,7 +1163,7 @@ module RubyLLM
         messages = assoc.to_a
         return messages unless assoc.respond_to?(:klass)
 
-        associations = %i[ruby_llm_tool_calls ruby_llm_parent_tool_call ruby_llm_usages]
+        associations = [:ruby_llm_tool_calls, :ruby_llm_parent_tool_call, { ruby_llm_usages: Usage.owner_preload }]
         associations << { attachments_attachments: :blob } if attachment_association?(assoc.klass)
         rich_text_reflection = assoc.klass.reflect_on_association(:rich_text_content)
         associations << :rich_text_content if rich_text_reflection
@@ -866,50 +1185,23 @@ module RubyLLM
           assume_model_exists: assume_model_exists || false
         )
         sync_messages(chat)
-        chat.cancellation_checker = proc { consume_persisted_cancellation_request }
-        chat.approval_checker = proc { |tool_call| persisted_tool_call_approval(tool_call) }
-        chat.input_checker = proc { |tool_call| persisted_tool_call_input(tool_call) }
-        chat.input_recorder = proc { |tool_call, input| persist_tool_call_input(tool_call, input) }
+        chat.run = ChatRun.new(self)
+        chat.tool_call_state = ChatToolCallState.new(self)
+        chat.message_queue = ChatQueue.new(self)
         install_persistence_callbacks(chat)
       end
 
-      def record_tool_call_decision(tool_call, decision)
-        id = tool_call.respond_to?(:tool_call_id) ? tool_call.tool_call_id : tool_call
-        id = id.id if id.respond_to?(:id) && !id.is_a?(String)
-        record = find_tool_call(id)
-        raise ArgumentError, "Unknown tool call: #{id.inspect}" unless record
-
-        record.update!(approval: decision)
-        self
-      end
-
-      def persisted_tool_call_input(tool_call)
-        record = RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(tool_call.id) }
-        record.mcp_state if record&.has_attribute?(:mcp_state)
-      end
-
-      def persist_tool_call_input(tool_call, input)
-        record = find_tool_call(tool_call.id)
-        record.update!(mcp_state: input) if record&.has_attribute?(:mcp_state)
-      end
-
-      def persisted_tool_call_approval(tool_call)
-        record = RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(tool_call.id) }
-        return unless record&.has_attribute?(:approval)
-
-        case record.approval
-        when 'approved' then true
-        when 'denied' then false
-        end
-      end
-
       def sync_messages(chat = @chat)
+        snapshot_run_claim
         message_records = eager_load_messages
+        @last_message_id = message_records.last&.id
         chat.messages = message_records
         linked_entry_pairs = message_records.zip(chat.messages).flat_map do |record, message|
           record.ruby_llm_usage_records.zip(message.ruby_llm_usage_entries)
         end
         linked_entries = linked_entry_pairs.to_h { |record, entry| [record.id, entry] }
+        ::ActiveRecord::Associations::Preloader.new(records: ruby_llm_usages.to_a,
+                                                    associations: Usage.owner_preload).call
         chat.usage_entries = ruby_llm_usages.map do |record|
           linked_entries.fetch(record.id) { record.to_entry }
         end
@@ -919,8 +1211,7 @@ module RubyLLM
 
       def install_persistence_callbacks(chat)
         chat.before_message { persist_new_message }
-        chat.usage_recorder = method(:persist_usage_entry)
-        chat.after_message { |msg| persist_message_completion(msg) }
+        chat.after_message { |msg| persist_message_completion(msg) unless msg&.role == :user }
         chat
       end
 
@@ -944,9 +1235,7 @@ module RubyLLM
       # Rewriting the same instructions every turn would move the system row
       # behind the user messages and rebroadcast it each time.
       def update_persisted_system_instruction(record, instructions, cache_until_here:)
-        boundary = cache_boundary_attributes(cache_until_here)
-        boundary.delete(:cache_until_here) unless record.has_attribute?(:cache_until_here)
-        attributes = { content: instructions, **boundary }
+        attributes = system_instruction_attributes(record, instructions, cache_until_here)
         changed = attributes.any? { |column, value| record[column] != value }
         record.update!(attributes) if changed
         messages_association.reset
@@ -998,35 +1287,23 @@ module RubyLLM
         end
       end
 
-      def persist_new_message
-        @message.destroy if blank_placeholder?
-
-        attrs = { role: :assistant, content: '' }
-        @message = messages_association.create!(attrs)
-      end
-
-      def blank_placeholder?
-        return false unless @message&.persisted? && @message.content.blank?
-        return false if @message.respond_to?(:attachments) && @message.attachments.attached?
-
-        !@message.ruby_llm_tool_calls.exists?
-      end
-
       def persist_message_completion(message)
         return unless message
 
         tool_call = find_tool_call(message.tool_call_id) if message.tool_call_id
         attrs = message_attributes(message)
 
-        transaction do
+        answered = fenced_by_run_claim do
           @message.assign_attributes(attrs)
           @message.save!
-          tool_call&.update!(tool_result_attributes(tool_call, message))
+          raise ::ActiveRecord::Rollback if tool_call && !tool_result_recorded?(tool_call, message)
 
           persist_content(@message, message.attachments) if message.attachments.any?
           persist_tool_calls(message.tool_calls) if message.tool_calls.present?
           link_usage_entries(message)
+          true
         end
+        discard_superseded_message unless answered
       end
 
       def message_attributes(message)
@@ -1037,16 +1314,18 @@ module RubyLLM
         assign_supported_attribute(attrs, :server_tool_calls, message.server_tool_calls.map(&:to_h).presence)
         assign_supported_attribute(attrs, :raw_content, message.raw_content)
         assign_supported_attribute(attrs, :raw_reasoning, message.raw_reasoning)
+        assign_supported_attribute(attrs, :phase, message.phase)
+        assign_supported_attribute(attrs, :continuation, message.continuation)
         assign_supported_attribute(attrs, :finish_reason, message.finish_reason)
         assign_supported_attribute(attrs, :cache_until_here, message.cache_until_here?)
         assign_supported_attribute(attrs, :cache_ttl, message.cache_ttl)
+        assign_fallback_attributes(attrs, message) if message.stood_in?
         attrs
       end
 
-      def tool_result_attributes(tool_call, message)
-        attributes = { result: @message }
-        attributes[:mcp_result] = message.mcp_result&.dump if tool_call.has_attribute?(:mcp_result)
-        attributes
+      def assign_fallback_attributes(attributes, message)
+        assign_supported_attribute(attributes, :model_id, message.model_id)
+        assign_supported_attribute(attributes, :provider, message.provider)
       end
 
       def assign_supported_attribute(attributes, name, value)
@@ -1054,53 +1333,19 @@ module RubyLLM
       end
 
       def persist_tool_calls(tool_calls, message_record: @message)
-        tool_calls.each_value do |tool_call|
+        tool_calls.each do |tool_call|
           attributes = tool_call.to_h
           attributes[:tool_call_id] = attributes.delete(:id)
+          malformed = attributes.delete(:malformed_arguments)
+          attributes[:arguments] = without_nul(malformed) if malformed
+          attributes[:approval] = 'pending' if to_llm.approval_pending?(tool_call)
           message_record.ruby_llm_tool_calls.create!(**attributes)
         end
       end
 
-      def find_tool_call(tool_call_id)
-        RubyLLM::ActiveRecord::ToolCall.find_by(
-          tool_call_id: tool_call_id,
-          message_type: self.class.message_class.constantize.polymorphic_name,
-          message_id: messages_association.select(:id)
-        )
-      end
-
-      def consume_persisted_cancellation_request
-        if self[:cancelled]
-          clear_cancellation_request
-          return :cancelled
-        end
-        return unless persisted?
-        return unless cancellation_poll_due?
-        return unless persisted_cancellation_request?
-
-        clear_cancellation_request
-        :cancelled
-      end
-
-      # Jobs and requests run with the query cache on, which would replay the
-      # first poll's answer for the rest of the run.
-      def persisted_cancellation_request?
-        self.class.uncached do
-          self.class.unscoped.where(self.class.primary_key => id).pick(:cancelled)
-        end
-      end
-
-      def clear_cancellation_request
-        self[:cancelled] = false
-        self.class.unscoped.where(self.class.primary_key => id).update_all(cancelled: false) if persisted?
-      end
-
-      def cancellation_poll_due?
-        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        return false if @last_cancellation_poll_at && now - @last_cancellation_poll_at < CANCELLATION_POLL_INTERVAL
-
-        @last_cancellation_poll_at = now
-        true
+      # PostgreSQL jsonb cannot store U+0000.
+      def without_nul(text)
+        text.gsub("\u0000", '\u0000')
       end
     end
   end