ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/agent.rb

@@ -9,14 +9,14 @@ module RubyLLM
   # configured chats wherever they are needed.
   #
   #   class SupportAgent < RubyLLM::Agent
-  #     model "gpt-5.6-luna"
+  #     model "gpt-6-luna"
   #     instructions "You are a concise support assistant."
   #     tools SearchDocs, LookupAccount
   #   end
   #
   #   SupportAgent.new.ask "How do I reset my API key?"
   #
-  # ::chat returns a configured Chat. When ::chat_model names an ActiveRecord
+  # ::chat returns a configured Chat. When ::chat_class names an ActiveRecord
   # chat class, ::create, ::create!, and ::find return configured records of
   # that class instead.
   #
@@ -37,11 +37,14 @@ module RubyLLM
   # Agent instances delegate Chat's conversation API (#ask, #complete,
   # #with_tools, and so on) to the wrapped chat, which is available via
   # #chat. Direct transcript replacement stays on the wrapped chat because
-  # Rails-backed chat models own their message association. Agents are
-  # enumerable over their messages.
+  # Rails-backed chat models own their message association. Read the
+  # conversation through #messages.
   class Agent
     extend Forwardable
-    include Enumerable
+    extend ModelOptions
+    singleton_class.prepend JoinCallbacks, Ownership, Callbacks, ToolConversion, ContextBudget
+    include Support::DeprecatedEnumerable
+    include Support::Rescuable
 
     DUPED_INHERITED_CONFIG = {
       :@chat_kwargs => {},
@@ -55,8 +58,7 @@ module RubyLLM
       :@headers => {},
       :@input_names => [],
       :@fallbacks => [],
-      :@fallback_options => {},
-      :@rescue_handlers => []
+      :@fallback_options => {}
     }.freeze
     # Simple value options: a class-level getter/setter macro whose value the
     # agent forwards to the matching Chat#with_* when it builds its chat.
@@ -65,42 +67,43 @@ module RubyLLM
     UNRESOLVED_CONTEXT = Object.new.freeze
     private_constant :UNRESOLVED_CONTEXT
 
-    # The chat operations an agent instance runs through its ::rescue_from
-    # handlers. Remaining delegated methods pass through untouched.
-    GUARDED_OPERATIONS = %i[ask say ask_later complete generate run_tools step count_tokens compact].freeze
-
     # Chat methods that return the wrapped chat so calls can be chained there.
     CHAINABLE_CHAT_DELEGATES = %i[
       with_instructions with_tools with_mcp with_provider_tools with_tool_options with_model
-      with_temperature with_max_output_tokens with_thinking with_citations
-      with_end_user with_compaction with_caching with_context with_provider_options
-      with_headers with_schema with_fallbacks
-      before_request before_message after_message before_tool_call after_tool_result after_tool_progress
-      before_fallback after_fallback
+      with_temperature with_max_output_tokens with_thinking with_citations with_context_budget
+      with_end_user with_owner with_compaction with_caching with_code_execution with_skills with_file_store with_context
+      with_provider_options with_headers with_schema with_fallbacks
+      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
       convert_unsupported_attachments
-      cancel approve deny answer decline cache_until_here
+      cancel approve answer decline cache_until_here
     ].freeze
 
     # Chat values and operations whose return values pass through unchanged.
     PASSTHROUGH_CHAT_DELEGATES = %i[
-      model provider messages tools deferred_tools mcp provider_tools tool_options provider_options headers schema
-      concurrency caching citations compaction context end_user fallbacks thinking temperature max_output_tokens
-      each complete? cancelled? waiting? awaiting_approval? pending_approvals awaiting_input? pending_inputs
-      awaiting_tasks? pending_tasks add_message add_completion tokens cost render
+      model model_id provider messages tools deferred_tools mcp provider_tools tool_options provider_options headers
+      schema concurrency caching citations code_execution compaction context_budget context end_user fallbacks thinking
+      temperature max_output_tokens skills file_store
+      each complete? cancelled? waiting? pending_questions pending_tasks add_message add_completion tokens cost render
+      queue queued_messages withdraw join_queued_messages
     ].freeze
 
     COPIED_INHERITED_CONFIG = (%i[
       @thinking
       @citations
+      @code_execution
+      @skills
+      @file_store
       @end_user
       @schema
       @context
-      @chat_model
+      @context_budget
+      @chat_class
       @tools_defer
       @mcp_defer
     ] + PASSTHROUGH_OPTIONS.map { |option| :"@#{option}" }).freeze
     private_constant :DUPED_INHERITED_CONFIG, :COPIED_INHERITED_CONFIG,
-                     :PASSTHROUGH_OPTIONS, :THINKING_OPTIONS, :GUARDED_OPERATIONS,
+                     :PASSTHROUGH_OPTIONS, :THINKING_OPTIONS,
                      :CHAINABLE_CHAT_DELEGATES, :PASSTHROUGH_CHAT_DELEGATES
 
     class << self
@@ -116,9 +119,17 @@ module RubyLLM
       # available as methods. Called with no arguments, returns the
       # configured chat keywords.
       #
-      #   model "gpt-5.6-luna"
-      #   model "gpt-5.6", provider: :openai, protocol: :responses
-      #   model { quality == :high ? "gpt-5.6" : "gpt-5.6-luna" }
+      #   model "gpt-6-luna"
+      #   model "gpt-6.1-sol", provider: :openai, protocol: :responses
+      #   model { quality == :high ? "gpt-6.1-sol" : "gpt-6-luna" }
+      #
+      # A +model:+ passed to ::chat, ::new, ::create, or ::create! replaces
+      # the declared model and its options, so the caller's model resolves
+      # on its own provider unless the caller also passes +provider:+. Options
+      # declared without a model stay. Later, ::find, ::new with +chat:+, and
+      # ::sync_instructions apply the options only to a record on the declared
+      # model, and always when a block declares it, since the block's choice
+      # is unknown until it runs.
       #
       # The block runs before the chat exists, so it can read inputs but not
       # +chat+.
@@ -138,12 +149,19 @@ module RubyLLM
       #   tools SearchDocs, LookupAccount
       #   tools { [TodoTool.new(chat: chat)] }
       #
-      # Pass +defer:+ as Chat#with_tools takes it:
+      # Pass +defer:+ as Chat#with_tools takes it, or a lambda that decides
+      # when the chat is built:
       #
       #   tools SearchDocs, LookupAccount, defer: true
