activeagent 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a1deba19c874b6abb36731bcee93bddf79bc193a3443a234cc811d9a4cc8383
-  data.tar.gz: 6f8847ab0d5eebf0ce26a8425f7630c884f0b9af71384c67325e3c06a8b0a8ae
+  metadata.gz: f352ce28ead5e975e8d64c76c4a263c1ac7cac3b202ea6fef1a137f899e3aea0
+  data.tar.gz: d163e4360d38fdf440465ec0caf76dc9c196cab342de0de4cf67de020b31d0e2
 SHA512:
-  metadata.gz: 767f039bd0af4f600a34becaac7bb2d04d2f8b768aef11242191f8a355b4a442c9c10690fe25a1a7f8e0da8b27e7216025c6f882c6d6002e5da9d0a9e876f1cb
-  data.tar.gz: 30725fb2369bd3b8dc23aa9d41e7d8a9843c3c8dd0aa629ace4bbd4cc217077339684ae0925cc6ea330c1e018b444a66057bcf5854b5bebf2bcb6a14bf57a322
+  metadata.gz: 8aed9bb0e1d7bec5b5e178940e4e43c8a117c82d36db703d34cbef485b0492d29d628350bb956cf709ee504a81327e152d5510d3c1b81cf43d5ecc70f33ffae8
+  data.tar.gz: 6d8b3c9b6d6f7286985206a42db8949067dbb46bc39db67e4eb507ccc1a9dd405ed46720c06878c4d5ea748f8da184072ce4e9bf9951361d4fe5172ae65770d8

data/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-12
+
+### Dashboard — self-hosted (enterprise) mount readiness
+
+The engine can now be mounted in any Rails app as the self-hosted
+observability surface (see `docs/framework/self-hosted-observability.md`):
+
+- **One install generator**: the duplicate `active_agent:dashboard:install`
+  variant that copied eight migrations (agents, sandboxes, recordings —
+  tables for models with no shipped controllers or routes) is removed.
+  The surviving generator installs the telemetry traces table only and
+  gains `--skip_migrations` / `--skip_routes`; its initializer template now
+  covers authentication, `ingest_api_key`, and multi-tenant options.
+- **Canonical mount path is `/activeagents`** (generator, dummy app and
+  docs updated). `Telemetry::Configuration#resolved_endpoint` now reports
+  the ingest path for wherever the engine is actually mounted — any mount
+  path, including `/` on a dedicated subdomain — instead of a hardcoded
+  constant, falling back to `LOCAL_ENDPOINT_PATH` when it isn't mounted.
+  Note this is informational: `local_storage` capture writes through the
+  trace model without HTTP, and remote apps set `endpoint:` explicitly.
+- **`TracesController` honors configuration**: index/metrics/time-series
+  queries now go through `ActiveAgent::Dashboard.trace_model` (previously
+  only `show` did) and are scoped with `for_account(current_owner)`, so a
+  `trace_model_class` override and multi-tenant scoping apply everywhere.
+- **Single-tenant ingest auth**: new `config.ingest_api_key` requires a
+  matching Bearer token on `POST <mount>/api/traces` when set. The
+  telemetry reporter and ruby_llm_telemetry already send their `api_key`
+  as a Bearer header, so remote apps need no changes.
+- **Metrics page no longer 500s with data**: the per-agent stats table
+  read a grouped SQL alias through a model method that expected per-trace
+  token columns.
+- **Mount detection is route-set based**: the ingest path is resolved by
+  locating the mounted engine in the host's routes rather than assuming
+  the default `active_agent_path` helper, so `mount ... => "/", as:
+  :something_else` and constraint-wrapped (subdomain) mounts resolve
+  correctly instead of silently falling back.
+- Deprecated the never-consumed `base_controller_class` config attribute:
+  it remains a no-op accessor with its historical default so existing
+  initializers keep booting, and will be removed in the next major.
+
+### Dashboard & Telemetry — dev console readiness
+
+The dashboard engine — Active Agent's local dev console — now works out of
+the box (production observability is the hosted platform product):
+
+- **Engine load paths fixed**: `Engine.find_root` now points at the
+  dashboard directory, so `ActiveAgent::TelemetryTrace`,
+  `ProcessTelemetryTracesJob`, the API controller, views and engine routes
+  are auto-discovered in host apps (previously they required manual
+  `require`s). The engine is also required eagerly with Rails, since
+  engines defined lazily miss initializer collection.
+- **Routes now match shipped controllers**: the engine exposes traces,
+  metrics and the ingest API (`<mount>/api/traces`); routes to
+  never-shipped controllers (agents, sandboxes, templates, recordings,
+  api/v1) were removed. Engine root renders the traces index.
+- **`local_storage` telemetry mode fixed**: tracer payloads are
+  symbol-keyed and were silently dropped by the string-keyed ingestion
+  normalizer; the reporter now stringifies and honors
+  `ActiveAgent::Dashboard.trace_model` overrides.
+- **Token totals no longer double-count**: instrumentation mirrors LLM
+  token usage onto the root span; `TelemetryTrace.create_from_payload`
+  now counts child spans as the source of truth.
+- **Span waterfall renders real offsets** (was pinned to 0ms), turbo-rails
+  is now optional (previously 500s without it), layout route helpers fixed,
+  `Agent.for_owner` scope added, synchronous ingest capped at 100
+  traces/request.
+- **New docs** (`docs/framework/dashboard.md`, README section) covering
+  install, authentication (none by default — see docs), remote ingestion
+  and multi-tenant mode; dashboard engine test suite added
+  (`test/dashboard/`).
+
 ## [1.0.0] - 2025-11-21
 
 Major refactor with breaking changes. Complete provider rewrite. New modular architecture.

