ruby_llm-agents 3.12.0 → 3.14.0

data/lib/ruby_llm/agents/base_agent.rb

@@ -262,6 +262,24 @@ module RubyLLM
           @tools || (superclass.respond_to?(:tools) ? superclass.tools : [])
         end
 
+        # Sets or returns how this agent runs multiple tool calls returned in
+        # a single LLM response.
+        #
+        # Mirrors RubyLLM's tool_concurrency: +false+ runs them sequentially,
+        # +true+ or +:threads+ runs them in Ruby threads, and +:fibers+ runs
+        # them in fibers (requires the async gem). When unset, the agent
+        # inherits its superclass value and ultimately the global
+        # RubyLLM tool_concurrency configuration.
+        #
+        # @param value [Boolean, Symbol] Concurrency mode (omit to read)
+        # @return [Boolean, Symbol, nil] Configured mode, or nil when unset
+        def tool_concurrency(*value)
+          @tool_concurrency = value.first unless value.empty?
+          return @tool_concurrency if instance_variable_defined?(:@tool_concurrency)
+
+          superclass.respond_to?(:tool_concurrency) ? superclass.tool_concurrency : nil
+        end
+
         # @!endgroup
 
         # @!group Temperature DSL
@@ -738,6 +756,7 @@ module RubyLLM
       def execute(context)
         @context = context
         client = build_client(context)
+        @client = client
 
         # Make context available to Tool instances during tool execution
         previous_context = Thread.current[:ruby_llm_agents_caller_context]
@@ -788,7 +807,16 @@ module RubyLLM
         end
 
         client = client.with_schema(schema) if schema
-        client = client.with_tools(*resolved_tools) if resolved_tools.any?
+        if resolved_tools.any?
+          # Only pass concurrency when the agent overrides it; otherwise let
+          # RubyLLM apply its globally configured tool_concurrency default.
+          concurrency = self.class.tool_concurrency
+          client = if concurrency.nil?
+            client.with_tools(*resolved_tools)
+          else
+            client.with_tools(*resolved_tools, concurrency: concurrency)
+          end
+        end
         apply_tool_prompt_caching(client) if use_prompt_caching && resolved_tools.any?
         client = setup_tool_tracking(client) if resolved_tools.any?
         client = apply_messages(client, resolved_messages) if resolved_messages.any?
@@ -891,35 +919,80 @@ module RubyLLM
 
       # Captures response metadata to the context
       #
-      # @param response [RubyLLM::Message] The response
+      # When a tool returns RubyLLM::Tool::Halt, the response is a Halt
+      # instance with no token metadata. In that case we pull metadata from
+      # the last assistant message in the client's history.
+      #
+      # @param response [RubyLLM::Message, RubyLLM::Tool::Halt] The response
       # @param context [Pipeline::Context] The context
       def capture_response(response, context)
-        context.input_tokens = response.input_tokens
-        context.output_tokens = response.output_tokens
-        context.model_used = response.model_id || model
-        # finish_reason may not be available on all RubyLLM::Message versions
-        context.finish_reason = response.respond_to?(:finish_reason) ? response.finish_reason : nil
+        is_halt = response.is_a?(RubyLLM::Tool::Halt)
+        metadata = is_halt ? last_assistant_message_from_client : response
 
-        # Store tracked tool calls in context for instrumentation
-        context[:tool_calls] = @tracked_tool_calls if @tracked_tool_calls.any?
+        if metadata
+          context.input_tokens = metadata.input_tokens if metadata.respond_to?(:input_tokens)
+          context.output_tokens = metadata.output_tokens if metadata.respond_to?(:output_tokens)
+          context.model_used = (metadata.respond_to?(:model_id) && metadata.model_id) || model
 
-        # Capture Anthropic prompt caching metrics
-        if response.respond_to?(:cached_tokens) && response.cached_tokens&.positive?
-          context[:cached_tokens] = response.cached_tokens
+          # Capture Anthropic prompt caching metrics
+          if metadata.respond_to?(:cached_tokens) && metadata.cached_tokens&.positive?
+            context[:cached_tokens] = metadata.cached_tokens
+          end
+          if metadata.respond_to?(:cache_creation_tokens) && metadata.cache_creation_tokens&.positive?
+            context[:cache_creation_tokens] = metadata.cache_creation_tokens
+          end
+        else
+          context.model_used = model
         end