+      #   tools(defer: -> { many_tools? }) { connected_tools }
+      #
+      # With +defer:+ alone it applies to the tools a parent agent declared.
       #
       def tools(*tools, defer: nil, &block)
-        return @tools || [] if tools.empty? && !block_given?
+        if tools.empty? && !block_given?
+          @tools_defer = defer unless defer.nil?
+          return @tools || []
+        end
 
         @tools_defer = defer
         @tools = block_given? ? block : tools.flatten
@@ -157,20 +175,26 @@ module RubyLLM
       #   mcp Files
       #   mcp { [Linear.new(user: user), Files] }
       #
-      # Pass +defer:+ as Chat#with_mcp takes it:
+      # Pass +defer:+ as Chat#with_mcp takes it, or a lambda that decides
+      # when the chat is built:
       #
       #   mcp GitHub, defer: true
       #
+      # With +defer:+ alone it applies to the servers a parent agent declared.
+      #
       def mcp(*servers, defer: nil, &block)
-        return @mcp || [] if servers.empty? && !block_given?
+        if servers.empty? && !block_given?
+          @mcp_defer = defer unless defer.nil?
+          return @mcp || []
+        end
 
         @mcp_defer = defer
         @mcp = block_given? ? block : servers.flatten
       end
 
       # Sets how chats this agent builds use their tools, applied via
-      # Chat#with_tool_options. Accepts +choice:+, +calls:+, and
-      # +concurrency:+. A block defers evaluation until the chat is built.
+      # Chat#with_tool_options. Accepts +choice:+, +calls:+, +concurrency:+,
+      # and +rounds:+. A block defers evaluation until the chat is built.
       # Called with no arguments, returns the configured options.
       #
       #   tool_options choice: :required, calls: :one
@@ -183,11 +207,13 @@ module RubyLLM
 
       # Enables provider-executed tools for chats this agent builds, applied
       # via Chat#with_provider_tools. Accepts the same aliases, options, and
-      # raw Hashes; a block defers evaluation until the chat is built.
+      # raw Hashes; a block defers evaluation until the chat is built and
+      # returns a list, or a Hash of aliases and options like the keywords.
       # Called with no arguments, returns the declared entries.
       #
       #   provider_tools :web_search
       #   provider_tools web_search: { allowed_domains: ["ruby-lang.org"] }
+      #   provider_tools { { web_search: { max_uses: max_searches } } }
       #
       def provider_tools(*tools, **tools_with_options, &block)
         return @provider_tools || [] if tools.empty? && tools_with_options.empty? && !block_given?
@@ -286,6 +312,89 @@ module RubyLLM
         @compaction = options
       end
 
+      # Keeps tool results within shares of the model's context window in
+      # chats this agent builds, applied via Chat#with_context_budget, in
+      # place of Configuration#context_budget. Pass +nil+ for no budget.
+      #
+      #   context_budget per_result: 0.25, per_request: 0.7
+      #   context_budget window: 128_000, per_request: 0.7
+      #   context_budget nil
+      #
+      # A block is evaluated for each chat, with the agent's inputs and
+      # +chat+ in scope, and returns the options, or +nil+ for no budget.
+      #
+      #   context_budget { { window: model_window, per_request: 0.7 } if model_window }
+      #
+      def context_budget(budget = {}, **, &) = (@context_budget = context_budget_option(budget, **, &))
+
+      # Lets chats this agent builds run code in the configured sandbox,
+      # applied via Chat#with_code_execution. Accepts the same options as
+      # keywords or a Hash. Pass +false+ to disable it. Passing +nil+ or a
+      # block raises ArgumentError.
+      #
+      #   code_execution
+      #   code_execution false
+      #   code_execution languages: [:ruby, :python], gems: %w[prawn]
+      #   code_execution sandbox: ReadOnlySandbox, escalate_to: [WorkspaceSandbox]
+      #   code_execution mounts: -> { { "templates" => chat.templates_dir } }
+      #
+      # A +mounts+ lambda runs before each run, with +chat+ and the
+      # agent's inputs in scope, like the agent's other lambdas.
+      def code_execution(enabled = true, **options) # rubocop:disable Style/OptionalBooleanParameter
+        raise ArgumentError, 'code_execution takes no block. Pass a lambda as mounts: for each run' if block_given?
+
+        @code_execution = CodeExecution.options(enabled, options)
+      end
+
+      # Attaches a file store to chats this agent builds, with the tools to
+      # work with it, applied via Chat#with_file_store, which takes the
+      # same arguments. A +store+ lambda runs once for each chat, with
+      # +chat+ and the agent's inputs in scope, like the agent's other
+      # lambdas. Pass +nil+ to remove the store a parent agent declared. A
+      # block raises ArgumentError: pass the lambda as the store instead.
+      #
+      #   file_store
+      #   file_store inline_limit: 20_000, tools: :read
+      #   file_store :memory
+      #   file_store -> { "tmp/chats/#{chat.id}" }
+      #   file_store nil
+      #
+      # Each chat gets a store of its own: without +store+, a new
+      # FileStore::Memory, or for a persisted chat, its files in Active
+      # Storage, kept for the chat's owner (see ::owner). A folder path on
+      # its own is shared by every chat, so use a lambda to give each chat
+      # its own folder.
+      #
+      # :call-seq: file_store(store = default, inline_limit: 10_000, tools: %i[read write edit])
+      def file_store(store = Chat::FileReferences::DEFAULT_STORE, inline_limit: Chat::FileReferences::INLINE_LIMIT,
+                     tools: FileStore::Tools::DEFAULT)
+        raise ArgumentError, 'file_store takes no block. Pass the store as a lambda instead' if block_given?
+        return @file_store = false if store.nil?
+
+        Chat::FileReferences.validate(store, inline_limit:, tools:, store_lambda: true)
+        @file_store = { store:, inline_limit:, tools: }.freeze
+      end
+
+      # Gives chats this agent builds the skills named, applied via
+      # Chat#with_skills when the chat is built. Symbols name folders under
+      # Skill.roots, Strings and Pathnames are paths to skill folders,
+      # +true+ is every skill under the roots, and +false+ removes the
+      # skills a parent agent declared. An agent without a +skills+
+      # declaration has no skills. Called with no arguments, returns the
+      # declaration: the names, +true+, +false+, or +nil+. A block raises
+      # ArgumentError.
+      #
+      #   skills :invoices, :refunds
+      #   skills true
+      #   skills false
+      #
+      def skills(*skills)
+        raise ArgumentError, 'skills takes no block. Name the skills, or pass true for every skill' if block_given?
+        return @skills if skills.empty?
+
+        @skills = Skill.selection(skills)
+      end
+
       # Sets the safety identifier for chats this agent builds, applied via
       # Chat#with_end_user. A block defers evaluation until the
       # chat is built, so the id can come from the agent's inputs. Called
