ruby_llm-agents 3.8.0 → 3.10.0

data/lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb

@@ -39,45 +39,47 @@ module RubyLLM
           def call(context)
             context.started_at = Time.current
 
-            # Create "running" record immediately (SYNC - must appear on dashboard)
-            execution = create_running_execution(context)
-            context.execution_id = execution&.id
-            emit_start_notification(context)
-            status_update_completed = false
-            raised_exception = nil
-
-            begin
-              @app.call(context)
-              context.completed_at = Time.current
-
-              begin
-                complete_execution(execution, context, status: "success")
-                status_update_completed = true
-              rescue
-                # Let ensure block handle via mark_execution_failed!
-              end
-
-              emit_complete_notification(context, "success")
-            rescue => e
-              context.completed_at = Time.current
-              context.error = e
-              raised_exception = e
+            trace(context) do
+              # Create "running" record immediately (SYNC - must appear on dashboard)
+              execution = create_running_execution(context)
+              context.execution_id = execution&.id
+              emit_start_notification(context)
+              status_update_completed = false
+              raised_exception = nil
 
               begin
-                complete_execution(execution, context, status: determine_error_status(e))
-                status_update_completed = true
-              rescue
-                # Let ensure block handle via mark_execution_failed!
+                @app.call(context)
+                context.completed_at = Time.current
+
+                begin
+                  complete_execution(execution, context, status: "success")
+                  status_update_completed = true
+                rescue
+                  # Let ensure block handle via mark_execution_failed!
+                end
+
+                emit_complete_notification(context, "success")
+              rescue => e
+                context.completed_at = Time.current
+                context.error = e
+                raised_exception = e
+
+                begin
+                  complete_execution(execution, context, status: determine_error_status(e))
+                  status_update_completed = true
+                rescue
+                  # Let ensure block handle via mark_execution_failed!
+                end
+
+                emit_complete_notification(context, determine_error_status(e))
+                raise
+              ensure
+                # Emergency fallback if update failed
+                mark_execution_failed!(execution, error: raised_exception || $!) unless status_update_completed
               end
 
-              emit_complete_notification(context, determine_error_status(e))
-              raise
-            ensure
-              # Emergency fallback if update failed
-              mark_execution_failed!(execution, error: raised_exception || $!) unless status_update_completed
+              context
             end
-
-            context
           end
 
           private
@@ -111,7 +113,7 @@ module RubyLLM
 
             execution
           rescue => e
-            error("Failed to create running execution record: #{e.message}")
+            error("Failed to create running execution record: #{e.message}", context)
             nil
           end
 
@@ -142,7 +144,7 @@ module RubyLLM
             # Save detail data (prompts, responses, tool calls, etc.)
             save_execution_details(execution, context, status)
           rescue => e
-            error("Failed to complete execution record: #{e.message}")
+            error("Failed to complete execution record: #{e.message}", context)
             raise # Re-raise for ensure block to handle via mark_execution_failed!
           end
 
@@ -158,7 +160,7 @@ module RubyLLM
             return unless execution&.id
             return unless execution.status == "running"
 
-            error_message = error ? "#{error.class}: #{error.message}".truncate(1000) : "Unknown error"
+            error_message = build_error_message(error)
 
             update_data = {
               status: "error",
@@ -183,6 +185,28 @@ module RubyLLM
             error("CRITICAL: Failed emergency status update for execution #{execution&.id}: #{e.message}")
           end
 
+          # Builds an informative error message including backtrace context
+          #
+          # Preserves the error class, message, and the most relevant
+          # backtrace frames (up to 10) so developers can trace the
+          # failure origin without needing to reproduce it.
+          #
+          # @param error [Exception, nil] The exception
+          # @return [String] Formatted error message with backtrace
+          def build_error_message(error)
+            return "Unknown error" unless error
+
+            parts = ["#{error.class}: #{error.message}"]
+
+            if error.backtrace&.any?
+              relevant_frames = error.backtrace.first(10)
+              parts << "Backtrace (first #{relevant_frames.size} frames):"
+              parts.concat(relevant_frames.map { |frame| "  #{frame}" })
+            end
+
+            parts.join("\n").truncate(5000)
+          end
+
           # Determines the status based on error type
           #
           # @param error [Exception] The exception that occurred
@@ -206,7 +230,7 @@ module RubyLLM
               execution_id: context.execution_id
             )
           rescue => e
-            debug("Start notification failed: #{e.message}")
+            debug("Start notification failed: #{e.message}", context)
           end
 
           # Emits an AS::Notification for execution completion or error
@@ -243,7 +267,7 @@ module RubyLLM
               error_message: context.error&.message
             )
           rescue => e
-            debug("Complete notification failed: #{e.message}")
+            debug("Complete notification failed: #{e.message}", context)
           end
 
           # Builds data for initial running execution record
