activeagent 1.0.3 → 1.1.0

data/lib/active_agent/model_capabilities.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Per-model capability quirks, applied before a request reaches the
+  # provider. Vendors ship models that reject otherwise-standard sampling
+  # parameters (thinking-first models steered by prompting/effort instead)
+  # with an API 400 — this registry strips those parameters up front so an
+  # agent configured with a shared temperature keeps working across model
+  # switches.
+  #
+  # The built-in rules cover the known families; apps can extend the
+  # registry for new or self-hosted models:
+  #
+  # @example Register a custom rule
+  #   ActiveAgent::ModelCapabilities.register(/\Amy-reasoning-model/, unsupported: [:temperature, :top_p])
+  #
+  # @example Disable sanitization entirely
+  #   ActiveAgent::ModelCapabilities.enabled = false
+  module ModelCapabilities
+    SAMPLING_PARAMS = [ :temperature, :top_p ].freeze
+
+    # Model families that reject sampling parameters with a 400:
+    # - Anthropic thinking-first models (Opus 4.7+, Opus 5, Sonnet 5,
+    #   Fable 5 / Mythos 5)
+    # - OpenAI reasoning models (o-series, GPT-5 family)
+    BUILTIN_RULES = [
+      { pattern: /\Aclaude-(opus-5|opus-4-[78]|sonnet-5|fable-5|mythos-5)/, unsupported: SAMPLING_PARAMS },
+      { pattern: /\A(o1|o3|o4)(-|$)/, unsupported: SAMPLING_PARAMS },
+      { pattern: /\Agpt-5/, unsupported: SAMPLING_PARAMS }
+    ].freeze
+
+    class << self
+      # Master switch; on by default. Set false to send parameters through
+      # untouched (the vendor then enforces its own rules).
+      attr_writer :enabled
+
+      def enabled
+        return @enabled unless @enabled.nil?
+
+        true
+      end
+
+      # Registers an app-defined capability rule ahead of the built-ins.
+      #
+      # @param pattern [Regexp] matched against the model name
+      # @param unsupported [Array<Symbol>] parameter keys the model rejects
+      def register(pattern, unsupported:)
+        custom_rules << { pattern: pattern, unsupported: unsupported.map(&:to_sym) }
+      end
+
+      def custom_rules
+        @custom_rules ||= []
+      end
+
+      def reset!
+        @custom_rules = []
+        @enabled = nil
+      end
+
+      # @return [Array<Symbol>] parameter keys the model rejects
+      def unsupported_params(model)
+        return [] if model.nil?
+
+        (custom_rules + BUILTIN_RULES).each do |rule|
+          return rule[:unsupported] if model.to_s.match?(rule[:pattern])
+        end
+        []
+      end
+
+      def sampling_supported?(model)
+        (unsupported_params(model) & SAMPLING_PARAMS).empty?
+      end
+
+      # Strips parameters the model rejects, in place. Returns the removed
+      # keys (empty when nothing applied).
+      #
+      # @param parameters [Hash] prepared prompt parameters (must carry :model)
+      # @return [Array<Symbol>] removed parameter keys
+      def sanitize!(parameters)
+        return [] unless enabled
+        return [] unless parameters.is_a?(Hash)
+
+        removed = unsupported_params(parameters[:model]).select { |key| parameters.key?(key) }
+        removed.each { |key| parameters.delete(key) }
+        removed
+      end
+    end
+  end
+end

data/lib/active_agent/providers/_base_provider.rb

@@ -55,7 +55,13 @@ module ActiveAgent
                     :request, :message_stack,        # Runtime
                     :stream_broadcaster, :streaming, # Callback (Streams)
                     :tools_function,                 # Callback (Tools)
-                    :usage_stack                     # Usage Tracking
+                    :usage_stack,                    # Usage Tracking
+                    :max_tool_turns, :tool_turns     # Tool-loop safety
+
+      # Upper bound on tool-calling round-trips within one generation. A
+      # model that keeps emitting tool calls otherwise recurses until the
+      # provider stops it — override per agent/prompt with max_tool_turns:.
+      DEFAULT_MAX_TOOL_TURNS = 25
 
       # @return [String] e.g., "Anthropic", "OpenAI"
       def self.service_name