@@ -294,11 +403,21 @@ module RubyLLM
       #   end_user "tenant-42"
       #   end_user { workspace.public_id }
       #
-      def end_user(value = nil, &block)
-        return @end_user if value.nil? && !block_given?
-
-        @end_user = block || value
-      end
+      def end_user(value = nil, &block) = value.nil? && !block ? @end_user : (@end_user = block || value)
+
+      # Sets whoever the usage of chats this agent builds or finds is
+      # attributed to, applied via Chat#with_owner. A block defers
+      # evaluation until the chat is built, so the owner can come from the
+      # agent's inputs or, for a persisted chat, from +chat+. A persisted
+      # chat keeps the files of its Active Storage store for the owner
+      # too, and the owner wins over the association its
+      # <tt>acts_as_chat owner:</tt> names. Subclasses inherit it. Called
+      # with no arguments, returns the configured value.
+      #
+      #   owner { account }
+      #   owner { chat.user }
+      #
+      def owner(value = nil, &block) = value.nil? && !block ? @owner : (@owner = block || value)
 
       # Enables citations for chats this agent builds, applied via
       # Chat#with_citations. Pass +false+ to disable them.
@@ -320,13 +439,18 @@ module RubyLLM
       #
       #   caching
       #   caching false
+      #   caching cache
       #   caching ttl: "1h"
       #   caching { { ttl: workspace.cache_ttl } }
       #
       def caching(enabled = true, **options, &block) # rubocop:disable Metrics/PerceivedComplexity, Style/OptionalBooleanParameter
         return caching(**enabled.transform_keys(&:to_sym), **options, &block) if enabled.is_a?(Hash)
+        return caching(id: enabled, **options, &block) if enabled.is_a?(CachedContent)
+
+        unless [true, false].include?(enabled)
+          raise ArgumentError, 'caching accepts false, a CachedContent, or caching options'
+        end
 
-        raise ArgumentError, 'caching accepts false or caching options' unless [true, false].include?(enabled)
         raise ArgumentError, 'caching accepts options or a block, not both' if options.any? && block
         raise ArgumentError, 'caching false does not accept options or a block' if !enabled && (options.any? || block)
 
@@ -375,17 +499,19 @@ module RubyLLM
 
       # Sets fallback models for chats this agent builds, applied via
       # Chat#with_fallbacks. Called with no arguments, returns the
-      # configured models.
+      # configured models. Keep the default +on:+: providers signal
+      # overload as HTTP 529 or 503, and the default covers both.
       #
       #   fallbacks "gpt-4.1-mini", "claude-haiku-4-5"
-      #   fallbacks "gpt-4.1-mini", on: [RubyLLM::RateLimitError]
+      #   fallbacks "gpt-4.1-mini", on: [*RubyLLM::Fallback::DEFAULT_ERRORS, RubyLLM::ContextLengthExceededError]
+      #   fallbacks drop_unsupported: true
       #
-      def fallbacks(*models, **options)
-        return @fallbacks || [] if models.empty? && options.empty?
-        raise ArgumentError, 'To set fallback options, provide at least one fallback model' if models.empty?
+      def fallbacks(*models, on: Fallback::DEFAULT_ERRORS, drop_unsupported: false)
+        return @fallbacks || [] if (bare = models.empty? && !drop_unsupported) && on.equal?(Fallback::DEFAULT_ERRORS)
+        raise ArgumentError, 'To set fallback options, provide at least one fallback model' if bare
 
         @fallbacks = models.flatten.compact
-        @fallback_options = options
+        @fallback_options = { on:, drop_unsupported: }
       end
 
       def fallback_options
@@ -425,13 +551,18 @@ module RubyLLM
       # ::sync_instructions). Accepts the class or its name as a string.
       # Called with no argument, returns the configured value.
       #
-      #   chat_model Chat
+      #   chat_class Chat
       #
-      def chat_model(value = nil)
-        return @chat_model if value.nil?
+      def chat_class(value = nil)
+        return @chat_class if value.nil?
+
+        @chat_class = value
+        remove_instance_variable(:@resolved_chat_class) if instance_variable_defined?(:@resolved_chat_class)
+      end
 
-        @chat_model = value
-        remove_instance_variable(:@resolved_chat_model) if instance_variable_defined?(:@resolved_chat_model)
+      def chat_model(value = nil) # :nodoc:
+        RubyLLM.deprecator.deprecate('Agent.chat_model', replacement: 'Agent.chat_class', removal: '3.0')
+        chat_class(value)
       end
 
       # Declares named runtime inputs. Matching keyword arguments passed to
@@ -447,57 +578,6 @@ module RubyLLM
         @input_names = names.flatten.map(&:to_sym)
       end
 
