activeagent 1.0.1 → 1.0.2

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

@@ -0,0 +1,135 @@
+<div data-controller="refresh" data-refresh-interval-value="30000">
+  <!-- Metrics Summary -->
+  <div class="grid grid-cols-1 md:grid-cols-5 gap-4 mb-6">
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4">
+      <div class="text-sm font-medium text-gray-500 dark:text-gray-400">Total Traces</div>
+      <div class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white">
+        <%= number_with_delimiter(@metrics[:total_traces]) %>
+      </div>
+      <div class="text-xs text-gray-400">Last 24h</div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4">
+      <div class="text-sm font-medium text-gray-500 dark:text-gray-400">Total Tokens</div>
+      <div class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white">
+        <%= number_to_human(@metrics[:total_tokens], precision: 2) %>
+      </div>
+      <div class="text-xs text-gray-400">Last 24h</div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4">
+      <div class="text-sm font-medium text-gray-500 dark:text-gray-400">Avg Duration</div>
+      <div class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white">
+        <%= @metrics[:avg_duration_ms] >= 1000 ? "#{(@metrics[:avg_duration_ms] / 1000.0).round(2)}s" : "#{@metrics[:avg_duration_ms].round(0)}ms" %>
+      </div>
+      <div class="text-xs text-gray-400">Last 24h</div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4">
+      <div class="text-sm font-medium text-gray-500 dark:text-gray-400">Error Rate</div>
+      <div class="mt-1 text-2xl font-semibold <%= @metrics[:error_rate] > 5 ? 'text-red-600' : 'text-gray-900 dark:text-white' %>">
+        <%= @metrics[:error_rate] %>%
+      </div>
+      <div class="text-xs text-gray-400">Last 24h</div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4">
+      <div class="text-sm font-medium text-gray-500 dark:text-gray-400">Active Agents</div>
+      <div class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white">
+        <%= @metrics[:unique_agents] %>
+      </div>
+      <div class="text-xs text-gray-400">Last 24h</div>
+    </div>
+  </div>
+
+  <!-- Traces Table -->
+  <div class="bg-white dark:bg-gray-800 shadow rounded-lg overflow-hidden" data-controller="traces">
+    <div class="px-4 py-3 border-b border-gray-200 dark:border-gray-700 flex justify-between items-center">
+      <h2 class="text-lg font-medium text-gray-900 dark:text-white">Recent Traces</h2>
+      <div class="flex gap-2">
+        <%= link_to "All", traces_path, class: "px-3 py-1 text-sm rounded #{params[:status].blank? ? 'bg-indigo-100 text-indigo-700' : 'text-gray-600 hover:bg-gray-100'}" %>
+        <%= link_to "Errors", traces_path(status: "error"), class: "px-3 py-1 text-sm rounded #{params[:status] == 'error' ? 'bg-red-100 text-red-700' : 'text-gray-600 hover:bg-gray-100'}" %>
+      </div>
+    </div>
+
+    <% if @traces.any? %>
+      <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+        <thead class="bg-gray-50 dark:bg-gray-900">
+          <tr>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Agent</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Status</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Duration</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Tokens</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Time</th>
+          </tr>
+        </thead>
+        <tbody class="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
+          <% @traces.each do |trace| %>
+            <!-- Main Row -->
+            <tr class="hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer"
+                data-trace-id="<%= trace.id %>"
+                data-action="click->traces#toggle">
+              <td class="px-4 py-3">
+                <div class="flex items-center">
+                  <span class="text-sm font-medium text-gray-900 dark:text-white">
+                    <%= trace.agent_class || "Unknown" %>
+                  </span>
+                  <% if trace.agent_action %>
+                    <span class="ml-2 text-sm text-gray-500 dark:text-gray-400">
+                      .<%= trace.agent_action %>
+                    </span>
+                  <% end %>
+                </div>
+                <div class="text-xs text-gray-400 font-mono"><%= trace.trace_id&.first(8) %></div>
+              </td>
+              <td class="px-4 py-3">
+                <% if trace.error? %>
+                  <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200">
+                    Error
+                  </span>
+                <% else %>
+                  <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200">
+                    OK
+                  </span>
+                <% end %>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+                <%= trace.formatted_duration %>
+              </td>
+              <td class="px-4 py-3">
+                <div class="flex items-center gap-2 text-sm">
+                  <span class="text-gray-900 dark:text-white"><%= trace.formatted_tokens %></span>
+                  <% if trace.total_thinking_tokens.to_i > 0 %>
+                    <span class="text-xs text-purple-600 dark:text-purple-400" title="Thinking tokens">
+                      +<%= number_to_human(trace.total_thinking_tokens, precision: 1) %> thinking
+                    </span>
+                  <% end %>
+                </div>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-500 dark:text-gray-400">
+                <%= time_ago_in_words(trace.timestamp || trace.created_at) %> ago
+              </td>
+            </tr>
+
+            <!-- Expanded Detail Row -->
+            <tr id="detail-<%= trace.id %>" class="hidden bg-gray-50 dark:bg-gray-900">
+              <td colspan="5" class="px-4 py-4">
+                <%= render partial: "trace_detail", locals: { trace: trace } %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    <% else %>
+      <div class="px-4 py-12 text-center">
+        <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 17v-2m3 2v-4m3 4v-6m2 10H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+        </svg>
+        <h3 class="mt-2 text-sm font-medium text-gray-900 dark:text-white">No traces yet</h3>
+        <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+          Traces will appear here when your agents generate responses.
+        </p>
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,143 @@
+<div data-controller="refresh" data-refresh-interval-value="60000">
+  <h1 class="text-2xl font-bold text-gray-900 dark:text-white mb-6">Metrics Overview</h1>
+
+  <!-- Summary Cards -->
+  <div class="grid grid-cols-1 md:grid-cols-5 gap-4 mb-8">
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+      <div class="flex items-center">
+        <div class="p-3 rounded-full bg-indigo-100 dark:bg-indigo-900">
+          <svg class="h-6 w-6 text-indigo-600 dark:text-indigo-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+          </svg>
+        </div>
+        <div class="ml-4">
+          <p class="text-sm font-medium text-gray-500 dark:text-gray-400">Total Traces</p>
+          <p class="text-2xl font-semibold text-gray-900 dark:text-white">
+            <%= number_with_delimiter(@metrics[:total_traces]) %>
+          </p>
+        </div>
+      </div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+      <div class="flex items-center">
+        <div class="p-3 rounded-full bg-blue-100 dark:bg-blue-900">
+          <svg class="h-6 w-6 text-blue-600 dark:text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
+          </svg>
+        </div>
+        <div class="ml-4">
+          <p class="text-sm font-medium text-gray-500 dark:text-gray-400">Total Tokens</p>
+          <p class="text-2xl font-semibold text-gray-900 dark:text-white">
+            <%= number_to_human(@metrics[:total_tokens], precision: 2) %>
+          </p>
+        </div>
+      </div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+      <div class="flex items-center">
+        <div class="p-3 rounded-full bg-green-100 dark:bg-green-900">
+          <svg class="h-6 w-6 text-green-600 dark:text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+        </div>
+        <div class="ml-4">
+          <p class="text-sm font-medium text-gray-500 dark:text-gray-400">Avg Duration</p>
+          <p class="text-2xl font-semibold text-gray-900 dark:text-white">
+            <%= @metrics[:avg_duration_ms] >= 1000 ? "#{(@metrics[:avg_duration_ms] / 1000.0).round(2)}s" : "#{@metrics[:avg_duration_ms].round(0)}ms" %>
+          </p>
+        </div>
+      </div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+      <div class="flex items-center">
+        <div class="p-3 rounded-full <%= @metrics[:error_rate] > 5 ? 'bg-red-100 dark:bg-red-900' : 'bg-gray-100 dark:bg-gray-700' %>">
+          <svg class="h-6 w-6 <%= @metrics[:error_rate] > 5 ? 'text-red-600 dark:text-red-400' : 'text-gray-600 dark:text-gray-400' %>" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+          </svg>
+        </div>
+        <div class="ml-4">
+          <p class="text-sm font-medium text-gray-500 dark:text-gray-400">Error Rate</p>
+          <p class="text-2xl font-semibold <%= @metrics[:error_rate] > 5 ? 'text-red-600' : 'text-gray-900 dark:text-white' %>">
+            <%= @metrics[:error_rate] %>%
+          </p>
+        </div>
+      </div>
+    </div>
+
+    <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+      <div class="flex items-center">
+        <div class="p-3 rounded-full bg-purple-100 dark:bg-purple-900">
+          <svg class="h-6 w-6 text-purple-600 dark:text-purple-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0zm6 3a2 2 0 11-4 0 2 2 0 014 0zM7 10a2 2 0 11-4 0 2 2 0 014 0z" />
+          </svg>
+        </div>
+        <div class="ml-4">
+          <p class="text-sm font-medium text-gray-500 dark:text-gray-400">Active Agents</p>
+          <p class="text-2xl font-semibold text-gray-900 dark:text-white">
+            <%= @metrics[:unique_agents] %>
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Agent Statistics -->
+  <div class="bg-white dark:bg-gray-800 shadow rounded-lg overflow-hidden mb-8">
+    <div class="px-4 py-4 border-b border-gray-200 dark:border-gray-700">
+      <h2 class="text-lg font-medium text-gray-900 dark:text-white">Agent Statistics</h2>
+      <p class="text-sm text-gray-500 dark:text-gray-400">Performance breakdown by agent class (last 24h)</p>
+    </div>
+
+    <% if @agent_stats.any? %>
+      <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+        <thead class="bg-gray-50 dark:bg-gray-900">
+          <tr>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Agent</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Traces</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Tokens</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Avg Duration</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Errors</th>
+          </tr>
+        </thead>
+        <tbody class="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
+          <% @agent_stats.each do |stat| %>
+            <tr class="hover:bg-gray-50 dark:hover:bg-gray-700">
+              <td class="px-4 py-3">
+                <span class="text-sm font-medium text-gray-900 dark:text-white">
+                  <%= stat.agent_class || "Unknown" %>
+                </span>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+                <%= 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) %>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+                <% avg = stat.avg_duration.to_f %>
+                <%= avg >= 1000 ? "#{(avg / 1000.0).round(2)}s" : "#{avg.round(0)}ms" %>
+              </td>
+              <td class="px-4 py-3">
+                <% error_count = stat.error_count.to_i %>
+                <% if error_count > 0 %>
+                  <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200">
+                    <%= error_count %>
+                  </span>
+                <% else %>
+                  <span class="text-sm text-gray-400">0</span>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    <% else %>
+      <div class="px-4 py-8 text-center text-gray-500 dark:text-gray-400">
+        No agent data available yet.
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,36 @@
+<div class="mb-4">
+  <%= link_to "← Back to traces", traces_path, class: "text-indigo-600 hover:text-indigo-800 text-sm" %>
+</div>
+
+<div class="bg-white dark:bg-gray-800 shadow rounded-lg overflow-hidden">
+  <div class="px-4 py-4 border-b border-gray-200 dark:border-gray-700">
+    <div class="flex items-center justify-between">
+      <div>
+        <h1 class="text-xl font-semibold text-gray-900 dark:text-white">
+          <%= @trace.display_name %>
+        </h1>
+        <p class="text-sm text-gray-500 dark:text-gray-400 font-mono">
+          <%= @trace.trace_id %>
+        </p>
+      </div>
+      <div class="flex items-center gap-4">
+        <% if @trace.error? %>
+          <span class="inline-flex items-center px-3 py-1 rounded-full text-sm font-medium bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200">
+            Error
+          </span>
+        <% else %>
+          <span class="inline-flex items-center px-3 py-1 rounded-full text-sm font-medium bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200">
+            Success
+          </span>
+        <% end %>
+        <span class="text-sm text-gray-500">
+          <%= @trace.timestamp&.strftime("%Y-%m-%d %H:%M:%S") %>
+        </span>
+      </div>
+    </div>
+  </div>
+
+  <div class="p-4">
+    <%= render partial: "trace_detail", locals: { trace: @trace } %>
+  </div>
+</div>

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

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html lang="en" class="h-full">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ActiveAgent Dashboard</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://unpkg.com/@hotwired/turbo@7.3.0/dist/turbo.es2017-esm.js" type="module"></script>
+  <script src="https://unpkg.com/@hotwired/stimulus@3.2.2/dist/stimulus.umd.js"></script>
+  <style>
+    [data-turbo-preview] { opacity: 0.5; }
+    .span-bar { transition: all 0.2s ease; }
+    .span-bar:hover { transform: scaleY(1.1); }
+  </style>
+  <script>
+    // Initialize Stimulus
+    const application = Stimulus.Application.start();
+
+    // Traces controller for expandable rows
+    application.register("traces", class extends Stimulus.Controller {
+      static targets = ["row", "detail"]
+
+      toggle(event) {
+        const traceId = event.currentTarget.dataset.traceId;
+        const detail = document.getElementById(`detail-${traceId}`);
+        if (detail) {
+          detail.classList.toggle("hidden");
+        }
+      }
+    });
+
+    // Auto-refresh controller
+    application.register("refresh", class extends Stimulus.Controller {
+      static values = { interval: Number }
+
+      connect() {
+        if (this.intervalValue > 0) {
+          this.startRefresh();
+        }
+      }
+
+      disconnect() {
+        this.stopRefresh();
+      }
+
+      startRefresh() {
+        this.timer = setInterval(() => {
+          Turbo.visit(window.location.href, { action: "replace" });
+        }, this.intervalValue);
+      }
+
+      stopRefresh() {
+        if (this.timer) clearInterval(this.timer);
+      }
+    });
+  </script>
+</head>
+<body class="h-full bg-gray-50 dark:bg-gray-900">
+  <div class="min-h-full">
+    <!-- Header -->
+    <nav class="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
+      <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <div class="flex h-16 items-center justify-between">
+          <div class="flex items-center">
+            <div class="flex-shrink-0">
+              <span class="text-xl font-bold text-indigo-600 dark:text-indigo-400">
+                ActiveAgent
+              </span>
+            </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'}" %>
+              <%= 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'}" %>
+            </div>
+          </div>
+          <div class="text-sm text-gray-500 dark:text-gray-400">
+            Local Telemetry
+          </div>
+        </div>
+      </div>
+    </nav>
+
+    <!-- Main content -->
+    <main>
+      <div class="mx-auto max-w-7xl py-6 px-4 sm:px-6 lg:px-8">
+        <%= yield %>
+      </div>
+    </main>
+  </div>
+</body>
+</html>

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+ActiveAgent::Dashboard::Engine.routes.draw do
+  # Dashboard root
+  root to: "dashboard#index"
+
+  # Dashboard
+  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
+  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
+  end
+end