@@ -106,6 +112,8 @@ module ActiveAgent
         self.stream_broadcaster = kwargs.delete(:stream_broadcaster)
         self.streaming          = false
         self.tools_function     = kwargs.delete(:tools_function)
+        self.max_tool_turns     = kwargs.delete(:max_tool_turns) || DEFAULT_MAX_TOOL_TURNS
+        self.tool_turns         = 0
         self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
         self.context            = kwargs
         self.message_stack      = []
@@ -344,7 +352,7 @@ module ActiveAgent
           message_stack.push(*api_messages)
         end
 
-        if (tool_calls = process_prompt_finished_extract_function_calls)&.any?
+        if (tool_calls = process_prompt_finished_extract_function_calls)&.any? && tool_turn_allowed?
           process_function_calls(tool_calls)
           resolve_prompt
         else
@@ -373,6 +381,19 @@ module ActiveAgent
         end
       end
 
+      # Counts a tool round-trip against the per-generation cap. When the
+      # cap is hit the loop finishes cleanly with the messages gathered so
+      # far (a partial result) instead of recursing indefinitely.
+      #
+      # @return [Boolean] whether another tool round-trip may run
+      def tool_turn_allowed?
+        self.tool_turns += 1
+        return true if max_tool_turns.nil? || tool_turns <= max_tool_turns
+
+        instrument("tool_turns_exceeded.active_agent", limit: max_tool_turns)
+        false
+      end
+
       # @abstract
       # @param api_response [Object]
       # @return [Array<Message>, nil]

data/lib/active_agent/providers/concerns/exception_handler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+
 module ActiveAgent
   module Providers
     # Provides exception handling for provider operations.
@@ -54,7 +56,16 @@ module ActiveAgent
       def with_exception_handling(&block)
         yield
       rescue => exception
-        rescue_with_handler(exception) || raise
+        # Vendor API failures are normalized into the framework taxonomy
+        # (Errors::RateLimited, Errors::ContextLengthExceeded, ...) so
+        # rescue_from policy is portable across providers; the original
+        # exception is preserved as #cause. Anything unrecognizable —
+        # including ordinary Ruby errors — passes through untouched.
+        exception = Errors::Taxonomy.normalize(
+          exception,
+          provider_tag: (tag_name if respond_to?(:tag_name))
+        )
+        rescue_with_handler(exception) || raise(exception)
         nil # Discard handler return value to prevent polluting raw_response
       end
 