-      # Registers a handler for exceptions raised by the chat operations of
-      # this agent's instances: #ask, #say, #ask_later, #complete,
-      # #generate, #run_tools, #step, #count_tokens, and #compact. Name the
-      # handler with +with:+ or pass a block; either runs on the agent instance,
-      # so the agent's #chat, inputs, and class name are available for instrumentation.
-      #
-      #   class ApplicationAgent < RubyLLM::Agent
-      #     rescue_from RubyLLM::RateLimitError, Faraday::TimeoutError, with: :handle_transient
-      #     rescue_from RubyLLM::BadRequestError do |error|
-      #       error_tracker.notify(error)
-      #       raise
-      #     end
-      #
-      #     private
-      #
-      #     def handle_transient(error)
-      #       metrics.increment("llm.api_error", type: "transient")
-      #       raise
-      #     end
-      #   end
-      #
-      # Handlers are searched in reverse declaration order, so the last
-      # matching one wins. Re-raise inside a handler to let the caller see
-      # the exception; otherwise the handler's return value becomes the
-      # operation's return value. Exceptions no handler matches are
-      # re-raised. Subclasses inherit the handlers declared when they are
-      # defined.
-      #
-      # Exception classes may be named as Strings, which defers constant
-      # lookup until an exception is raised.
-      def rescue_from(*exception_classes, with: nil, &block)
-        raise ArgumentError, 'rescue_from needs a handler: pass with: or a block' unless with || block
-        raise ArgumentError, 'rescue_from takes with: or a block, not both' if with && block
-
-        exception_classes.flatten.each do |exception_class|
-          rescue_handlers << [rescue_handler_key(exception_class), with || block]
-        end
-      end
-
-      def rescue_handlers # :nodoc:
-        @rescue_handlers ||= []
-      end
-
-      def rescue_handler_for(exception) # :nodoc:
-        rescue_handlers.reverse_each do |class_name, handler|
-          exception_class = rescue_handler_class(class_name)
-          return handler if exception_class && exception.is_a?(exception_class)
-        end
-        nil
-      end
-
       def chat_kwargs # :nodoc:
         @chat_kwargs || {}
       end
@@ -511,16 +591,9 @@ module RubyLLM
         evaluate(value, runtime_context(chat: nil, inputs:))
       end
 
-      def resolved_chat_kwargs(inputs: {}) # :nodoc:
-        kwargs = chat_kwargs
-        return kwargs unless kwargs[:model].is_a?(Proc)
-
-        kwargs.merge(model: evaluate(kwargs[:model], runtime_context(chat: nil, inputs: inputs)))
-      end
-
       def build_chat(inputs:, options:, resolved_context: UNRESOLVED_CONTEXT) # :nodoc:
         context_value = resolved_context.equal?(UNRESOLVED_CONTEXT) ? self.resolved_context(inputs:) : resolved_context
-        (context_value || RubyLLM).chat(**resolved_chat_kwargs(inputs:), **options)
+        (context_value || RubyLLM).chat(**resolved_chat_kwargs(inputs:, options:))
       end
 
       # Builds a Chat configured with this agent's declarations and returns
@@ -538,13 +611,13 @@ module RubyLLM
         chat
       end
 
-      # Creates a ::chat_model record, applies this agent's configuration to
+      # Creates a ::chat_class record, applies this agent's configuration to
       # it, and returns it. Keywords matching declared ::inputs become
       # runtime inputs; the rest are forwarded to the model's +create+.
       #
       #   chat = WorkAssistant.create(user: current_user)
       #
-      # Raises ArgumentError if ::chat_model is not configured.
+      # Raises ArgumentError if ::chat_class is not configured.
       def create(**)
         with_rails_chat_record(:create, **)
       end
@@ -558,38 +631,37 @@ module RubyLLM
         with_rails_chat_record(:create!, **)
       end
 
-      # Finds the ::chat_model record with +id+ and applies this agent's
+      # Finds the ::chat_class record with +id+ and applies this agent's
       # configuration at runtime, without persisting instructions. Returns
       # the record.
       #
       #   chat = WorkAssistant.find(params[:id])
       #
-      # Raises ArgumentError if ::chat_model is not configured.
+      # Raises ArgumentError if ::chat_class is not configured.
       def find(id, **kwargs)
-        raise ArgumentError, 'chat_model must be configured to use find' unless resolved_chat_model
+        raise ArgumentError, 'chat_class must be configured to use find' unless resolved_chat_class
 
         input_values, = partition_inputs(kwargs)
-        record = resolved_chat_model.find(id)
+        record = resolved_chat_class.find(id)
         apply_configuration(record, input_values:, persist_instructions: false)
 
         record
       end
 
       # Re-renders this agent's instructions and persists them on the given
-      # ::chat_model record (or the record found by that id). Keywords
+      # ::chat_class record (or the record found by that id). Keywords
       # matching declared ::inputs become runtime inputs. Returns the
       # record.
       #
       #   WorkAssistant.sync_instructions(chat)
       #
-      # Raises ArgumentError if ::chat_model is not configured.
+      # Raises ArgumentError if ::chat_class is not configured.
       def sync_instructions(chat_or_id, **kwargs)
-        raise ArgumentError, 'chat_model must be configured to use sync_instructions' unless resolved_chat_model
+        raise ArgumentError, 'chat_class must be configured to use sync_instructions' unless resolved_chat_class
 
         input_values, = partition_inputs(kwargs)
-        record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
-        apply_assume_model_exists(record)
-        apply_protocol(record)
+        record = chat_or_id.is_a?(resolved_chat_class) ? chat_or_id : resolved_chat_class.find(chat_or_id)
+        apply_chat_options(record)
         runtime = runtime_context(chat: record, inputs: input_values)
         apply_context(record, runtime)
         apply_instructions(
@@ -627,10 +699,12 @@ module RubyLLM
         chat,
         input_values:,
         persist_instructions:,
-        resolved_context: UNRESOLVED_CONTEXT
+        resolved_context: UNRESOLVED_CONTEXT,
+        agent: nil,
+        chat_options: {}
       )
         runtime = runtime_context(chat:, inputs: input_values)
-        apply_chat_options(chat)
+        apply_chat_options(chat, chat_options)
         apply_context(chat, runtime, resolved_context:)
         apply_instructions(chat, runtime, inputs: input_values, persist: persist_instructions)
         apply_tools(chat, runtime)
@@ -640,10 +714,17 @@ module RubyLLM
         apply_end_user(chat, runtime)
         apply_caching(chat, runtime)
         apply_compaction(chat)
+        apply_code_execution(chat, runtime)
+        apply_skills(chat)
+        apply_file_store(chat, runtime)
+        apply_tool_options(chat, runtime)
         apply_provider_options(chat, runtime)
         apply_headers(chat, runtime)
         apply_schema(chat, runtime)
         apply_fallbacks(chat)
+        apply_rescue_handlers(chat, agent, input_values)
+        target = chat.respond_to?(:to_llm) ? chat.to_llm : chat
+        target.agent_class = self if target.respond_to?(:agent_class=)
       end
 
       private
@@ -666,28 +747,12 @@ module RubyLLM
         raise ArgumentError, "thinking accepts #{THINKING_OPTIONS.join(', ')}, got #{unsupported.join(', ')}"
       end
 