@@ -295,6 +319,9 @@ module RubyLLM
               data[:root_execution_id] = context.root_execution_id || context.parent_execution_id
             end
 
+            # Inject tracker request_id and tags
+            inject_tracker_data(context, data)
+
             data
           end
 
@@ -322,7 +349,7 @@ module RubyLLM
             context_meta = begin
               context.metadata.dup
             rescue => e
-              debug("Failed to read context metadata: #{e.message}")
+              debug("Failed to read context metadata: #{e.message}", context)
               {}
             end
             context_meta.transform_keys!(&:to_s)
@@ -365,7 +392,7 @@ module RubyLLM
             end
 
             if context.error
-              detail_data[:error_message] = truncate_error_message(context.error.message)
+              detail_data[:error_message] = build_error_message(context.error)
             end
 
             if context[:tool_calls].present?
@@ -392,7 +419,7 @@ module RubyLLM
               execution.create_detail!(detail_data)
             end
           rescue => e
-            error("Failed to save execution details: #{e.message}")
+            error("Failed to save execution details: #{e.message}", context)
           end
 
           # Persists execution data to database (legacy fallback)
@@ -412,7 +439,7 @@ module RubyLLM
               create_execution_record(data)
             end
           rescue => e
-            error("Failed to record execution: #{e.message}")
+            error("Failed to record execution: #{e.message}", context)
           end
 
           # Builds execution data hash for the legacy single-step persistence path.
@@ -435,7 +462,7 @@ module RubyLLM
               detail_data[:user_prompt] = context.input.to_s.presence
               detail_data[:assistant_prompt] = exec_opts[:assistant_prefill] if assistant_prompt_column_exists?
             end
-            detail_data[:error_message] = truncate_error_message(context.error.message) if context.error
+            detail_data[:error_message] = build_error_message(context.error) if context.error
             detail_data[:tool_calls] = context[:tool_calls] if context[:tool_calls].present?
             detail_data[:attempts] = context[:reliability_attempts] if context[:reliability_attempts].present?
             if global_config.persist_responses && context.output.respond_to?(:content)
@@ -474,7 +501,7 @@ module RubyLLM
             params = begin
               context.agent_instance.send(:options)
             rescue => e
-              debug("Failed to extract agent options: #{e.message}")
+              debug("Failed to extract agent options: #{e.message}", context)
               {}
             end
             params = params.dup
@@ -505,10 +532,38 @@ module RubyLLM
             result = context.agent_instance.metadata
             result.is_a?(Hash) ? result : {}
           rescue => e
-            debug("Failed to retrieve agent metadata: #{e.message}")
+            debug("Failed to retrieve agent metadata: #{e.message}", context)
             {}
           end
 