data/lib/active_agent/providers/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Typed provider failures, normalized across vendor SDKs.
+    #
+    # Every vendor raises its own exception classes for the same underlying
+    # conditions (rate limits, context overflows, content filters, outages),
+    # which makes retry/backoff/fallback policy impossible to express
+    # portably. The taxonomy classifies vendor errors into a small set of
+    # framework types — the original exception is preserved as +#cause+, so
+    # nothing is lost.
+    #
+    # @example Portable retry policy
+    #   rescue_from ActiveAgent::Providers::Errors::RateLimited do |error|
+    #     retry_job wait: 30.seconds
+    #   end
+    #
+    # @example Fallback on outage
+    #   rescue_from ActiveAgent::Providers::Errors::ServiceUnavailable do |error|
+    #     FallbackAgent.with(params).ask.generate_later
+    #   end
+    module Errors
+      # Base class for normalized provider failures.
+      class ProviderError < StandardError
+        # @return [Integer, nil] HTTP status from the vendor error, when known
+        attr_reader :status
+
+        # @return [String, nil] provider tag (e.g. "Anthropic", "OpenAI::Chat")
+        attr_reader :provider_tag
+
+        def initialize(message = nil, status: nil, provider_tag: nil)
+          super(message)
+          @status = status
+          @provider_tag = provider_tag
+        end
+      end
+
+      # 429s / vendor rate & quota limits. Retryable with backoff.
+      class RateLimited < ProviderError; end
+
+      # The prompt exceeded the model's context window. Not retryable
+      # without shrinking the input.
+      class ContextLengthExceeded < ProviderError; end
+
+      # Invalid, expired, or unauthorized credentials (401/403).
+      class AuthenticationFailed < ProviderError; end
+
+      # The vendor's safety layer refused the request or response.
+      class ContentFiltered < ProviderError; end
+
+      # Vendor-side failure or overload (5xx, timeouts, connection drops).
+      # Retryable; a natural trigger for provider fallback.
+      class ServiceUnavailable < ProviderError; end
+
+      # Malformed or unsupported request the vendor rejected (400/422)
+      # that doesn't classify more specifically.
+      class InvalidRequest < ProviderError; end
+
+      # Classifies vendor SDK exceptions into the taxonomy. Unrecognizable
+      # exceptions (including ordinary Ruby errors) pass through untouched —
+      # only errors that look like vendor API failures are normalized.
+      module Taxonomy
+        # Vendor SDK class names (demodulized) → taxonomy class. Covers the
+        # official anthropic/openai gems and SDKs following their naming.
+        NAME_MAP = {
+          "RateLimitError" => RateLimited,
+          "AuthenticationError" => AuthenticationFailed,
+          "PermissionDeniedError" => AuthenticationFailed,
+          "ContentFilterError" => ContentFiltered,
+          "InternalServerError" => ServiceUnavailable,
+          "APIConnectionError" => ServiceUnavailable,
+          "APIConnectionTimeoutError" => ServiceUnavailable,
+          "APITimeoutError" => ServiceUnavailable,
+          "OverloadedError" => ServiceUnavailable,
+          "ServiceUnavailableError" => ServiceUnavailable,
+          "BadRequestError" => InvalidRequest,
+          "UnprocessableEntityError" => InvalidRequest
+        }.freeze
+
+        STATUS_MAP = {
+          400 => InvalidRequest,
+          401 => AuthenticationFailed,
+          403 => AuthenticationFailed,
+          408 => ServiceUnavailable,
+          422 => InvalidRequest,
+          429 => RateLimited,
+          529 => ServiceUnavailable # Anthropic "overloaded"
+        }.freeze
+
+        CONTEXT_LENGTH_PATTERN = /context length|context_length|maximum context|context window|too many tokens|prompt is too long|input (?:is )?too long/i
+        CONTENT_FILTER_PATTERN = /content (?:filter|policy|management)|filtered due to|blocked by|safety (?:system|filter)/i
+
+        class << self
+          # @param exception [Exception]
+          # @param provider_tag [String, nil]
+          # @return [Exception] a taxonomy error, or the original exception
+          #   when it doesn't classify
+          def normalize(exception, provider_tag: nil)
+            return exception if exception.is_a?(ProviderError)
+
+            klass = classify(exception)
+            return exception unless klass
+
+            klass.new(exception.message, status: status_of(exception), provider_tag: provider_tag)
+          end
+
+          # @return [Class, nil]
+          def classify(exception)
+            name = exception.class.name.to_s.demodulize
+            status = status_of(exception)
+            api_error = NAME_MAP.key?(name) || !status.nil?
+            return nil unless api_error
+
+            message = exception.message.to_s
+            return ContextLengthExceeded if CONTEXT_LENGTH_PATTERN.match?(message)
+            return ContentFiltered if CONTENT_FILTER_PATTERN.match?(message)
+
+            NAME_MAP[name] || STATUS_MAP[status] || (status && status >= 500 ? ServiceUnavailable : nil)
+          end
+
+          # @return [Integer, nil]
+          def status_of(exception)
+            [ :status, :status_code, :http_status, :code ].each do |reader|
+              next unless exception.respond_to?(reader)
+
+              value = begin
+                exception.public_send(reader)
+              rescue StandardError
+                nil
+              end
+              return value if value.is_a?(Integer)
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/ollama/chat/transforms.rb

@@ -55,12 +55,18 @@ module ActiveAgent
               OpenAI::Chat::Transforms.normalize_messages(messages)
             end
 
-            # Normalizes instructions using OpenAI transforms
+            # Normalizes instructions using OpenAI transforms, then remaps the
+            # role: OpenAI's transforms emit the "developer" role, but the chat
+            # templates of Ollama-served models (qwen, llama, gemma, …) only
+            # know "system" — a "developer" message is silently dropped, so the
+            # model never sees its instructions.
             #
             # @param instructions [Array<String>, String]
-            # @return [Array<OpenAI::Models::Chat::ChatCompletionMessageParam>]
+            # @return [Array<Hash>] system messages
             def normalize_instructions(instructions)