-      def rescue_handler_key(exception_class)
-        case exception_class
-        when Module then exception_class.name || exception_class
-        when String then exception_class
-        else raise ArgumentError, "#{exception_class.inspect} is not an exception class or its name"
-        end
-      end
-
-      def rescue_handler_class(class_name)
-        return class_name if class_name.is_a?(Module)
-
-        Object.const_get(class_name)
-      rescue NameError
-        nil
-      end
-
       def copy_inherited_config_to(subclass)
         subclass.instance_variable_set(:@inherited_instruction_declarations, instruction_declarations.dup)
 
         DUPED_INHERITED_CONFIG.each do |ivar, default|
           value = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : default
-          subclass.instance_variable_set(ivar, value.respond_to?(:dup) ? value.dup : value)
+          subclass.instance_variable_set(ivar, value.dup)
         end
 
         COPIED_INHERITED_CONFIG.each do |ivar|
@@ -696,13 +761,13 @@ module RubyLLM
       end
 
       def with_rails_chat_record(method_name, **kwargs)
-        raise ArgumentError, 'chat_model must be configured to use create/create!' unless resolved_chat_model
+        raise ArgumentError, 'chat_class must be configured to use create/create!' unless resolved_chat_class
 
         input_values, chat_options = partition_inputs(kwargs)
-        record = resolved_chat_model.public_send(
-          method_name, **resolved_chat_kwargs(inputs: input_values), **chat_options
+        record = resolved_chat_class.public_send(
+          method_name, **resolved_chat_kwargs(inputs: input_values, options: chat_options)
         )
-        apply_configuration(record, input_values:, persist_instructions: true) if record
+        apply_configuration(record, input_values:, persist_instructions: true, chat_options:) if record&.persisted?
         record
       end
 
@@ -712,7 +777,13 @@ module RubyLLM
       end
 
       def apply_instructions(chat, runtime, inputs:, persist:, persistent_only: false)
-        instructions_config.each do |declaration|
+        instructions = resolved_instructions(chat, runtime, inputs:, persist:, persistent_only:)
+        instructions.reject! { |_, options| options[:persist] } if instructions_persisted?(chat, instructions)
+        instructions.each { |value, options| chat.with_instructions(value, **options) }
+      end
+
+      def resolved_instructions(chat, runtime, inputs:, persist:, persistent_only:)
+        instructions_config.filter_map do |declaration|
           next if persistent_only && !declaration[:persist]
 
           value = resolved_instruction_value(declaration, chat, runtime, inputs:)
@@ -723,10 +794,22 @@ module RubyLLM
             cache_until_here: declaration[:cache_until_here]
           }
           options[:persist] = persist && declaration[:persist] if rails_chat_record?(chat)
-          chat.with_instructions(value, **options)
+          [value, options]
         end
       end
 
+      # Applying an agent to a record on every request would otherwise
+      # rewrite the same system rows each time, behind the conversation.
+      def instructions_persisted?(chat, instructions)
+        persistent = instructions.select { |_, options| options[:persist] }
+        replacement = persistent.rindex { |_, options| !options[:append] }
+        return false unless replacement
+
+        chat.system_instructions_persisted?(
+          persistent.drop(replacement).map { |value, options| [value, options[:cache_until_here]] }
+        )
+      end
+
       # An empty prompt file, such as the one the agent generator writes,
       # means no instructions rather than an empty system message.
       def blank_instruction?(value)
@@ -735,16 +818,18 @@ module RubyLLM
 
       def apply_tools(chat, runtime)
         tools_to_apply = Array(evaluate(tools, runtime)).compact
-        chat.with_tools(*tools_to_apply, defer: @tools_defer) if tools_to_apply.any?
+        chat.with_tools(*tools_to_apply, defer: evaluate(@tools_defer, runtime)) if tools_to_apply.any?
 
         servers = Array(evaluate(mcp, runtime)).compact
-        chat.with_mcp(*servers, defer: @mcp_defer) if servers.any?
+        chat.with_mcp(*servers, defer: evaluate(@mcp_defer, runtime)) if servers.any?
+
+        provider_tools_to_apply = RubyLLM::Tools::ProviderTools.entries(evaluate(provider_tools, runtime))
+        chat.with_provider_tools(*provider_tools_to_apply) if provider_tools_to_apply.any?
+      end
 
+      def apply_tool_options(chat, runtime)
         options = evaluate(tool_options, runtime)
         chat.with_tool_options(**options) if options && !options.empty?
-
-        provider_tools_to_apply = Array(evaluate(provider_tools, runtime)).compact
-        chat.with_provider_tools(*provider_tools_to_apply) if provider_tools_to_apply.any?
       end
 
       def apply_passthrough_options(chat)
@@ -782,6 +867,33 @@ module RubyLLM
         @compaction == false ? chat.with_compaction(false) : chat.with_compaction(**@compaction)
       end
 
+      def apply_code_execution(chat, runtime)
+        return if @code_execution.nil?
+        return chat.with_code_execution(false) if @code_execution == false
+
+        options = @code_execution
+        mounts = options[:mounts]
+        options = options.merge(mounts: -> { evaluate(mounts, runtime) }) if mounts.is_a?(Proc)
+        chat.with_code_execution(**options)
+      end
+
+      def apply_file_store(chat, runtime)
+        return if @file_store.nil?
+        return chat.with_file_store(nil) if @file_store == false
+
+        store = @file_store[:store]
+        options = @file_store.except(:store).transform_values { |value| evaluate(value, runtime) }
+        return chat.with_file_store(**options) if store.equal?(Chat::FileReferences::DEFAULT_STORE)
+
+        chat.with_file_store(evaluate(store, runtime), **options)
+      end
+
+      def apply_skills(chat)
+        return if @skills.nil?
+
+        chat.with_skills(*Array(@skills))
+      end
+
       def apply_provider_options(chat, runtime)
         value = evaluate(provider_options, runtime)
         chat.with_provider_options(**value) if value && !value.empty?
@@ -798,7 +910,13 @@ module RubyLLM
       end
 
       def apply_fallbacks(chat)