-        if response.respond_to?(:cache_creation_tokens) && response.cache_creation_tokens&.positive?
-          context[:cache_creation_tokens] = response.cache_creation_tokens
+
+        context.finish_reason = if is_halt
+          "halt"
+        elsif response.respond_to?(:finish_reason)
+          response.finish_reason
         end
 
-        calculate_costs(response, context) if context.input_tokens
+        # Store tracked tool calls in context for instrumentation
+        context[:tool_calls] = @tracked_tool_calls if @tracked_tool_calls.any?
+
+        calculate_costs(metadata, context) if metadata && context.input_tokens
       end
 
-      # Calculates costs for the response
+      # Finds the most recent assistant message with usage metadata in
+      # the active client's history. Used to recover token/model metadata
+      # when the LLM call short-circuits via Tool::Halt.
+      #
+      # @return [RubyLLM::Message, nil]
+      def last_assistant_message_from_client
+        messages = @client&.messages
+        return nil unless messages
+
+        messages.reverse_each.find do |m|
+          m.respond_to?(:role) && m.role == :assistant &&
+            m.respond_to?(:input_tokens) && m.input_tokens
+        end
+      end
+
+      # Calculates costs for the response.
+      #
+      # Providers often return dated model variants (e.g.
+      # "anthropic/claude-4.6-sonnet-20260217") that aren't in the
+      # RubyLLM::Models registry, while the agent is configured with a
+      # stable alias (e.g. "anthropic/claude-sonnet-4.6") that is. When the
+      # response's model_id misses, fall back to the agent's configured
+      # model so cost calculation still finds pricing.
+      #
+      # Text input/output are priced from the context's token counts. These
+      # reflect the final attempt's usage (a retry/fallback overwrites them per
+      # attempt); failed attempts that erred at the provider are typically not
+      # billed, so the final attempt is the charged one. On top of the text
+      # cost, cache reads/writes and reasoning tokens — which exist on the
+      # response and are billed at their own rates — are priced via RubyLLM's
+      # first-class cost helper (RubyLLM::Cost) and added in.
       #
       # @param response [RubyLLM::Message] The response
       # @param context [Pipeline::Context] The context
       def calculate_costs(response, context)
-        model_info = find_model_info(response.model_id || model)
+        model_info = find_model_info(response.model_id) || find_model_info(model)
         return unless model_info
 
         input_tokens = context.input_tokens || 0
@@ -929,16 +1002,111 @@ module RubyLLM
         output_price = model_info.pricing&.text_tokens&.output || 0
 
         context.input_cost = (input_tokens / 1_000_000.0) * input_price