data/README.md

@@ -127,6 +127,32 @@ development:
     service: "RubyLLM"
 ```
 
+## Dev Console & Observability
+
+Active Agent includes a local dev console — traces with span waterfalls,
+token usage, and per-agent metrics — as a mountable Rails engine, so you
+can watch your agents while you build:
+
+```bash
+rails generate active_agent:dashboard:install
+rails db:migrate
+```
+
+```yaml
+# config/active_agent.yml
+telemetry:
+  enabled: true
+  local_storage: true
+```
+
+Open `/activeagents` and every generation appears as a trace. See
+[docs/framework/dashboard.md](docs/framework/dashboard.md) for
+authentication, remote ingestion, and multi-tenant mode. For production
+monitoring — evaluations, cost estimates, retention, team workspaces —
+point telemetry at the hosted platform at
+[activeagents.ai](https://activeagents.ai); every workspace starts with a
+free low-volume trial.
+
 ## Features
 
 - **Agent-Oriented Programming**: Build AI applications using familiar Rails patterns

data/lib/active_agent/base.rb

@@ -304,6 +304,10 @@ module ActiveAgent
       # Render out proc/lamda attributes before rendering templates
       parameters.deep_transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
+      # Strip parameters the target model rejects (e.g. temperature/top_p
+      # on thinking-first models) before they reach the provider.
+      ModelCapabilities.sanitize!(parameters)
+
       # Apply Callbacks
       parameters.merge!(
         trace_id: prompt_options[:trace_id] || SecureRandom.uuid,

data/lib/active_agent/concerns/view.rb

@@ -142,7 +142,7 @@ module ActiveAgent
 
       return if !strict && !lookup_context.exists?(template_name, _prefixes, false, [], **options)
 
-      template = lookup_context.find_template(template_name, _prefixes, false, [], **options)
+      template = lookup_context.find(template_name, _prefixes, false, [], **options)
 
       render_to_string(template: template.virtual_path, locals:, layout: false).chomp.presence
     end

data/lib/active_agent/dashboard/app/controllers/active_agent/dashboard/api/traces_controller.rb

@@ -9,11 +9,14 @@ module ActiveAgent
       # for analysis and visualization in the dashboard.
       #
       # Supports two modes:
-      # - Local mode: No authentication, synchronous processing
-      # - Multi-tenant mode: Bearer token auth, async processing via job
+      # - Local mode: synchronous processing; unauthenticated unless
+      #   ActiveAgent::Dashboard.ingest_api_key is set (set it whenever the
+      #   mount is reachable beyond your own machine)
+      # - Multi-tenant mode: per-account Bearer token auth, async processing
+      #   via job
       #
       # @example Local mode request
-      #   POST /active_agent/api/traces
+      #   POST <mount>/api/traces  (e.g. /activeagents/api/traces)
       #   Content-Type: application/json
       #
       #   {
@@ -22,7 +25,7 @@ module ActiveAgent
       #   }
       #
       # @example Multi-tenant mode request
-      #   POST /active_agent/api/traces
+      #   POST <mount>/api/traces  (e.g. /activeagents/api/traces)
       #   Authorization: Bearer <api_key>
       #   Content-Type: application/json
       #
@@ -33,10 +36,15 @@ module ActiveAgent
       #
       class TracesController < ActionController::API
         before_action :authenticate_api_key!, if: -> { ActiveAgent::Dashboard.multi_tenant? }
+        before_action :authenticate_ingest_key!, unless: -> { ActiveAgent::Dashboard.multi_tenant? }
 
-        # POST /active_agent/api/traces
+        # Maximum traces accepted per request (mirrors
+        # ProcessTelemetryTracesJob::MAX_TRACES_PER_JOB).
+        MAX_TRACES_PER_REQUEST = 100
+
+        # POST <mount>/api/traces  (e.g. /activeagents/api/traces)
         def create
-          traces = params[:traces] || []
+          traces = Array(params[:traces]).take(MAX_TRACES_PER_REQUEST)
           sdk_info = params[:sdk] || {}
 
           return head :accepted if traces.empty?
@@ -86,6 +94,19 @@ module ActiveAgent
           @account.increment_telemetry_usage! if @account.respond_to?(:increment_telemetry_usage!)
         end
 
+        # Requires the configured single-tenant ingest key when one is set.
+        # The telemetry reporter and ruby_llm_telemetry both send their
+        # api_key as a Bearer header, so remote apps work unchanged.
+        def authenticate_ingest_key!
+          expected = ActiveAgent::Dashboard.ingest_api_key
+          return if expected.blank?
+
+          token = extract_bearer_token
+          return if token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
+
+          render json: { error: "Invalid API key" }, status: :unauthorized
+        end
+
         # Extracts Bearer token from Authorization header.
         def extract_bearer_token
           auth_header = request.headers["Authorization"]

data/lib/active_agent/dashboard/app/controllers/active_agent/dashboard/application_controller.rb

@@ -21,7 +21,17 @@ module ActiveAgent
       private
 
       def authenticate_dashboard!
-        return if ActiveAgent::Dashboard.authentication_method.nil?
+        if ActiveAgent::Dashboard.authentication_method.nil?
+          # Traces contain prompts, outputs, and error backtraces. Refuse to
+          # serve them unauthenticated in production rather than exposing
+          # them to the internet by default.
+          if Rails.env.production?
+            render plain: "ActiveAgent Dashboard: set ActiveAgent::Dashboard.authentication_method " \
+              "(see docs/framework/dashboard.md) to enable access in production.",
+              status: :forbidden
+          end
+          return
+        end
 
         result = ActiveAgent::Dashboard.authentication_method.call(self)
         head :unauthorized unless result

data/lib/active_agent/dashboard/app/controllers/active_agent/dashboard/dashboard_controller.rb

@@ -6,23 +6,26 @@ module ActiveAgent
     #
     class DashboardController < ApplicationController
       def index
+        unless ActiveAgent::Dashboard.use_inertia && defined?(InertiaRails)
+          # No ERB overview ships yet — the traces list is the dashboard.
+          # Loading agent/run data here would also require the full
+          # dashboard tables, which telemetry-only installs don't have.
+          return redirect_to(traces_path)
+        end
+
         @agents = fetch_agents.limit(10)
         @recent_runs = fetch_recent_runs.limit(10)
         @recent_traces = fetch_recent_traces.limit(10)
         @metrics = calculate_metrics
 
-        if ActiveAgent::Dashboard.use_inertia && defined?(InertiaRails)
-          render inertia: "Dashboard", props: {
-            agents: serialize_agents(@agents),
-            recentRuns: serialize_runs(@recent_runs),
-            recentTraces: serialize_traces(@recent_traces),
-            metrics: @metrics,
-            user: current_user_props,
-            account: current_account_props
-          }
-        else
-          render :index
-        end
+        render inertia: "Dashboard", props: {
+          agents: serialize_agents(@agents),
+          recentRuns: serialize_runs(@recent_runs),
+          recentTraces: serialize_traces(@recent_traces),
+          metrics: @metrics,
+          user: current_user_props,
+          account: current_account_props
+        }
       end
 
       private

data/lib/active_agent/dashboard/app/controllers/active_agent/dashboard/traces_controller.rb

@@ -16,12 +16,14 @@ module ActiveAgent
 
         respond_to do |format|
           format.html
-          format.turbo_stream
+          # turbo-rails is optional; responding to an unregistered MIME
+          # type raises in host apps without it.
+          format.turbo_stream if turbo_stream_available?
         end
       end
 
       def show
-        @trace = ActiveAgent::TelemetryTrace.find(params[:id])
+        @trace = scoped_traces.find(params[:id])
       end
 
       def metrics
@@ -31,14 +33,32 @@ module ActiveAgent
 
         respond_to do |format|
           format.html
-          format.turbo_stream
+          format.turbo_stream if turbo_stream_available?
         end
       end
 
       private
 
+      def turbo_stream_available?
+        Mime::Type.lookup_by_extension(:turbo_stream).present?
+      end
+
+      # All queries honor the configured trace model and, in multi-tenant
+      # mode, the current owner's account (for_account no-ops otherwise).
+      #
+      # In multi-tenant mode an unresolvable owner returns nothing rather
+      # than falling through: current_owner degrades to current_user when
+      # current_account_method is unset, which would scope by a user id
+      # against account_id — another tenant's traces.
+      def scoped_traces
+        model = ActiveAgent::Dashboard.trace_model
+        return model.none if ActiveAgent::Dashboard.multi_tenant? && current_owner.nil?
+
+        model.for_account(current_owner)
+      end
+
       def fetch_traces
-        traces = ActiveAgent::TelemetryTrace.recent
+        traces = scoped_traces.recent
 
         traces = traces.for_agent(params[:agent]) if params[:agent].present?
         traces = traces.with_errors if params[:status] == "error"
@@ -55,7 +75,7 @@ module ActiveAgent
       end
 
       def calculate_metrics
-        traces = ActiveAgent::TelemetryTrace.where(
+        traces = scoped_traces.where(
           "created_at > ?", 24.hours.ago
         )
 
@@ -77,7 +97,7 @@ module ActiveAgent
       end
 
       def agent_statistics
-        ActiveAgent::TelemetryTrace
+        scoped_traces
           .where("created_at > ?", 24.hours.ago)
           .group(:agent_class)
           .select(
@@ -90,7 +110,7 @@ module ActiveAgent
       end
 
       def time_series_data
-        ActiveAgent::TelemetryTrace
+        scoped_traces
           .where("created_at > ?", 1.hour.ago)
           .group_by_minute(:created_at)
           .count

data/lib/active_agent/dashboard/app/jobs/active_agent/process_telemetry_traces_job.rb

@@ -39,7 +39,16 @@ module ActiveAgent
         return
       end
 
+      # Process in bounded slices; anything beyond the cap is re-enqueued
+      # rather than silently dropped (the client already received 202).
+      remainder = traces.drop(MAX_TRACES_PER_JOB)
       traces = traces.take(MAX_TRACES_PER_JOB)
+      if remainder.any?
+        self.class.perform_later(
+          account_id: account_id, traces: remainder,
+          sdk_info: sdk_info, received_at: received_at
+        )
+      end
 
       traces.each do |trace|
         process_trace(trace, sdk_info, account)

data/lib/active_agent/dashboard/app/models/active_agent/dashboard/agent.rb

@@ -71,7 +71,7 @@ module ActiveAgent
       ].freeze
 
       # Available providers
-      PROVIDERS = %w[openai anthropic ollama openrouter].freeze
+      PROVIDERS = %w[openai anthropic ollama openrouter requesty].freeze
 
       # Returns the configuration as a hash for versioning
       def configuration_snapshot

data/lib/active_agent/dashboard/app/models/active_agent/telemetry_trace.rb

@@ -54,13 +54,20 @@ module ActiveAgent
       spans = trace["spans"] || []
       root_span = spans.find { |s| s["parent_span_id"].nil? } || spans.first || {}
 
-      # Calculate totals from all spans
       total_duration = root_span["duration_ms"]
+
+      # Instrumentation mirrors LLM token usage onto the root span for
+      # display, so summing every span double-counts. When child spans
+      # carry token data, they are the source of truth; the root span only
+      # counts for single-span traces.
+      counted_spans = spans.reject { |s| s["parent_span_id"].nil? }
+      counted_spans = spans if counted_spans.none? { |s| span_token_sum(s).positive? }
+
       total_input = 0
       total_output = 0
       total_thinking = 0
 
-      spans.each do |span|
+      counted_spans.each do |span|
         tokens = span["tokens"] || {}
         total_input += (tokens["input"] || 0)
         total_output += (tokens["output"] || 0)
@@ -100,6 +107,15 @@ module ActiveAgent
       create!(attrs)
     end
 
+    # Sums a span's token counts (used to decide which spans carry the
+    # authoritative token data during ingestion).
+    #
+    # @api private
+    def self.span_token_sum(span)
+      tokens = span["tokens"] || {}
+      tokens.fetch("input", 0).to_i + tokens.fetch("output", 0).to_i + tokens.fetch("thinking", 0).to_i
+    end
+
     # Returns the root span of this trace.
     #
     # @return [Hash, nil] The root span or nil

data/lib/active_agent/dashboard/app/views/active_agent/dashboard/traces/_trace_detail.html.erb

@@ -59,11 +59,23 @@
     <div class="mt-4">
       <h4 class="text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Span Timeline</h4>
       <div class="relative bg-gray-100 dark:bg-gray-800 rounded-lg p-4">
-        <% total_duration = trace.total_duration_ms || 1 %>
+        <% total_duration = (trace.total_duration_ms || 1).to_f %>
+        <% total_duration = 1.0 if total_duration.zero? %>
+        <%
+          # Offsets relative to the root span's start. Span payloads carry
+          # absolute ISO8601 start_time values, not relative offsets.
+          root = trace.root_span || trace.spans.first || {}
+          root_start = Time.parse(root["start_time"]) rescue nil
+        %>
         <% trace.spans.each_with_index do |span, index| %>
           <%
-            start_pct = ((span["start_time_relative_ms"] || 0) / total_duration * 100).clamp(0, 100)
-            width_pct = ((span["duration_ms"] || 0) / total_duration * 100).clamp(0.5, 100 - start_pct)
+            relative_ms = span["start_time_relative_ms"]
+            if relative_ms.nil? && root_start && span["start_time"].present?
+              span_start = Time.parse(span["start_time"]) rescue nil
+              relative_ms = ((span_start - root_start) * 1000).round(2) if span_start
+            end
+            start_pct = ((relative_ms || 0).to_f / total_duration * 100).clamp(0, 100)
+            width_pct = ((span["duration_ms"] || 0).to_f / total_duration * 100).clamp(0.5, [ 100 - start_pct, 0.5 ].max)
             span_type = span["type"] || "unknown"
             colors = {
               "root" => "bg-gray-400",

data/lib/active_agent/dashboard/app/views/active_agent/dashboard/traces/metrics.html.erb

@@ -114,7 +114,9 @@
                 <%= number_with_delimiter(stat.trace_count) %>
               </td>
               <td class="px-4 py-3 text-sm text-gray-900 dark:text-white">
-                <%= number_to_human(stat.total_tokens || 0, precision: 1) %>
+                <%# stat is a grouped row: read the SQL alias, not the model
+                    method (which sums per-trace token columns absent here) %>
+                <%= number_to_human(stat[:total_tokens] || 0, precision: 1) %>
               </td>
               <td class="px-4 py-3 text-sm text-gray-900 dark:text-white">
                 <% avg = stat.avg_duration.to_f %>

data/lib/active_agent/dashboard/app/views/layouts/active_agent/dashboard/application.html.erb

@@ -69,11 +69,11 @@
             </div>
             <div class="ml-10 flex items-baseline space-x-4">
               <%= link_to "Traces",
-                  active_agent_dashboard.traces_path,
-                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path == active_agent_dashboard.traces_path ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-900 dark:text-indigo-200' : 'text-gray-600 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700'}" %>
+                  traces_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path == traces_path ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-900 dark:text-indigo-200' : 'text-gray-600 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700'}" %>
               <%= link_to "Metrics",
-                  active_agent_dashboard.metrics_traces_path,
-                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path == active_agent_dashboard.metrics_traces_path ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-900 dark:text-indigo-200' : 'text-gray-600 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700'}" %>
+                  metrics_traces_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path == metrics_traces_path ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-900 dark:text-indigo-200' : 'text-gray-600 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700'}" %>
             </div>
           </div>
           <div class="text-sm text-gray-500 dark:text-gray-400">

data/lib/active_agent/dashboard/config/routes.rb

@@ -1,78 +1,19 @@
 # frozen_string_literal: true
 
 ActiveAgent::Dashboard::Engine.routes.draw do
-  # Dashboard root
-  root to: "dashboard#index"
-
-  # Dashboard
+  # The functional dashboard surface: traces + metrics.
+  root to: "traces#index"
   get "dashboard", to: "dashboard#index"
 
-  # Traces
   resources :traces, only: [ :index, :show ] do
     collection do
       get :metrics
     end
   end
 
-  # Agents
-  resources :agents do
-    member do
-      post :execute
-      post :test
-      get :versions
-      post :restore_version
-    end
-    resources :runs, controller: "agent_runs", only: [ :index, :show ] do
-      member do
-        post :cancel
-      end
-    end
-  end
-
-  # Agent Templates
-  resources :templates, only: [ :index, :show ] do
-    member do
-      post :create_agent
-    end
-  end
-
-  # Sandbox Sessions
-  resources :sandboxes, controller: "sandbox_sessions" do
-    member do
-      post :provision
-      post :execute
-      post :expire
-    end
-    resources :runs, controller: "sandbox_runs", only: [ :index, :show ]
-  end
-
-  # Session Recordings
-  resources :recordings, controller: "session_recordings", only: [ :index, :show ] do
-    member do
-      get :timeline
-      get :playback
-    end
-  end
-
-  # API namespace
+  # Telemetry ingestion, relative to wherever the engine is mounted:
+  # <mount>/api/traces (e.g. /activeagents/api/traces at the default mount).
   namespace :api do
-    namespace :v1 do
-      # Telemetry ingestion
-      resources :traces, only: [ :create ]
-
-      # Agent execution API
-      resources :agents, only: [ :index, :show ] do
-        member do
-          post :execute
-        end
-      end
-
-      # Sandbox API
-      resources :sandboxes, only: [ :create, :show ] do
-        member do
-          post :execute
-        end
-      end
-    end
+    resources :traces, only: [ :create ]
   end
 end

data/lib/active_agent/dashboard/engine.rb

@@ -4,36 +4,40 @@ module ActiveAgent
   module Dashboard
     # Rails Engine for the ActiveAgent Dashboard.
     #
-    # Provides a full-featured dashboard for managing agents, viewing telemetry,
-    # running sandboxes, and recording sessions.
+    # Provides the free self-hosted dashboard: telemetry traces, metrics,
+    # and the local trace ingestion API.
     #
     # Mount in your routes:
-    #   mount ActiveAgent::Dashboard::Engine => "/active_agent"
+    #   mount ActiveAgent::Dashboard::Engine => "/activeagents"
     #
     class Engine < ::Rails::Engine
-      isolate_namespace ActiveAgent::Dashboard
-
-      # Use a unique engine name to avoid conflicts
-      engine_name "active_agent"
+      # The engine lives at lib/active_agent/dashboard rather than the gem
+      # root. Rails derives an engine's load paths (app/models,
+      # app/controllers, app/jobs, app/views, config/routes.rb) from
+      # find_root when +config+ is first materialized — which
+      # isolate_namespace below triggers via +routes+ — so this override
+      # must be defined before anything touches config. Overriding only
+      # +root+ leaves the engine's classes off host applications' autoload
+      # paths entirely.
+      def self.find_root(_from)
+        root
+      end
 
-      # Override engine root to point to the dashboard directory
-      # This must be set before paths are computed
       def self.root
         @root ||= Pathname.new(File.expand_path("..", __FILE__))
       end
 
+      isolate_namespace ActiveAgent::Dashboard
+
+      # Use a unique engine name to avoid conflicts
+      engine_name "active_agent"
+
       # Alias for consistency with existing code
       def self.dashboard_root
         root
       end
 
       config.active_agent_dashboard = ActiveSupport::OrderedOptions.new
-
-      initializer "active_agent.dashboard.append_view_paths" do
-        ActiveSupport.on_load(:action_controller) do
-          prepend_view_path ActiveAgent::Dashboard::Engine.root.join("app", "views").to_s
-        end
-      end
     end
   end
 end

data/lib/active_agent/dashboard.rb

@@ -8,7 +8,7 @@ module ActiveAgent
   # Mount the engine in your routes to access the full dashboard:
   #
   #   # config/routes.rb
-  #   mount ActiveAgent::Dashboard::Engine => "/active_agent"
+  #   mount ActiveAgent::Dashboard::Engine => "/activeagents"
   #
   # The dashboard provides:
   # - Agent management: Create, edit, version, and execute agents
@@ -91,7 +91,16 @@ module ActiveAgent
       # @return [Object, nil] Object responding to #signed_url_for and #fetch_snapshot
       attr_accessor :storage_service
 
-      # Base controller class for dashboard controllers
+      # Bearer token required by the ingest API in single-tenant mode. When
+      # unset the local ingest endpoint accepts unauthenticated posts, so set
+      # it whenever the mount is reachable beyond your own machine.
+      # (Multi-tenant mode authenticates per-account keys instead.)
+      # @return [String, nil]
+      attr_accessor :ingest_api_key
+
+      # @deprecated Never consumed — dashboard controllers inherit
+      #   ActionController::Base. Retained as a no-op so existing
+      #   initializers that set it keep booting; remove in the next major.
       # @return [String]
       attr_accessor :base_controller_class
 
@@ -141,7 +150,8 @@ module ActiveAgent
         @sandbox_service = :local
         @sandbox_limits = nil
         @storage_service = nil
-        @base_controller_class = "ActionController::Base"
+        @ingest_api_key = nil
+        @base_controller_class = "ActionController::Base" # deprecated no-op
       end
     end