-        chat.with_fallbacks(*fallbacks, **fallback_options) if fallbacks.any?
+        chat.with_fallbacks(*fallbacks, **fallback_options) if fallbacks.any? || fallback_options[:drop_unsupported]
+      end
+
+      def apply_rescue_handlers(chat, agent, input_values)
+        return unless chat.is_a?(Chat::Rescuable)
+
+        chat.rescuer = rescue_handlers? ? agent || allocate.bind(chat, input_values) : nil
       end
 
       def resolved_schema_value(runtime)
@@ -809,27 +927,6 @@ module RubyLLM
         Schematist::Schema.create(&value)
       end
 
-      def apply_chat_options(chat)
-        apply_assume_model_exists(chat)
-        apply_protocol(chat)
-      end
-
-      def apply_assume_model_exists(chat_object)
-        return unless chat_kwargs.key?(:assume_model_exists) &&
-                      resolved_chat_model &&
-                      chat_object.is_a?(resolved_chat_model)
-
-        chat_object.assume_model_exists = chat_kwargs[:assume_model_exists]
-      end
-
-      def apply_protocol(chat_object)
-        return unless chat_kwargs.key?(:protocol) &&
-                      resolved_chat_model &&
-                      chat_object.is_a?(resolved_chat_model)
-
-        chat_object.protocol = chat_kwargs[:protocol]
-      end
-
       def evaluate(value, runtime)
         value.is_a?(Proc) ? runtime.instance_exec(&value) : value
       end
@@ -860,7 +957,7 @@ module RubyLLM
       end
 
       def rails_chat_record?(chat)
-        resolved_chat_model && chat.is_a?(resolved_chat_model)
+        resolved_chat_class && chat.is_a?(resolved_chat_class)
       end
 
       def default_instructions_prompt_exists?
@@ -898,12 +995,12 @@ module RubyLLM
         Support::Utils.underscore(class_name.gsub('::', '/')).tr('-', '_')
       end
 
-      def resolved_chat_model
-        return @resolved_chat_model if defined?(@resolved_chat_model)
+      def resolved_chat_class
+        return @resolved_chat_class if defined?(@resolved_chat_class)
 
-        @resolved_chat_model = case @chat_model
-                               when String then Object.const_get(@chat_model)
-                               else @chat_model
+        @resolved_chat_class = case @chat_class
+                               when String then Object.const_get(@chat_class)
+                               else @chat_class
                                end
       end
     end
@@ -927,22 +1024,20 @@ module RubyLLM
       input_values = input_values.merge(inputs || {})
 
       if chat
-        @chat = chat
-        self.class.apply_configuration(@chat, input_values:, persist_instructions:)
+        bind(chat, input_values)
+        self.class.apply_configuration(@chat, input_values:, persist_instructions:, agent: self)
         return
       end
 
       context_value = self.class.resolved_context(inputs: input_values)
-      @chat = self.class.build_chat(
-        inputs: input_values,
-        options: chat_options,
-        resolved_context: context_value
-      )
+      bind(self.class.build_chat(inputs: input_values, options: chat_options, resolved_context: context_value),
+           input_values)
       self.class.apply_configuration(
         @chat,
         input_values:,
         persist_instructions:,
-        resolved_context: context_value
+        resolved_context: context_value,
+        agent: self
       )
     end
 
@@ -953,6 +1048,207 @@ module RubyLLM
     # #chat without adapting its return values.
     def_delegators :chat, *CHAINABLE_CHAT_DELEGATES, *PASSTHROUGH_CHAT_DELEGATES
 