-        context.output_cost = (output_tokens / 1_000_000.0) * output_price
-        context.total_cost = (context.input_cost + context.output_cost).round(6)
+
+        # Price cache/reasoning extras first so we know whether reasoning was
+        # actually billed at the reasoning rate. Only then exclude those tokens
+        # from the output charge — never subtract tokens that weren't charged
+        # elsewhere, or a degraded cost helper would make reasoning vanish.
+        extra = extra_token_costs(response, model_info, context)
+        billable_output = output_tokens - reasoning_tokens_charged(response, context)
+        context.output_cost = ([billable_output, 0].max / 1_000_000.0) * output_price
+
+        context.total_cost = (context.input_cost + context.output_cost + extra).round(6)
+      end
+
+      # Number of reasoning (thinking) tokens that were actually charged at the
+      # reasoning rate, recorded in the cost breakdown by +extra_token_costs+.
+      #
+      # Reasoning providers fold reasoning tokens into the reported
+      # output_tokens, so when they are billed separately they must be removed
+      # from the output-rate charge to avoid double billing. Returns 0 when no
+      # reasoning was charged (non-reasoning model, or a degraded cost helper),
+      # so reasoning tokens are never silently dropped from the output charge.
+      #
+      # @param response [Object] The response (RubyLLM::Message in production)
+      # @param context [Pipeline::Context] The context
+      # @return [Integer] Reasoning tokens to exclude from the output charge
+      def reasoning_tokens_charged(response, context)
+        breakdown = context[:cost_breakdown]
+        return 0 unless breakdown.is_a?(Hash) && breakdown.key?(:thinking)
+        return 0 unless response.respond_to?(:reasoning_tokens)
+
+        response.reasoning_tokens.to_i
+      end
+
+      # Prices the non-text token components (cache reads/writes, reasoning)
+      # that RubyLLM::Cost exposes on a response, records them in metadata for
+      # visibility, and returns their sum to add on top of text input/output.
+      #
+      # Returns 0.0 for responses that don't expose cost (plain structs/mocks)
+      # or when the registry lacks the relevant prices, so cache/reasoning
+      # accuracy is additive and never regresses text pricing.
+      #
+      # @param response [Object] The response (RubyLLM::Message in production)
+      # @param model_info [RubyLLM::Model::Info] Resolved pricing source
+      # @param context [Pipeline::Context] The context
+      # @return [Float] Combined cache + reasoning cost, or 0.0
+      def extra_token_costs(response, model_info, context)
+        cost = response_cost(response, model_info)
+        return 0.0 unless cost
+
+        components = {
+          cache_read: cost.cache_read,
+          cache_write: cost.cache_write,
+          thinking: cost.thinking
+        }.compact.reject { |_, value| value.zero? }
+        return 0.0 if components.empty?
+
+        # Round per component and sum the rounded values so the stored
+        # breakdown reconciles exactly with the amount added to total_cost.
+        breakdown = components.transform_values { |value| value.round(6) }
+        context[:cost_breakdown] = breakdown
+        breakdown.values.sum
+      rescue => e
+        # Non-standard pricing shapes can't price these components; degrade to
+        # text-only rather than failing the cost calculation.
+        log_cost_warning("extra_token_costs", e)
+        0.0
+      end
+
+      # Returns a RubyLLM::Cost for the response, priced against the resolved
+      # model_info (which may differ from the response's own dated model
+      # variant). Returns nil for responses that don't expose cost — e.g.
+      # simple structs/mocks in tests — so callers skip the extra components.
+      #
+      # @param response [Object] The response (RubyLLM::Message in production)
+      # @param model_info [RubyLLM::Model::Info] Resolved pricing source
+      # @return [RubyLLM::Cost, nil]
+      def response_cost(response, model_info)
+        return nil unless response.respond_to?(:cost)
+
+        response.cost(model: model_info)
+      rescue => e
+        log_cost_warning("response_cost", e)
+        nil
+      end
+
+      # Leaves a debug breadcrumb for a swallowed cost-calculation error.
+      # Cost components are best-effort, so we degrade gracefully rather than
+      # raise, but record why instead of failing silently. Logging itself must
+      # never break cost handling.
+      #
+      # @param source [String] The method that degraded
+      # @param error [Exception] The swallowed error
+      def log_cost_warning(source, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        Rails.logger.debug("[RubyLLM::Agents] #{source} skipped: #{error.class}: #{error.message}")
+      rescue
+        nil
       end
 
-      # Finds model pricing info
+      # Finds model pricing info.
       #
       # @param model_id [String] The model ID
       # @return [Hash, nil] Model info with pricing
       def find_model_info(model_id)
-        return nil unless defined?(RubyLLM::Models)
+        return nil unless defined?(RubyLLM::Models) && model_id
 
         RubyLLM::Models.find(model_id)
       rescue

data/lib/ruby_llm/agents/core/configuration.rb

@@ -50,9 +50,26 @@ module RubyLLM
       #   When false, executions are logged synchronously.
       #   @return [Boolean] Enable async logging (default: true)
 
+      # @!attribute [rw] soft_purge_after
+      #   How long to keep full execution details (prompts, responses, tool calls,
+      #   attempts) before the retention job destroys them. The executions row is
+      #   preserved so cost, token, and latency analytics remain intact. A
+      #   truncated copy of the error message is stamped into metadata for
+      #   long-term error-rate trend analysis.
+      #   Set to nil to disable soft purging.
+      #   @return [ActiveSupport::Duration, nil] Soft-purge window (default: 30.days)
+
+      # @!attribute [rw] hard_purge_after
+      #   How long to keep the executions row itself before the retention job
+      #   destroys it entirely. Must be greater than soft_purge_after when both
+      #   are set. Set to nil to retain executions indefinitely.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window (default: 365.days)
+
       # @!attribute [rw] retention_period
-      #   How long to retain execution records before cleanup.
-      #   @return [ActiveSupport::Duration] Retention period (default: 30.days)
+      #   Deprecated. Alias for hard_purge_after, kept for backward compatibility.
+      #   Prefer configuring soft_purge_after and hard_purge_after explicitly.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window
+      #   @deprecated Use {#hard_purge_after} instead.
 
       # @!attribute [rw] anomaly_cost_threshold
       #   Cost threshold in dollars that triggers anomaly logging.
@@ -356,10 +373,18 @@ module RubyLLM
         gemini_api_base
         gpustack_api_base
         ollama_api_base
+        bedrock_api_base
+        mistral_api_base
+        perplexity_api_base
+        vertexai_api_base
         vertexai_project_id
         vertexai_location
+        xai_api_base
         request_timeout
         max_retries
+        faraday_adapter
+        deprecation_behavior
+        tool_concurrency
       ].freeze
 
       FORWARDED_RUBY_LLM_ATTRIBUTES.each do |attr|