-              OpenAI::Chat::Transforms.normalize_instructions(instructions)
+              OpenAI::Chat::Transforms.normalize_instructions(instructions).map do |message|
+                message.is_a?(Hash) ? message.merge(role: "system") : message
+              end
             end
 
             # Cleans up serialized request for API submission

data/lib/active_agent/railtie.rb

@@ -67,6 +67,11 @@ module ActiveAgent
           include ActiveAgent::Telemetry::Instrumentation
           instrument_telemetry!
         end
+
+        # Flush remaining traces when the process exits — without this,
+        # short-lived processes (rails runner, jobs, deploys rolling a
+        # server) drop whatever was buffered since the last interval flush.
+        at_exit { ActiveAgent::Telemetry.shutdown }
       end
       # endregion telemetry_configuration
 

data/lib/active_agent/telemetry/configuration.rb

@@ -2,212 +2,152 @@
 
 module ActiveAgent
   module Telemetry
-    # Configuration for telemetry collection and reporting.
+    # The framework's telemetry configuration, now provided by the
+    # activeagents-telemetry gem. This subclass keeps the framework's
+    # historical behavior on top of the shared core:
     #
-    # Stores settings for endpoint, authentication, sampling, and batching.
-    # Configuration can be set programmatically or loaded from YAML.
+    # * telemetry is opt-in (`enabled` defaults to false)
+    # * `local_storage: true` persists traces through the dashboard's trace
+    #   model instead of HTTP
     #
-    # @example Programmatic configuration
-    #   ActiveAgent::Telemetry.configure do |config|
-    #     config.enabled = true
-    #     config.endpoint = "https://api.activeagents.ai/v1/traces"
-    #     config.api_key = "your-api-key"
-    #     config.sample_rate = 1.0
-    #   end
+    # Every other option — endpoint, api_key, sample_rate, batch_size,
+    # flush_interval, capture_bodies, redact_attributes, service_name,
+    # environment, resource_attributes — lives on the shared class, so
+    # existing config/active_agent.yml files keep working unchanged.
     #
-    # @example YAML configuration (config/activeagent.yml)
-    #   telemetry:
-    #     enabled: true
-    #     endpoint: https://api.activeagents.ai/v1/traces
-    #     api_key: <%= ENV["ACTIVEAGENTS_API_KEY"] %>
-    #     sample_rate: 1.0
-    #     batch_size: 100
-    #     flush_interval: 5
-    #
-    class Configuration
-      # @return [Boolean] Whether telemetry is enabled (default: false)
-      attr_accessor :enabled
-
-      # @return [String] The endpoint URL for sending traces
-      attr_accessor :endpoint
-
-      # @return [String] API key for authentication
-      attr_accessor :api_key
-
-      # @return [Float] Sampling rate from 0.0 to 1.0 (default: 1.0)
-      attr_accessor :sample_rate
-
-      # @return [Integer] Number of traces to batch before sending (default: 100)
-      attr_accessor :batch_size
-
-      # @return [Integer] Seconds between automatic flushes (default: 5)
-      attr_accessor :flush_interval
-
-      # @return [Integer] HTTP timeout in seconds (default: 10)
-      attr_accessor :timeout
-
-      # @return [Boolean] Whether to capture request/response bodies (default: false)
-      attr_accessor :capture_bodies
-
-      # @return [Array<String>] Attributes to redact from traces
-      attr_accessor :redact_attributes
-
-      # @return [String] Service name for trace attribution
-      attr_accessor :service_name
+    # @see ActiveAgents::Telemetry::Configuration
+    class Configuration < ActiveAgents::Telemetry::Configuration
+      # Fallback ingest path when the dashboard engine's mount point can't
+      # be resolved from the host's routes (e.g. engine not mounted).
+      LOCAL_ENDPOINT_PATH = "/activeagents/api/traces"
 
