Make the dashboard engine (local dev console) work out of the box

[TonsOfFun]

Positioning update (latest commit): the core framework stays free, but production observability/monitoring is the hosted platform's paid product — free workspaces get a low-volume trial. The engine is now documented as a local dev console: README, CHANGELOG, and docs/framework/dashboard.md reframed accordingly (the parity table states intended use: console = development, platform = production). All engine fixes below are unchanged and still needed — they make the dev/trial experience work.

Why

The dashboard engine that shipped in 1.0.3 is the local dev console counterpart to the activeagents.ai cloud platform, but it was undocumented and not actually usable in a host app: its classes never landed on autoload paths, local_storage telemetry silently persisted nothing, most engine routes pointed at controllers that don't exist, token totals were exactly doubled, and every dashboard page 500'd in apps without turbo-rails. The activeagents.ai platform (which runs this engine multi-tenant — see activeagents/activeagents#90) needed manual require workarounds and app-side patches for all of this.

This PR makes the engine work out of the box for v2 and the cloud launch. All fixes were verified two ways: a new engine test suite against the gem's dummy app, and the full activeagents.ai platform test suite (166 runs) run against this branch with every workaround removed.

What

Engine boot (the big one)

• Engine.find_root now returns the dashboard directory, and is defined before isolate_namespace (which materializes config via routes, freezing the root). Previously only Engine.root was overridden, which Rails never consults for load paths — so ActiveAgent::TelemetryTrace, ProcessTelemetryTracesJob, the ingest controller, views, and the engine's routes file were all invisible to host apps.
• The engine is required eagerly when Rails is present (lib/active_agent.rb). It was previously behind autoload :Dashboard, and an engine defined after the host app collects railtie initializers never registers its paths.

Routes / controllers

• Engine routes trimmed to what actually ships: traces, metrics, and the ingest API. The removed routes (agents CRUD, runs, templates, sandboxes, recordings, api/v1/*) pointed at controllers that don't exist in the gem and produced 500s; the models remain for host apps that use them. A route↔controller consistency test now guards this.
• Ingest is POST /api/traces, matching Telemetry::Configuration::LOCAL_ENDPOINT_PATH (the routes previously declared api/v1 while the controller lives at Api::TracesController and the config pointed at api/traces — three different answers).
• Engine root renders the traces index; dashboard#index redirects in ERB mode instead of rendering a view that doesn't exist (and no longer queries Agent/AgentRun tables that telemetry-only installs don't have). Added the Agent.for_owner scope DashboardController referenced but nothing defined.

Telemetry correctness

• local_storage mode: Tracer#build_trace_payload emits symbol keys, create_from_payload reads string keys — every locally stored trace failed trace_id presence validation inside a rescued block, i.e. the flagship local mode persisted nothing. The reporter now deep-stringifies and honors ActiveAgent::Dashboard.trace_model overrides instead of hardcoding the class.
• Token totals: instrumentation mirrors LLM usage onto both the llm span and root span; create_from_payload summed all spans, so every trace reported exactly 2× tokens. Child spans are now the source of truth when they carry token data (root-only traces still count the root).
• Synchronous ingest capped at 100 traces/request, mirroring ProcessTelemetryTracesJob::MAX_TRACES_PER_JOB.

Views

• Span waterfall computes relative offsets from span start_time (the template read start_time_relative_ms, which no emitter produces — every bar rendered at 0ms). Also fixes a clamp crash for spans starting at 100%.
• turbo_stream responses are gated on the MIME type being registered — turbo-rails is not a dependency, and without it every dashboard page raised.
• Layout used an undefined active_agent_dashboard. route proxy (the mount helper is active_agent); engine views now use engine-local helpers.

Docs & tests

• docs/framework/dashboard.md: install, what you get, authentication (none by default — stated loudly), remote ingestion, multi-tenant mode, and the dev-console ↔ cloud relationship table. README gains a Dev Console & Observability section. CHANGELOG entry under Unreleased.
• New test/dashboard/ suite (16 tests): payload normalization/dedup, engine paths + autoload, route↔controller consistency, page rendering, LOCAL_ENDPOINT_PATH ingest round-trip, and symbol-keyed reporter persistence — run against the dummy app (now mounts the engine).

Verification

• test/dashboard/: 16 runs, 0 failures/errors (rails8 gemfile)
• Full gem suite: identical results to unmodified main apart from the new tests passing (the pre-existing errors in both runs are missing OPENAI_API_KEY-style credential errors in this environment, not regressions)
• activeagents.ai platform suite (166 runs, 536 assertions) green against this branch with its engine-require workarounds deleted — engine classes autoload, ingest/dedup/read APIs all work through the gem

Notes for reviewers

• Companion PRs: feat(observability): real telemetry pipeline built on the activeagent gem activeagents#90 (platform builds on this engine multi-tenant) and First-class telemetry trace correlation for persisted generations solid_agent#3 (generation-level trace correlation). Once this merges, the platform can drop its require workarounds and its app-side token-dedup override.
• Versioning: no version bump included — the fixes are backwards-compatible for anyone who wasn't relying on the broken behavior, but the routes trim is technically breaking if someone routed to the missing controllers; flagging for the v2 decision.

🤖 Generated with Claude Code

https://claude.ai/code/session_014h5Yw7jE62UyPPAF1h7Mr5

---

Generated by Claude Code