+          # Injects tracker request_id and tags into execution data
+          #
+          # Reads @_track_request_id and @_track_tags from the agent instance,
+          # which are set by BaseAgent#initialize when a Tracker is active.
+          #
+          # @param context [Context] The execution context
+          # @param data [Hash] The execution data hash to modify
+          def inject_tracker_data(context, data)
+            agent = context.agent_instance
+            return unless agent
+
+            # Inject request_id
+            track_request_id = agent.instance_variable_get(:@_track_request_id)
+            if track_request_id && data[:request_id].blank?
+              data[:request_id] = track_request_id
+            end
+
+            # Merge tracker tags into metadata
+            track_tags = agent.instance_variable_get(:@_track_tags)
+            if track_tags.is_a?(Hash) && track_tags.any?
+              data[:metadata] = (data[:metadata] || {}).merge(
+                "tags" => track_tags.transform_keys(&:to_s)
+              )
+            end
+          rescue
+            # Never let tracker data injection break execution
+          end
+
           # Sensitive parameter keys that should be redacted
           SENSITIVE_KEYS = %w[
             password token api_key secret credential auth key
@@ -527,7 +582,7 @@ module RubyLLM
           def truncate_error_message(message)
             return "" if message.nil?
 
-            message.to_s.truncate(1000)
+            message.to_s.truncate(5000)
           rescue
             message.to_s[0, 1000]
           end
@@ -554,7 +609,7 @@ module RubyLLM
 
             response_data
           rescue => e
-            error("Failed to serialize response: #{e.message}")
+            error("Failed to serialize response: #{e.message}", context)
             nil
           end
 
@@ -581,7 +636,7 @@ module RubyLLM
 
             detail_data[:response] = serialize_audio_response(context.output)
           rescue => e
-            error("Failed to persist audio response: #{e.message}")
+            error("Failed to persist audio response: #{e.message}", context)
           end
 
           # Serializes a SpeechResult into a hash for the response column
@@ -637,7 +692,7 @@ module RubyLLM
               cfg.track_executions
             end
           rescue => e
-            debug("Failed to check tracking config: #{e.message}")
+            debug("Failed to check tracking config: #{e.message}", context)
             false
           end
 

data/lib/ruby_llm/agents/pipeline/middleware/reliability.rb

@@ -41,11 +41,13 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless reliability_enabled?
 
-            config = reliability_config
-            models_to_try = build_models_list(context, config)
-            total_deadline = calculate_deadline(config)
+            trace(context) do
+              config = reliability_config
+              models_to_try = build_models_list(context, config)
+              total_deadline = calculate_deadline(config)
 
-            execute_with_reliability(context, models_to_try, config, total_deadline)
+              execute_with_reliability(context, models_to_try, config, total_deadline)
+            end
           end
 
           private
@@ -103,7 +105,7 @@ module RubyLLM
               # Check circuit breaker for this model
               breaker = get_circuit_breaker(current_model, context)
               if breaker&.open?
-                debug("Circuit breaker open for #{current_model}, skipping")
+                debug("Circuit breaker open for #{current_model}, skipping", context)
                 tracker.record_short_circuit(current_model)
                 next
               end

data/lib/ruby_llm/agents/pipeline/middleware/tenant.rb

@@ -41,10 +41,12 @@ module RubyLLM
           # @param context [Context] The execution context
           # @return [Context] The context with tenant fields populated
           def call(context)
-            resolve_tenant!(context)
-            ensure_tenant_record!(context)
-            apply_api_configuration!(context)
-            @app.call(context)
+            trace(context) do
+              resolve_tenant!(context)
+              ensure_tenant_record!(context)
+              apply_api_configuration!(context)
+              @app.call(context)
+            end
           end
 
           private

data/lib/ruby_llm/agents/rails/engine.rb

@@ -53,6 +53,17 @@ module RubyLLM
           helper RubyLLM::Agents::ApplicationHelper
           before_action :authenticate_dashboard!
 
+          rescue_from ::ActiveRecord::StatementInvalid do |e|
+            if e.message.include?("ruby_llm_agents_")
+              render plain: "RubyLLM::Agents migrations are pending.\n\n" \
+                           "Run: rails db:migrate\n" \
+                           "Or:  rails ruby_llm_agents:doctor",
+                status: :service_unavailable
+            else
+              raise
+            end
+          end
+
           private
 
           # Authenticates dashboard access using configured method

data/lib/ruby_llm/agents/results/background_removal_result.rb

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?   # => true
     #
     class BackgroundRemovalResult
+      include Trackable
+
       attr_reader :foreground, :mask, :source_image, :model_id, :output_format,
         :alpha_matting, :refine_edges,
         :started_at, :completed_at, :tenant_id, :remover_class,
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(foreground:, mask:, source_image:, model_id:, output_format:,
         alpha_matting:, refine_edges:, started_at:, completed_at:,
-        tenant_id:, remover_class:, error_class: nil, error_message: nil)
+        tenant_id:, remover_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @foreground = foreground
         @mask = mask
         @source_image = source_image
@@ -53,6 +55,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/base.rb

@@ -107,6 +107,21 @@ module RubyLLM
       #   @return [Integer, nil] Database ID of the associated Execution record
       attr_reader :execution_id
 
+      # @!group Tracking
+      # @!attribute [r] agent_class_name
+      #   @return [String, nil] The agent class that produced this result
+      attr_reader :agent_class_name
+
+      # @!group Cancellation
+      # @!attribute [r] cancelled
+      #   @return [Boolean] Whether the execution was cancelled
+      attr_reader :cancelled
+
+      # @!group Debug
+      # @!attribute [r] trace
+      #   @return [Array<Hash>, nil] Pipeline trace entries (when debug: true)
+      attr_reader :trace
+
       # Creates a new Result instance
       #
       # @param content [Hash, String] The processed response content
@@ -159,6 +174,19 @@ module RubyLLM
 
         # Execution record
         @execution_id = options[:execution_id]
+
+        # Tracking
+        @agent_class_name = options[:agent_class_name]
+
+        # Cancellation
+        @cancelled = options[:cancelled] || false
+
+        # Debug trace
+        @trace = options[:trace]
+
+        # Register with active tracker
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        tracker << self if tracker
       end
 
       # Loads the associated Execution record from the database
@@ -202,6 +230,13 @@ module RubyLLM
         !success?
       end
 
+      # Returns whether the execution was cancelled
+      #
+      # @return [Boolean] true if cancelled
+      def cancelled?
+        cancelled == true
+      end
+
       # Returns whether a fallback model was used
       #
       # @return [Boolean] true if chosen_model_id differs from model_id
@@ -264,8 +299,10 @@ module RubyLLM
           thinking_text: thinking_text,
           thinking_signature: thinking_signature,
           thinking_tokens: thinking_tokens,
-          execution_id: execution_id
-        }
+          execution_id: execution_id,
+          agent_class_name: agent_class_name,
+          trace: trace
+        }.compact
       end
 
       # @!group Deprecated Hash Delegation