data/lib/active_agent/dashboard/engine.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Mount in your routes:
+    #   mount ActiveAgent::Dashboard::Engine => "/active_agent"
+    #
+    class Engine < ::Rails::Engine
+      isolate_namespace ActiveAgent::Dashboard
+
+      # Use a unique engine name to avoid conflicts
+      engine_name "active_agent"
+
+      # 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
+
+      # 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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "active_agent/dashboard/engine"
+
+module ActiveAgent
+  # Dashboard engine for visualizing telemetry data and managing agents.
+  #
+  # Mount the engine in your routes to access the full dashboard:
+  #
+  #   # config/routes.rb
+  #   mount ActiveAgent::Dashboard::Engine => "/active_agent"
+  #
+  # The dashboard provides:
+  # - Agent management: Create, edit, version, and execute agents
+  # - Traces view: See all agent invocations with spans, timing, and token usage
+  # - Metrics view: Aggregate statistics and charts
+  # - Sandbox execution: Run agents in isolated environments
+  # - Session recordings: Capture and replay browser sessions
+  #
+  # = Configuration Modes
+  #
+  # == Local Mode (default)
+  # For self-hosted, single-tenant deployments:
+  #
+  #   ActiveAgent::Dashboard.configure do |config|
+  #     config.authentication_method = ->(controller) { controller.authenticate_admin! }
+  #     config.sandbox_service = :local  # Docker/Incus
+  #   end
+  #
+  # == Multi-tenant Mode
+  # For SaaS platforms with multiple accounts:
+  #
+  #   ActiveAgent::Dashboard.configure do |config|
+  #     config.multi_tenant = true
+  #     config.account_class = "Account"
+  #     config.user_class = "User"
+  #     config.current_account_method = :current_account
+  #     config.current_user_method = :current_user
+  #     config.authentication_method = ->(controller) { controller.authenticate_user! }
+  #     config.sandbox_service = :cloud_run  # Managed
+  #     config.use_inertia = true
+  #   end
+  #
+  module Dashboard
+    class << self
+      # Authentication method to call on controllers
+      # @return [Proc, nil] A proc that receives the controller instance
+      attr_accessor :authentication_method
+
+      # Enable multi-tenant mode (requires account association)
+      # @return [Boolean]
+      attr_accessor :multi_tenant
+
+      # Class name for the Account model (multi-tenant mode)
+      # @return [String, nil]
+      attr_accessor :account_class
+
+      # Class name for the User model
+      # @return [String, nil]
+      attr_accessor :user_class
+
+      # Method to call on controller to get current account (multi-tenant mode)
+      # @return [Symbol, nil]
+      attr_accessor :current_account_method
+
+      # Method to call on controller to get current user
+      # @return [Symbol, nil]
+      attr_accessor :current_user_method
+
+      # Custom trace model class (for host app overrides)
+      # @return [String, nil]
+      attr_accessor :trace_model_class
+
+      # Enable React/Inertia frontend instead of ERB
+      # @return [Boolean]
+      attr_accessor :use_inertia
+
+      # Custom layout for the dashboard
+      # @return [String, nil]
+      attr_accessor :layout
+
+      # Sandbox service type (:local, :cloud_run, :kubernetes)
+      # @return [Symbol]
+      attr_accessor :sandbox_service
+
+      # Custom sandbox limits (overrides defaults)
+      # @return [Hash, nil]
+      attr_accessor :sandbox_limits
+
+      # Storage service for screenshots/snapshots
+      # @return [Object, nil] Object responding to #signed_url_for and #fetch_snapshot
+      attr_accessor :storage_service
+
+      # Base controller class for dashboard controllers
+      # @return [String]
+      attr_accessor :base_controller_class
+
+      # Returns whether multi-tenant mode is enabled.
+      #
+      # @return [Boolean]
+      def multi_tenant?
+        @multi_tenant == true
+      end
+
+      # Returns the trace model class to use.
+      #
+      # @return [Class] The trace model class
+      def trace_model
+        if trace_model_class
+          trace_model_class.constantize
+        else
+          ActiveAgent::TelemetryTrace
+        end
+      end
+
+      # Returns the agent model class to use.
+      #
+      # @return [Class] The agent model class
+      def agent_model
+        ActiveAgent::Dashboard::Agent
+      end
+
+      # Configures the dashboard.
+      #
+      # @yield [config] Configuration block
+      def configure
+        yield self
+      end
+
+      # Reset configuration to defaults
+      def reset!
+        @authentication_method = nil
+        @multi_tenant = false
+        @account_class = nil
+        @user_class = nil
+        @current_account_method = nil
+        @current_user_method = nil
+        @trace_model_class = nil
+        @use_inertia = false
+        @layout = nil
+        @sandbox_service = :local
+        @sandbox_limits = nil
+        @storage_service = nil
+        @base_controller_class = "ActionController::Base"
+      end
+    end
+
+    # Set defaults
+    reset!
+  end
+end