+    ##
+    # :singleton-method: rescue_from
+    # :call-seq: rescue_from(*exception_classes, with: nil, &block)
+    #
+    # Registers a handler for exceptions raised by the chat operations of
+    # this agent's instances and of the chats and records ::chat, ::create,
+    # ::create!, and ::find return: #ask, #say, #ask_later, #complete,
+    # #generate, #run_tools, #step, #count_tokens, and #compact. Name the
+    # handler with +with:+ or pass a block; either runs on the agent instance,
+    # so the agent's #chat, inputs, and class name are available for instrumentation.
+    #
+    #   class ApplicationAgent < RubyLLM::Agent
+    #     rescue_from RubyLLM::RateLimitError, RubyLLM::ConnectionError, with: :handle_transient
+    #     rescue_from RubyLLM::BadRequestError do |error|
+    #       error_tracker.notify(error)
+    #       raise
+    #     end
+    #
+    #     private
+    #
+    #     def handle_transient(error)
+    #       metrics.increment("llm.api_error", type: "transient")
+    #       raise
+    #     end
+    #   end
+    #
+    # Handlers are searched in reverse declaration order, so the last
+    # matching one wins. Re-raise inside a handler to let the caller see
+    # the exception; otherwise the handler's return value becomes the
+    # operation's return value. Exceptions no handler matches are
+    # re-raised. Subclasses use their parents' handlers, including ones
+    # declared after the subclass, and their own come first.
+    #
+    # Exception classes may be named as Strings, which defers constant
+    # lookup until an exception is raised. A class that can never match a
+    # StandardError, such as Interrupt, raises ArgumentError.
+
+    ##
+    # :method: rescue_with_handler
+    # :call-seq: rescue_with_handler(exception)
+    #
+    # Runs the ::rescue_from handler matching +exception+ and returns its
+    # value, or re-raises when no handler matches. The chat operations call
+    # this for you.
+
+    ##
+    # :singleton-method: description
+    # :call-seq: description(text = nil)
+    #
+    # Sets what the agent does, which a model reads when the agent is one
+    # of its tools (see ::to_tool), or returns it when called without an
+    # argument.
+    #
+    #   class ResearchAgent < RubyLLM::Agent
+    #     description "Researches a question across the web and reports back"
+    #   end
+
+    ##
+    # :singleton-method: to_tool
+    # :call-seq: to_tool(**inputs)
+    #
+    # Returns an AgentTool that runs this agent as a subagent: a model
+    # hands it a task and gets its answer back. Keywords matching ::inputs
+    # are given to every run; the agent's other inputs become parameters
+    # the model fills. Chat#with_tools and ::tools take an Agent class too,
+    # and convert it with no inputs.
+    #
+    #   chat.with_tools(ResearchAgent.to_tool(workspace: current_workspace))
+    #   chat.with_tools(ResearchAgent)
+    #
+    # Raises ArgumentError for an agent class without a name.
+
+    ##
+    # :singleton-method: after_message
+    # :call-seq: after_message(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#after_message callback on every chat the agent builds
+    # or finds, Agent::find records included. Name a method or pass a block;
+    # either runs on the agent instance, so its inputs, +chat+, and private
+    # methods are available, and receives the callback's arguments when it
+    # takes them. +if:+ and +unless:+ take a method name, a lambda, or an
+    # Array of them, like Rails callbacks. Subclasses inherit the callbacks
+    # declared when they are defined. Returns the agent class.
+    #
+    # For a chat from ::chat or ::find, the agent is bound to the chat
+    # without running +initialize+, as for ::rescue_from handlers, so read
+    # inputs and +chat+ rather than instance variables +initialize+ sets.
+    # Wrapping a configured chat in a new agent, as
+    # <tt>SupportAgent.new(chat:)</tt> does, moves its callbacks to that
+    # agent instead of registering them twice.
+    #
+    #   class SupportAgent < RubyLLM::Agent
+    #     inputs :ticket
+    #
+    #     after_message :log_reply, if: -> { ticket.urgent? }
+    #     before_tool_call { |tool_call| Rails.logger.info "Calling #{tool_call.name}" }
+    #
+    #     private
+    #
+    #     def log_reply(message) = ticket.notes.create!(body: message.content)
+    #   end
+    #
+    # The other chat callbacks have macros of the same name and shape:
+    # ::before_request, ::before_message, ::before_tool_call,
+    # ::around_tool_call, ::after_tool_result, ::after_tool_progress, ::before_fallback,
+    # ::after_fallback, and ::after_file_write. Raises ArgumentError for
+    # both a method name and a block, neither, or another option.
+
+    ##
+    # :singleton-method: before_request
+    # :call-seq: before_request(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#before_request callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: before_message
+    # :call-seq: before_message(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#before_message callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: before_tool_call
+    # :call-seq: before_tool_call(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#before_tool_call callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: around_tool_call
+    # :call-seq: around_tool_call(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#around_tool_call callback on every chat the agent builds
+    # or finds. The method or block receives the ToolCall and a block that
+    # runs the tool. A method yields to it; a block takes it as +&run+:
+    #
+    #   class SupportAgent < RubyLLM::Agent
+    #     inputs :account
+    #
+    #     around_tool_call :in_tenant
+    #
+    #     private
+    #
+    #     def in_tenant(tool_call, &) = ActsAsTenant.with_tenant(account, &)
+    #   end
+    #
+    # When +if:+ or +unless:+ skips the callback, the tool runs without it.
+    # See ::after_message.
+
+    ##
+    # :singleton-method: after_tool_result
+    # :call-seq: after_tool_result(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#after_tool_result callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: after_tool_progress
+    # :call-seq: after_tool_progress(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#after_tool_progress callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: before_fallback
+    # :call-seq: before_fallback(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#before_fallback callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: after_fallback
+    # :call-seq: after_fallback(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#after_fallback callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: after_file_write
+    # :call-seq: after_file_write(method_name = nil, if: nil, unless: nil, &block)
+    #
+    # Registers a Chat#after_file_write callback on every chat the agent builds or
+    # finds. See ::after_message.
+
+    ##
+    # :singleton-method: around_join
+    # :call-seq: around_join(&block)
+    #
+    # Registers +block+ as a Chat#around_join callback on every chat the
+    # agent builds or finds. Subclasses inherit the callbacks declared
+    # when they are defined. Returns the list of callbacks.
+    #
+    #   class SupportAgent < RubyLLM::Agent
+    #     around_join do |queued, join|
+    #       join.call(sender: queued.sender)
+    #     end
+    #   end
+    #
+    # Raises ArgumentError without a block.
+
     ##
     # :method: with_instructions
     # :call-seq: with_instructions(instructions, append: false, cache_until_here: false)
@@ -1019,6 +1315,18 @@ module RubyLLM
     #
     # Delegates to Chat#with_end_user. See that method for arguments and return values.
 
+    ##
+    # :method: with_owner
+    # :call-seq: with_owner(owner)
+    #
+    # Delegates to Chat#with_owner. See that method for arguments and return values.
+
+    ##
+    # :method: with_context_budget
+    # :call-seq: with_context_budget(budget = {}, per_result: nil, per_request: nil, window: nil)
+    #
+    # Delegates to Chat#with_context_budget. See that method for arguments and return values.
+
     ##
     # :method: with_compaction
     # :call-seq: with_compaction(options = {})
@@ -1031,6 +1339,24 @@ module RubyLLM
     #
     # Delegates to Chat#with_caching. See that method for arguments and return values.
 
+    ##
+    # :method: with_code_execution
+    # :call-seq: with_code_execution(enabled = true, **options)
+    #
+    # Delegates to Chat#with_code_execution. See that method for arguments and return values.
+
+    ##
+    # :method: with_skills
+    # :call-seq: with_skills(*skills)
+    #
+    # Delegates to Chat#with_skills. See that method for arguments and return values.
+
+    ##
+    # :method: with_file_store
+    # :call-seq: with_file_store(store = :memory, inline_limit: 10_000, tools: %i[read write edit])
+    #
+    # Delegates to Chat#with_file_store. See that method for arguments and return values.
+
     ##
     # :method: with_context
     # :call-seq: with_context(context)
@@ -1057,7 +1383,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)
     #
     # Delegates to Chat#with_fallbacks. See that method for arguments and return values.
 
@@ -1097,6 +1423,12 @@ module RubyLLM
     #
     # Delegates to Chat#after_tool_result. See that method for arguments and return values.
 
+    ##
+    # :method: around_tool_call
+    # :call-seq: around_tool_call(&block)
+    #
+    # Delegates to Chat#around_tool_call. See that method for arguments and return values.
+
     ##
     # :method: after_tool_progress
     # :call-seq: after_tool_progress(&block)
@@ -1115,6 +1447,24 @@ module RubyLLM
     #
     # Delegates to Chat#after_fallback. See that method for arguments and return values.
 
+    ##
+    # :method: around_join
+    # :call-seq: around_join(&block)
+    #
+    # Delegates to Chat#around_join. See that method for arguments and return values.
+
+    ##
+    # :method: join_queued_messages
+    # :call-seq: join_queued_messages
+    #
+    # Delegates to Chat#join_queued_messages. See that method for arguments and return values.
+
+    ##
+    # :method: after_file_write
+    # :call-seq: after_file_write(&block)
+    #
+    # Delegates to Chat#after_file_write. See that method for arguments and return values.
+
     ##
     # :method: cancel
     # :call-seq: cancel()