@@ -379,7 +404,6 @@ module RubyLLM
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
         :async_logging,
-        :retention_period,
         :dashboard_parent_controller,
         :basic_auth_username,
         :basic_auth_password,
@@ -464,7 +488,9 @@ module RubyLLM
         :tenant_resolver,
         :tenant_config_resolver,
         :default_retries,
-        :budgets
+        :budgets,
+        :soft_purge_after,
+        :hard_purge_after
 
       attr_writer :cache_store
 
@@ -594,6 +620,44 @@ module RubyLLM
         @default_embedding_batch_size = value
       end
 
+      # Sets soft_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def soft_purge_after=(value)
+        validate_purge_window!(:soft_purge_after, value)
+        @soft_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Sets hard_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def hard_purge_after=(value)
+        validate_purge_window!(:hard_purge_after, value)
+        @hard_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Deprecated alias for hard_purge_after.
+      #
+      # @return [ActiveSupport::Duration, nil]
+      # @deprecated Use {#hard_purge_after} instead.
+      def retention_period
+        hard_purge_after
+      end
+
+      # Deprecated setter for retention_period (maps to hard_purge_after).
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil]
+      # @deprecated Use {#hard_purge_after=} instead.
+      def retention_period=(value)
+        warn "[DEPRECATION] RubyLLM::Agents config.retention_period is deprecated. " \
+          "Use config.hard_purge_after instead (and set config.soft_purge_after for two-tier retention)."
+        self.hard_purge_after = value
+      end
+
       # Sets default_embedding_dimensions with validation
       #
       # @param value [Integer, nil] Dimensions (must be nil or > 0)
@@ -616,7 +680,8 @@ module RubyLLM
         @default_timeout = 60
         @cache_store = nil
         @async_logging = true
-        @retention_period = 30.days
+        @soft_purge_after = 30.days
+        @hard_purge_after = 365.days
         @anomaly_cost_threshold = 5.00
         @anomaly_duration_threshold = 10_000
         @dashboard_auth = ->(_controller) { true }