-      # @return [String] Environment name (development, staging, production)
-      attr_accessor :environment
-
-      # @return [Hash] Additional resource attributes to include in all traces
-      attr_accessor :resource_attributes
-
-      # @return [Logger] Logger for telemetry operations
-      attr_accessor :logger
-
-      # @return [Boolean] Whether to store traces locally in the app's database
-      attr_accessor :local_storage
-
-      # Default ActiveAgents.ai endpoint for hosted observability.
-      DEFAULT_ENDPOINT = "https://api.activeagents.ai/v1/traces"
-
-      # Local dashboard endpoint path (relative to app root)
-      LOCAL_ENDPOINT_PATH = "/active_agent/api/traces"
+      # @return [Boolean] Whether to store traces in the app's own database
+      attr_reader :local_storage
 
       def initialize
-        @enabled = false
-        @endpoint = DEFAULT_ENDPOINT
-        @api_key = nil
-        @sample_rate = 1.0
-        @batch_size = 100
-        @flush_interval = 5
-        @timeout = 10
-        @capture_bodies = false
-        @redact_attributes = %w[password secret token key credential api_key]
-        @service_name = nil
-        @environment = Rails.env if defined?(Rails)
-        @resource_attributes = {}
-        @logger = nil
+        super
+        # The framework predates the shared gem and has always been opt-in;
+        # adapters treat the presence of an api_key as the switch instead.
+        self.enabled = false
         @local_storage = false
       end
 
-      # Returns whether telemetry collection is enabled.
-      #
-      # @return [Boolean]
-      def enabled?
-        @enabled == true
+      def local_storage=(value)
+        @local_storage = value == true
       end
 
-      # Returns whether telemetry is properly configured.
-      #
-      # Checks that endpoint and api_key are present, or local_storage is enabled.
-      #
-      # @return [Boolean]
-      def configured?
-        local_storage? || (endpoint.present? && api_key.present?)
+      def local_storage?
+        @local_storage
       end
 
-      # Returns whether local storage mode is enabled.
-      #
-      # @return [Boolean]
-      def local_storage?
-        @local_storage == true
+      def local_store?
+        local_storage? || super
+      end
+
+      # When local storage is on, traces persist through the dashboard's
+      # trace model rather than leaving the process.
+      def local_store
+        super || (dashboard_store if local_storage?)
       end
 
       # Returns the resolved endpoint for trace reporting.
-      #
-      # Uses local endpoint when local_storage is enabled.
-      #
-      # @return [String]
       def resolved_endpoint
-        if local_storage?
-          LOCAL_ENDPOINT_PATH
-        else
-          endpoint
-        end
+        local_storage? ? local_endpoint_path : endpoint
       end
 
-      # Returns whether a trace should be sampled.
-      #
-      # Uses sample_rate to determine if trace should be collected.
-      #
-      # @return [Boolean]
-      def should_sample?
-        return true if sample_rate >= 1.0
-        return false if sample_rate <= 0.0
-
-        rand < sample_rate
+      # The dashboard engine's ingest path, derived from wherever the host
+      # app actually mounted it — "/activeagents", "/observability", or "/"
+      # on a dedicated subdomain all work. Falls back to
+      # LOCAL_ENDPOINT_PATH when the engine isn't mounted.
+      def local_endpoint_path
+        mount = dashboard_mount_path
+        mount ? "#{mount}/api/traces" : LOCAL_ENDPOINT_PATH
       end
 
-      # Resolves the service name for traces.
-      #
-      # Falls back to Rails application name or "activeagent".
-      #
-      # @return [String]
+      # The framework's historical fallback is "activeagent", not the shared
+      # core's generic "ruby".
       def resolved_service_name
-        @service_name || rails_app_name || "activeagent"
+        value = super
+        value == "ruby" ? "activeagent" : value
       end
 
-      # Returns the logger for telemetry operations.
-      #
-      # Falls back to Rails.logger or a null logger.
-      #
-      # @return [Logger]
-      def resolved_logger
-        @logger || (defined?(Rails) && Rails.logger) || Logger.new(File::NULL)
+      def to_h
+        super.merge(local_storage: local_storage)
       end
 