@@ -1123,25 +1473,19 @@ module RubyLLM
 
     ##
     # :method: approve
-    # :call-seq: approve(tool_call)
+    # :call-seq: approve(tool_call, remember: false)
     #
     # Delegates to Chat#approve. See that method for arguments and return values.
 
-    ##
-    # :method: deny
-    # :call-seq: deny(tool_call)
-    #
-    # Delegates to Chat#deny. See that method for arguments and return values.
-
     ##
     # :method: answer
-    # :call-seq: answer(request, **values)
+    # :call-seq: answer(question, value = nil, **values)
     #
     # Delegates to Chat#answer. See that method for arguments and return values.
 
     ##
     # :method: decline
-    # :call-seq: decline(request)
+    # :call-seq: decline(question, note = nil)
     #
     # Delegates to Chat#decline. See that method for arguments and return values.
 
@@ -1149,7 +1493,9 @@ module RubyLLM
     # :method: cache_until_here
     # :call-seq: cache_until_here(ttl: nil)
     #
-    # Delegates to Chat#cache_until_here. See that method for arguments and return values.
+    # Deprecated: use Message#cache_until_here or
+    # <tt>with_instructions(cache_until_here:)</tt>. Delegates to
+    # Chat#cache_until_here, which warns. RubyLLM 3.0 removes it.
 
     ##
     # :method: model
@@ -1235,12 +1581,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: context
     # :call-seq: context
@@ -1281,7 +1651,15 @@ module RubyLLM
     # :method: each
     # :call-seq: each(&block)
     #
-    # Delegates to Chat#each. See that method for arguments and return values.
+    # Deprecated: iterate #messages instead. Delegates to Chat#each, which
+    # warns, as do the Enumerable methods built on it. RubyLLM 3.0 removes
+    # them.
+
+    ##
+    # :method: model_id
+    # :call-seq: model_id()
+    #
+    # Delegates to Chat#model_id. See that method for arguments and return values.
 
     ##
     # :method: complete?
@@ -1302,46 +1680,40 @@ module RubyLLM
     # Delegates to Chat#waiting?. See that method for arguments and return values.
 
     ##
-    # :method: awaiting_approval?
-    # :call-seq: awaiting_approval?()
+    # :method: pending_questions
+    # :call-seq: pending_questions()
     #
-    # Delegates to Chat#awaiting_approval?. See that method for arguments and return values.
+    # Delegates to Chat#pending_questions. See that method for arguments and return values.
 
     ##
-    # :method: pending_approvals
-    # :call-seq: pending_approvals()
-    #
-    # Delegates to Chat#pending_approvals. See that method for arguments and return values.
-
-    ##
-    # :method: awaiting_input?
-    # :call-seq: awaiting_input?()
+    # :method: pending_tasks
+    # :call-seq: pending_tasks()
     #
-    # Delegates to Chat#awaiting_input?. See that method for arguments and return values.
+    # Delegates to Chat#pending_tasks. See that method for arguments and return values.
 
     ##
-    # :method: pending_inputs
-    # :call-seq: pending_inputs()
+    # :method: add_message
+    # :call-seq: add_message(message_or_attributes)
     #
-    # Delegates to Chat#pending_inputs. See that method for arguments and return values.
+    # Delegates to Chat#add_message. See that method for arguments and return values.
 
     ##
-    # :method: awaiting_tasks?
-    # :call-seq: awaiting_tasks?()
+    # :method: queue
+    # :call-seq: queue(message = nil, with: nil, steer: true, sender: nil)
     #
-    # Delegates to Chat#awaiting_tasks?. See that method for arguments and return values.
+    # Delegates to Chat#queue. See that method for arguments and return values.
 
     ##
-    # :method: pending_tasks
-    # :call-seq: pending_tasks()
+    # :method: queued_messages
+    # :call-seq: queued_messages()
     #
-    # Delegates to Chat#pending_tasks. See that method for arguments and return values.
+    # Delegates to Chat#queued_messages. See that method for arguments and return values.
 
     ##
-    # :method: add_message
-    # :call-seq: add_message(message_or_attributes)
+    # :method: withdraw
+    # :call-seq: withdraw(queued)
     #
-    # Delegates to Chat#add_message. See that method for arguments and return values.
+    # Delegates to Chat#withdraw. See that method for arguments and return values.
 
     ##
     # :method: tokens
@@ -1423,25 +1795,37 @@ module RubyLLM
     # Compacts the model context through Chat#compact and returns its Message.
     # Exceptions use ::rescue_from handlers.
 
-    GUARDED_OPERATIONS.each do |operation|
+    Chat::Rescuable::OPERATIONS.each do |operation|
       define_method(operation) do |*args, **kwargs, &block|
-        chat.public_send(operation, *args, **kwargs, &block)
-      rescue StandardError => e
-        rescue_with_handler(e)
+        rescuing { chat.public_send(operation, *args, **kwargs, &block) }
       end
     end
 
-    # Runs the ::rescue_from handler matching +exception+ and returns its
-    # value, or re-raises when no handler matches. The chat operations call
-    # this for you.
-    def rescue_with_handler(exception)
-      handler = self.class.rescue_handler_for(exception)
-      raise exception unless handler
+    # Returns whoever the usage of the agent's chat is attributed to, as
+    # Chat#owner describes. For a persisted chat, reads it from the
+    # record's chat, since the record leaves +owner+ to the application.
+    def owner
+      (chat.respond_to?(:to_llm) ? chat.to_llm : chat).owner
+    end
 
-      return instance_exec(exception, &handler) unless handler.is_a?(Symbol)
+    def bind(chat, input_values) # :nodoc:
+      @chat = chat
+      input_values.each do |name, value|
+        define_singleton_method(name) { value } unless respond_to?(name)
+      end
+      self
+    end
+
+    private
+
+    def rescuing(&)
+      return chat.rescuing_with(self, &) if chat.is_a?(Chat::Rescuable)
 
-      handler_method = method(handler)
-      handler_method.arity.zero? ? handler_method.call : handler_method.call(exception)
+      begin
+        yield
+      rescue StandardError => e
+        rescue_with_handler(e)
+      end
     end
   end
 end