Packages
Everything ships as one package — @adonis-agora/telescope — exposing the headless core (with config-driven memory + Lucid storage drivers) plus opt-in subpaths for per-technology watchers, the dashboard UI, alerts, and AI exception diagnosis.
Telescope is one published package, @adonis-agora/telescope, following the first-party
AdonisJS convention (like @adonisjs/auth exposing its guards): the core is enough on its
own (it records and exposes a query API), and every other feature is an opt-in subpath
of that same package. You install @adonis-agora/telescope once; node ace configure @adonis-agora/telescope wires the core and prompts which optional features to enable, registering
the chosen @adonis-agora/telescope/<feature>_provider and publishing its config/*.ts.
| Subpath | Entry / role |
|---|---|
@adonis-agora/telescope | Core capture spine — request + exception + diagnostics watchers, the Entry model, the TelescopeStore contract, the config-driven storage drivers (memory + lucid), TelescopeService, Pulse, the pruner + overload guard, client-error ingestion, and the extension SDK. |
@adonis-agora/telescope/watchers | Per-technology watchers — Lucid query, http-client, logs, mail, cache, queue, events, redis, plus user-driven profiling + schedule. |
@adonis-agora/telescope/ui | The JSON API + SSE live-stream, behind an auth guard. |
@adonis-agora/telescope/alerts | Alerting — new-exception / every-exception / exception-rate / metric-threshold rules → Slack, webhook, console, or custom channels. |
@adonis-agora/telescope/ai | AI-assisted exception diagnosis via the Anthropic Claude API, cached by family. |
@adonis-agora/telescope/mcp | A Model Context Protocol JSON-RPC endpoint so a coding agent can query the captured telemetry. |
@adonis-agora/telescope-ui | Separate package — the React dashboard SPA served under the same prefix and guard as the API. |
The package is MIT, ESM-only, and requires Node 20.6+ and @adonisjs/core ^7.3.0. Optional peers (@adonisjs/lucid, @adonisjs/mail,
@adonisjs/cache, @anthropic-ai/sdk) are installed only for the features that use them.
How they fit together
The core publishes a live store on a cross-copy-stable global slot at boot. The watchers,
UI, alerts, and AI subpaths all reach that same store through the slot — no dependency
injection, no inter-package wiring. The core has zero @adonis-agora/* dependencies; it
reads @adonis-agora/context and @adonis-agora/diagnostics
structurally and degrades gracefully when they're absent.
Core
The capture spine, Entry model, store contract, query API, and extension SDK.
Watchers
Query, http-client, logs, mail, cache, queue, events, redis, profiling + schedule watchers.
Pulse
The aggregated at-a-glance health rollup over stored entries.
Metrics API
MetricsService + the pure percentile / timeseries / trace / waterfall functions behind the dashboard analytics.
Storage drivers
The config-driven memory + Lucid stores built into the core.
Dashboard UI
The JSON API + SSE live-stream, behind an auth guard.
Dashboard SPA
The React observability dashboard (@adonis-agora/telescope-ui).
Alerts
Page on new exception families and metric thresholds via Slack, webhook, or custom channels.
AI
Structured root-cause diagnosis of exceptions, cached by family.
MCP
Query the captured telemetry from a coding agent over the Model Context Protocol.
Client errors
A public, opt-in endpoint for browser-reported front-end errors.
Advanced / programmatic
The bounded-redaction, tail-sampling, and live-stream store decorators for wiring a custom store chain by hand.
Dashboard auth
How the Telescope dashboard is gated — the default allow-in-dev / deny-in-prod policy, the built-in token and HTTP Basic credentials, delegating to your own app auth with an authorize hook, and the 401-vs-403 fail-closed guard behaviour.
@adonis-agora/telescope
The headless core — the request, exception and diagnostics watchers, the uniform Entry model, the TelescopeStore contract and in-memory ring buffer, the TelescopeService query API, the extension SDK, and the structural readers for context and diagnostics.