data/lib/ruby_llm/agents/results/embedding_result.rb

@@ -25,6 +25,8 @@ module RubyLLM
     #
     # @api public
     class EmbeddingResult
+      include Trackable
+
       # @!attribute [r] vectors
       #   @return [Array<Array<Float>>] The embedding vectors
       attr_reader :vectors
@@ -106,6 +108,8 @@ module RubyLLM
         @error_class = attributes[:error_class]
         @error_message = attributes[:error_message]
         @execution_id = attributes[:execution_id]
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_analysis_result.rb

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageAnalysisResult
+      include Trackable
+
       attr_reader :image, :model_id, :analysis_type,
         :caption, :description, :tags, :objects, :colors, :text,
         :raw_response, :started_at, :completed_at, :tenant_id, :analyzer_class,
@@ -43,7 +45,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(image:, model_id:, analysis_type:, caption:, description:, tags:,
         objects:, colors:, text:, raw_response:, started_at:, completed_at:,
-        tenant_id:, analyzer_class:, error_class: nil, error_message: nil)
+        tenant_id:, analyzer_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @model_id = model_id
         @analysis_type = analysis_type
@@ -61,6 +63,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_edit_result.rb

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageEditResult
+      include Trackable
+
       attr_reader :images, :source_image, :mask, :prompt, :model_id, :size,
         :started_at, :completed_at, :tenant_id, :editor_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, mask:, prompt:, model_id:, size:,
         started_at:, completed_at:, tenant_id:, editor_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @mask = mask
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_generation_result.rb

@@ -20,6 +20,8 @@ module RubyLLM
     #   result.save_all("./logos")
     #
     class ImageGenerationResult
+      include Trackable
+
       attr_reader :images, :prompt, :model_id, :size, :quality, :style,
         :started_at, :completed_at, :tenant_id, :generator_class,
         :error_class, :error_message, :execution_id
@@ -40,7 +42,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, prompt:, model_id:, size:, quality:, style:,
         started_at:, completed_at:, tenant_id:, generator_class:,
-        error_class: nil, error_message: nil, execution_id: nil)
+        error_class: nil, error_message: nil, execution_id: nil, agent_class_name: nil)
         @images = images
         @prompt = prompt
         @model_id = model_id
@@ -54,6 +56,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = execution_id
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_pipeline_result.rb

@@ -21,6 +21,8 @@ module RubyLLM
     #   result.analysis          # => Shortcut to analyzer step result
     #
     class ImagePipelineResult
+      include Trackable
+
       attr_reader :step_results, :started_at, :completed_at, :tenant_id,
         :pipeline_class, :context, :error_class, :error_message
       attr_accessor :execution_id
@@ -36,7 +38,7 @@ module RubyLLM
       # @param error_class [String, nil] Error class name if failed
       # @param error_message [String, nil] Error message if failed
       def initialize(step_results:, started_at:, completed_at:, tenant_id:,
-        pipeline_class:, context:, error_class: nil, error_message: nil)
+        pipeline_class:, context:, error_class: nil, error_message: nil, agent_class_name: nil)
         @step_results = step_results
         @started_at = started_at
         @completed_at = completed_at
@@ -46,6 +48,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_transform_result.rb

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageTransformResult
+      include Trackable
+
       attr_reader :images, :source_image, :prompt, :model_id, :size, :strength,
         :started_at, :completed_at, :tenant_id, :transformer_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, prompt:, model_id:, size:, strength:,
         started_at:, completed_at:, tenant_id:, transformer_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @prompt = prompt
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_upscale_result.rb

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageUpscaleResult
+      include Trackable
+
       attr_reader :image, :source_image, :model_id, :scale, :output_size, :face_enhance,
         :started_at, :completed_at, :tenant_id, :upscaler_class,
         :error_class, :error_message
@@ -36,7 +38,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(image:, source_image:, model_id:, scale:, output_size:, face_enhance:,
         started_at:, completed_at:, tenant_id:, upscaler_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @source_image = source_image
         @model_id = model_id
@@ -50,6 +52,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/results/image_variation_result.rb

@@ -14,6 +14,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageVariationResult
+      include Trackable
+
       attr_reader :images, :source_image, :model_id, :size, :variation_strength,
         :started_at, :completed_at, :tenant_id, :variator_class,
         :error_class, :error_message
@@ -34,7 +36,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, model_id:, size:, variation_strength:,
         started_at:, completed_at:, tenant_id:, variator_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @model_id = model_id
@@ -47,6 +49,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database