-      # Loads configuration from a hash (typically from YAML).
-      #
-      # @param hash [Hash] Configuration hash
-      # @return [self]
-      def load_from_hash(hash)
-        hash = hash.with_indifferent_access if hash.respond_to?(:with_indifferent_access)
-
-        @enabled = hash[:enabled] if hash.key?(:enabled)
-        @endpoint = hash[:endpoint] if hash.key?(:endpoint)
-        @api_key = hash[:api_key] if hash.key?(:api_key)
-        @sample_rate = hash[:sample_rate].to_f if hash.key?(:sample_rate)
-        @batch_size = hash[:batch_size].to_i if hash.key?(:batch_size)
-        @flush_interval = hash[:flush_interval].to_i if hash.key?(:flush_interval)
-        @timeout = hash[:timeout].to_i if hash.key?(:timeout)
-        @capture_bodies = hash[:capture_bodies] if hash.key?(:capture_bodies)
-        @redact_attributes = hash[:redact_attributes] if hash.key?(:redact_attributes)
-        @service_name = hash[:service_name] if hash.key?(:service_name)
-        @environment = hash[:environment] if hash.key?(:environment)
-        @resource_attributes = hash[:resource_attributes] if hash.key?(:resource_attributes)
-        @local_storage = hash[:local_storage] if hash.key?(:local_storage)
-
-        self
-      end
+      private
 
-      # Returns configuration as a hash for serialization.
-      #
-      # @return [Hash]
-      def to_h
-        {
-          enabled: enabled,
-          endpoint: endpoint,
-          api_key: api_key ? "[REDACTED]" : nil,
-          sample_rate: sample_rate,
-          batch_size: batch_size,
-          flush_interval: flush_interval,
-          timeout: timeout,
-          capture_bodies: capture_bodies,
-          service_name: resolved_service_name,
-          environment: environment,
-          local_storage: local_storage
-        }
+      # Persists a trace through the dashboard's trace model, honoring
+      # ActiveAgent::Dashboard.trace_model_class overrides. Idempotent on
+      # trace_id, as HTTP ingest is.
+      def dashboard_store
+        @dashboard_store ||= lambda do |trace, sdk|
+          model = local_trace_model
+          unless model
+            resolved_logger.error(
+              "[ActiveAgent::Telemetry] local_storage is enabled but no trace model is available — " \
+              "run `rails generate active_agent:dashboard:install` first"
+            )
+            next
+          end
+
+          next if model.exists?(trace_id: trace["trace_id"])
+
+          model.create_from_payload(trace, sdk)
+        end
       end
 
-      private
+      def local_trace_model
+        if defined?(ActiveAgent::Dashboard) && ActiveAgent::Dashboard.respond_to?(:trace_model)
+          ActiveAgent::Dashboard.trace_model
+        elsif defined?(ActiveAgent::TelemetryTrace)
+          ActiveAgent::TelemetryTrace
+        end
+      rescue NameError
+        nil
+      end
 
-      def rails_app_name
-        return nil unless defined?(Rails) && Rails.application
+      # The engine's mount point in the host app, found by locating the
+      # mounted engine in the host's route set. Works regardless of the
+      # helper name, so `mount ... => "/", as: :something_else` and
+      # constraint-wrapped mounts resolve correctly. Returns nil when the
+      # engine isn't mounted or no Rails app is booted; "" for a root mount.
+      def dashboard_mount_path
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
 
-        Rails.application.class.module_parent_name.underscore
+        mount_path_in(::Rails.application.routes)
       rescue StandardError
         nil
       end
+
+      # The engine's mount path within a given route set, or nil when it
+      # isn't mounted there. Separate from #dashboard_mount_path so it can be
+      # exercised against a route set directly.
+      public def mount_path_in(route_set)
+        return nil unless defined?(::ActiveAgent::Dashboard::Engine)
+
+        route = route_set.routes.find do |candidate|
+          mounted_engine(candidate.app) == ::ActiveAgent::Dashboard::Engine
+        end
+        return nil unless route
+
+        # "/activeagents(.:format)" -> "/activeagents"; a root mount -> "".
+        route.path.spec.to_s.sub(/\(\.:format\)\z/, "").chomp("/")
+      end
+
+      # Unwraps the constraint layers Rails wraps a mounted engine in,
+      # returning the engine class (or nil for ordinary routes). Stops at the
+      # engine class itself — engines also respond to #app (their route set),
+      # so unwrapping blindly walks straight past them.
+      def mounted_engine(app)
+        5.times do
+          return app if app.is_a?(Class) && app < ::Rails::Engine
+          break unless app.respond_to?(:app) && !app.app.equal?(app)
+
+          app = app.app
+        end
+        nil
+      end
     end
   end
 end