@@ -960,7 +1025,8 @@ module RubyLLM
           },
           logging: {
             async_logging: async_logging,
-            retention_period: retention_period,
+            soft_purge_after: soft_purge_after,
+            hard_purge_after: hard_purge_after,
             job_retry_attempts: job_retry_attempts,
             track_executions: track_executions,
             track_cache_hits: track_cache_hits,
@@ -1161,6 +1227,30 @@ module RubyLLM
           raise ArgumentError, "budgets[:enforcement] must be :none, :soft, or :hard"
         end
       end
+
+      # Validates a purge-window value (Duration, Numeric seconds, or nil).
+      #
+      # @param attr [Symbol] Attribute name for error messages
+      # @param value [ActiveSupport::Duration, Numeric, nil] Value to validate
+      # @raise [ArgumentError] If value is neither nil nor a non-negative duration/number
+      def validate_purge_window!(attr, value)
+        return if value.nil?
+        return if value.is_a?(ActiveSupport::Duration) && value.to_i >= 0
+        return if value.is_a?(Numeric) && value >= 0
+
+        raise ArgumentError, "#{attr} must be an ActiveSupport::Duration, non-negative Numeric, or nil"
+      end
+
+      # Ensures soft_purge_after is strictly less than hard_purge_after when both are set.
+      #
+      # @raise [ArgumentError] If ordering is violated
+      def validate_purge_ordering!
+        return if @soft_purge_after.nil? || @hard_purge_after.nil?
+        return if @soft_purge_after.to_i < @hard_purge_after.to_i
+
+        raise ArgumentError, "soft_purge_after (#{@soft_purge_after.inspect}) must be less than " \
+          "hard_purge_after (#{@hard_purge_after.inspect})"
+      end
     end
   end
 end

data/lib/ruby_llm/agents/core/llm_tenant.rb

@@ -113,6 +113,11 @@ module RubyLLM
 
           # Auto-create tenant record callback
           after_create :create_default_llm_tenant if llm_tenant_options[:budget]
+
+          # Keep the denormalized Tenant#name column fresh so the dashboard's
+          # SQL search/sort by name keeps working for linked tenants. Display
+          # already resolves the name live, so this only powers SQL.
+          after_update :sync_llm_tenant_name
         end
 
         private
@@ -143,6 +148,17 @@ module RubyLLM
         send(id_method).to_s
       end
 
+      # Returns this model's tenant display name, resolved live from the
+      # configured name method (`llm_tenant name: :company_name`). Resolving on
+      # read means the tenant always reflects the current value instead of the
+      # snapshot taken when its Tenant record was first created.
+      #
+      # @return [String] The current display name
+      def llm_tenant_name
+        name_method = self.class.llm_tenant_options[:name] || :to_s
+        send(name_method).to_s
+      end
+
       # Returns API keys resolved from the DSL configuration
       #
       # Maps provider names (e.g., :openai, :anthropic) to their resolved values
@@ -354,6 +370,30 @@ module RubyLLM
         tenant.tenant_record = self
         tenant.save!
       end
+
+      # Pushes the current name into the linked Tenant row when the source
+      # column changed, keeping the denormalized copy fresh for the dashboard's
+      # SQL search/sort. Display already resolves live, so this is best-effort
+      # and never raises. Only runs when the name is backed by a column we can
+      # detect a change on (method-based names are skipped — display stays
+      # correct via live resolution, only SQL search/sort may lag for those).
+      #
+      # @return [void]
+      def sync_llm_tenant_name
+        name_method = self.class.llm_tenant_options[:name]
+        return unless name_method
+
+        change_predicate = "saved_change_to_#{name_method}?"
+        return unless respond_to?(change_predicate) && public_send(change_predicate)
+
+        record = llm_tenant_record
+        return unless record&.persisted?
+        return if record.read_attribute(:name) == llm_tenant_name
+
+        record.update_column(:name, llm_tenant_name)
+      rescue
+        nil
+      end
     end
   end
 end

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.12.0"
+    VERSION = "3.14.0"
   end
 end

data/lib/ruby_llm/agents/image/concerns/image_operation_execution.rb

@@ -95,12 +95,13 @@ module RubyLLM
         def record_failed_execution(error, started_at)
           return unless defined?(RubyLLM::Agents::Execution)
 
-          execution_data = build_failed_execution_data(error, started_at)
+          execution_data, detail_data = build_failed_execution_data(error, started_at)
 
           if config.async_logging && defined?(ExecutionLoggerJob)
-            ExecutionLoggerJob.perform_later(execution_data)
+            ExecutionLoggerJob.perform_later(execution_data.merge(_detail_data: detail_data))
           else
-            RubyLLM::Agents::Execution.create!(execution_data)
+            execution = RubyLLM::Agents::Execution.create!(execution_data)
+            execution.create_detail!(detail_data) if detail_data.present?
           end
         rescue => e
           Rails.logger.error("[RubyLLM::Agents] Failed to record failed #{execution_type} execution: #{e.message}") if defined?(Rails)
@@ -124,7 +125,7 @@ module RubyLLM
         end
 
         def build_failed_execution_data(error, started_at)
-          {
+          execution_data = {
             agent_type: self.class.name,
             tenant_id: @tenant_id,
             execution_type: execution_type,
@@ -137,9 +138,12 @@ module RubyLLM
             started_at: started_at,
             completed_at: Time.current,
             error_class: error.class.name,
-            error_message: error.message.truncate(1000),
             metadata: {}
           }
+
+          detail_data = {error_message: error.message.to_s.truncate(1000)}
+
+          [execution_data, detail_data]
         end
 
         def build_metadata(result)

data/lib/ruby_llm/agents/infrastructure/execution_logger_job.rb

@@ -37,8 +37,10 @@ module RubyLLM
           execution.create_detail!(detail_data)
         end
 
-        # Calculate costs if token data is available
-        if execution.input_tokens && execution.output_tokens
+        # Calculate costs if token data is available. Skip when the pipeline
+        # already supplied an accurate total (RubyLLM::Cost, which prices cache
+        # and reasoning tokens) so we don't downgrade it to text-only pricing.
+        if execution.input_tokens && execution.output_tokens && !execution.total_cost&.positive?
           execution.calculate_costs!
           execution.save!
         end

data/lib/ruby_llm/agents/infrastructure/retention_job.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Background job that enforces two-tier data retention on execution records.
+    #
+    # Soft pass: for executions older than {Configuration#soft_purge_after},
+    # destroys the associated execution_details and tool_executions rows,
+    # preserves a truncated copy of error_message in metadata, and stamps
+    # metadata["soft_purged_at"] so the dashboard can surface the state and
+    # the pass stays idempotent.
+    #
+    # Hard pass: for executions older than {Configuration#hard_purge_after},
+    # destroys the executions row itself. The foreign-key cascade removes
+    # any remaining details or tool_executions.
+    #
+    # Either tier may be set to nil in configuration to skip that pass.
+    #
+    # @example Enqueue manually
+    #   RubyLLM::Agents::RetentionJob.perform_later
+    #
+    # @example Schedule daily (whenever gem)
+    #   every 1.day, at: "3:00 am" do
+    #     runner "RubyLLM::Agents::RetentionJob.perform_later"
+    #   end
+    #
+    # @api public
+    class RetentionJob < ActiveJob::Base
+      queue_as :default
+
+      ERROR_MESSAGE_MAX_LENGTH = 500
+      BATCH_SIZE = 500
+
+      # Runs the soft and hard retention passes based on current configuration.
+      #
+      # @return [Hash] counts of rows affected in each pass
+      def perform
+        {
+          soft_purged: soft_purge,
+          hard_purged: hard_purge
+        }
+      end
+
+      private
+
+      # Destroys detail + tool_execution rows for executions older than the
+      # soft-purge window that have not already been soft-purged. Stamps
+      # metadata with the purge timestamp and preserves a truncated
+      # error_message for long-term error-rate analytics.
+      #
+      # The "already purged" filter runs in Ruby rather than SQL because
+      # JSON key-exists operators differ across SQLite/Postgres/MySQL; this
+      # keeps the job adapter-agnostic. We batch to bound memory.
+      def soft_purge
+        window = RubyLLM::Agents.configuration.soft_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        count = 0
+
+        Execution
+          .where("created_at < ?", cutoff)
+          .includes(:detail)
+          .find_in_batches(batch_size: BATCH_SIZE) do |batch|
+            batch.each do |execution|
+              next if execution.soft_purged?
+
+              purge_one(execution)
+              count += 1
+            end
+          end
+
+        count
+      end
+
+      # Destroys executions (and everything cascaded from them) older than
+      # the hard-purge window.
+      def hard_purge
+        window = RubyLLM::Agents.configuration.hard_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        total = 0
+
+        Execution.where("created_at < ?", cutoff).in_batches(of: BATCH_SIZE) do |batch|
+          total += batch.destroy_all.size
+        end
+
+        total
+      end
+
+      # Performs the soft purge for a single execution.
+      def purge_one(execution)
+        preserved_error = preserved_error_message(execution)
+
+        Execution.transaction do
+          execution.detail&.destroy
+          execution.tool_executions.destroy_all
+
+          new_metadata = (execution.metadata || {}).merge(
+            "soft_purged_at" => Time.current.iso8601
+          )
+          new_metadata["error_message"] = preserved_error if preserved_error
+
+          execution.update_columns(metadata: new_metadata)
+        end
+      end
+
+      # Returns a truncated copy of the detail's error_message, or nil.
+      def preserved_error_message(execution)
+        raw = execution.detail&.error_message
+        return nil if raw.blank?
+
+        raw.to_s.truncate(ERROR_MESSAGE_MAX_LENGTH)
+      end
+    end
+  end
+end