@adonis-agora/telescope 0.3.3 → 0.5.0

package/dist/src/watchers/schedule_watcher.d.ts

@@ -0,0 +1,143 @@
+import { type RecordInput } from '../entry.js';
+/** The `type` of the entries this watcher records. */
+export declare const SCHEDULED_TASK_ENTRY_TYPE: "scheduled_task";
+/** The terminal outcome of a single scheduled-task run. */
+export type ScheduleRunStatus = 'completed' | 'failed';
+/** What kind of schedule triggered the run (best-effort, informational). */
+export type ScheduleKind = 'cron' | 'interval' | 'custom';
+/** The recorded body of a `scheduled_task` entry. */
+export interface ScheduleEntryContent {
+    /** The task name, e.g. `'prune-sessions'`. */
+    name: string;
+    /** The cron/interval expression, or `null` when the caller did not supply one. */
+    schedule: string | null;
+    /** The schedule kind. */
+    kind: ScheduleKind;
+    /** Wall-clock duration of the run in milliseconds. */
+    durationMs: number;
+    /** The run outcome. */
+    status: ScheduleRunStatus;
+    /** How many attempts the run represents, or `null`. */
+    attempts: number | null;
+    /** The failure message when `status` is `'failed'`, else `null`. */
+    failureReason: string | null;
+    /** The active trace id at run time, or `null`. */
+    traceId: string | null;
+}
+/** A single scheduled-task run — the input to {@link buildScheduleEntry} and
+ *  {@link recordScheduledRun}. */
+export interface ScheduledRun {
+    /** The task name. */
+    name: string;
+    /** The run outcome. */
+    status: ScheduleRunStatus;
+    /** Wall-clock duration of the run in milliseconds. */
+    durationMs: number;
+    /** The cron/interval expression, when known. */
+    schedule?: string | null;
+    /** The schedule kind. Default `'cron'`. */
+    kind?: ScheduleKind;
+    /** How many attempts the run represents, when known. */
+    attempts?: number | null;
+    /** The error on a failed run (its message is stored). */
+    error?: unknown;
+}
+/** Options for {@link ScheduleWatcher} and {@link ScheduleWatcher.scheduleTask}. */
+export interface ScheduleWatcherOptions {
+    /** Runs at/above this many ms get a `slow` tag. Default 1000. */
+    slowMs?: number;
+    /** Time source; injectable for tests. Default `Date.now`. */
+    clock?: {
+        now(): number;
+    };
+}
+/** Per-task metadata for the {@link ScheduleWatcher.scheduleTask} wrapper. */
+export interface ScheduledTaskOptions {
+    /** The cron/interval expression, recorded on each run. */
+    schedule?: string | null;
+    /** The schedule kind. Default `'cron'`. */
+    kind?: ScheduleKind;
+}
+/**
+ * Records each scheduled-task run as a `scheduled_task` telescope entry — capturing
+ * the task name, cron/interval expression, duration and outcome
+ * (completed/failed), correlated to the active trace.
+ *
+ * ## Integration point — a wrapper, by design (not a fake event)
+ * The NestJS original wraps `@nestjs/schedule`'s `@Cron`/`@Interval`/`@Timeout`
+ * decorators via its `SchedulerRegistry`. AdonisJS ships NO first-party scheduler,
+ * and the community schedulers (`adonisjs-scheduler` et al.) emit nothing on the
+ * app emitter and expose no lifecycle hook — so there is no stable event to tap.
+ * Rather than fabricate one, this watcher's integration point is EXPLICIT and
+ * idiomatic:
+ *
+ *  - wrap a scheduled closure with {@link scheduleTask} (it times the run and
+ *    records completed/failed, always re-throwing), or
+ *  - call {@link recordScheduledRun} yourself from an existing scheduler callback
+ *    (e.g. an ace `scheduler:run` command, or a scheduler that DOES surface a
+ *    run hook) with the outcome you already have.
+ *
+ * (In the Agora ecosystem, `@adonis-agora/durable` also bridges its scheduled/cron
+ * runs onto the diagnostics bus, which the diagnostics watcher records — this
+ * watcher covers plain application-level scheduled work.)
+ *
+ * Each entry carries `familyHash` (`schedule:<name>`) and `durationMs`, so repeated
+ * runs of the same task roll up and feed the slow-hotspot metrics cards. Recording
+ * is fire-and-forget and fully guarded: a telescope failure can never break (or
+ * delay) a scheduled task.
+ *
+ * Idiomatic Adonis: a plain class, no DI decorators. The provider constructs it
+ * from `config/telescope_watchers.ts` and calls {@link start} to publish it as the
+ * default backing the bare {@link scheduleTask} / {@link recordScheduledRun}
+ * helpers; {@link stop} unpublishes.
+ */
+export declare class ScheduleWatcher {
+    readonly type: "scheduled_task";
+    private readonly slowMs;
+    private readonly clock;
+    constructor(options?: ScheduleWatcherOptions);
+    /** Publish this configured instance as the default the standalone helpers
+     *  inherit. Does NOT patch any global. Named `start`/`stop` to match the other
+     *  watchers' provider lifecycle. */
+    start(): void;
+    /** Unpublish this instance as the default (if it is). Never touches globals. */
+    stop(): void;
+    /** Record one already-completed scheduled run. Fire-and-forget; never throws. */
+    record(run: ScheduledRun): void;
+    /**
+     * Time `fn` as a scheduled run named `name`. Records `completed` on
+     * return/resolve and `failed` on throw/reject, always re-throwing so the
+     * scheduler's own error handling is unaffected. Works with sync and async `fn`.
+     *
+     * @example
+     *   scheduler.call(() => scheduleTask('prune-sessions', () => Session.pruneExpired(), {
+     *     schedule: '0 * * * *',
+     *   })).hourly()
+     */
+    scheduleTask<T>(name: string, fn: () => T, options?: ScheduledTaskOptions): T;
+}
+/** Map a scheduled run to a telescope {@link RecordInput}. Exported so the entry
+ *  shape can be unit-tested without a live watcher. */
+export declare function buildScheduleEntry(run: ScheduledRun, slowMs?: number): RecordInput<ScheduleEntryContent>;
+/**
+ * Record one scheduled-task run through the provider-published default watcher.
+ * A NO-OP when the schedule watcher is not enabled, so it is safe to call from a
+ * scheduler callback unconditionally.
+ *
+ * @example
+ *   import { recordScheduledRun } from '@adonis-agora/telescope/watchers'
+ *   recordScheduledRun({ name: 'prune-sessions', status: 'completed', durationMs: 42 })
+ */
+export declare function recordScheduledRun(run: ScheduledRun): void;
+/**
+ * Time `fn` as a scheduled run through the provider-published default watcher. A
+ * no-op passthrough (just runs `fn`) when the schedule watcher is not enabled.
+ * This is the recommended integration point: wrap the closure you hand your
+ * scheduler.
+ *
+ * @example
+ *   import { scheduleTask } from '@adonis-agora/telescope/watchers'
+ *   scheduler.call(() => scheduleTask('report', () => sendDailyReport())).daily()
+ */
+export declare function scheduleTask<T>(name: string, fn: () => T, options?: ScheduledTaskOptions): T;
+//# sourceMappingURL=schedule_watcher.d.ts.map

package/dist/src/watchers/schedule_watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule_watcher.d.ts","sourceRoot":"","sources":["../../../src/watchers/schedule_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1D,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,kBAA0B,CAAC;AAEjE,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE1D,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yBAAyB;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kDAAkD;IAClD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;kCACkC;AAClC,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,mBAA2B;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAE9B,OAAO,GAAE,sBAA2B;IAKhD;;wCAEoC;IACpC,KAAK,IAAI,IAAI;IAIb,gFAAgF;IAChF,IAAI,IAAI,IAAI;IAIZ,iFAAiF;IACjF,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAI/B;;;;;;;;;OASG;IACH,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,CAAC;CAmClF;AAWD;uDACuD;AACvD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,SAAkB,GACvB,WAAW,CAAC,oBAAoB,CAAC,CAkCnC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,oBAAoB,GAC7B,CAAC,CAIH"}

package/dist/src/watchers/schedule_watcher.js

@@ -0,0 +1,195 @@
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { safeRecord } from './record.js';
+/** The `type` of the entries this watcher records. */
+export const SCHEDULED_TASK_ENTRY_TYPE = EntryType.ScheduledTask;
+/** Default slow-run threshold in milliseconds. */
+const DEFAULT_SLOW_MS = 1000;
+/**
+ * Cross-copy-stable slot holding the provider-configured default watcher, so the
+ * standalone {@link recordScheduledRun} / {@link scheduleTask} helpers inherit the
+ * app's configured `slowMs` — and are a NO-OP until the provider starts the watcher
+ * (schedule capture stays strictly opt-in). Mirrors the http-client / profiling
+ * watchers' default-slot stance.
+ */
+const DEFAULT_SLOT = Symbol.for('@agora/telescope:defaultScheduleWatcher');
+const slotHost = globalThis;
+function setDefaultScheduleWatcher(watcher) {
+    slotHost[DEFAULT_SLOT] = watcher;
+}
+function getDefaultScheduleWatcher() {
+    return slotHost[DEFAULT_SLOT] ?? null;
+}
+/**
+ * Records each scheduled-task run as a `scheduled_task` telescope entry — capturing
+ * the task name, cron/interval expression, duration and outcome
+ * (completed/failed), correlated to the active trace.
+ *
+ * ## Integration point — a wrapper, by design (not a fake event)
+ * The NestJS original wraps `@nestjs/schedule`'s `@Cron`/`@Interval`/`@Timeout`
+ * decorators via its `SchedulerRegistry`. AdonisJS ships NO first-party scheduler,
+ * and the community schedulers (`adonisjs-scheduler` et al.) emit nothing on the
+ * app emitter and expose no lifecycle hook — so there is no stable event to tap.
+ * Rather than fabricate one, this watcher's integration point is EXPLICIT and
+ * idiomatic:
+ *
+ *  - wrap a scheduled closure with {@link scheduleTask} (it times the run and
+ *    records completed/failed, always re-throwing), or
+ *  - call {@link recordScheduledRun} yourself from an existing scheduler callback
+ *    (e.g. an ace `scheduler:run` command, or a scheduler that DOES surface a
+ *    run hook) with the outcome you already have.
+ *
+ * (In the Agora ecosystem, `@adonis-agora/durable` also bridges its scheduled/cron
+ * runs onto the diagnostics bus, which the diagnostics watcher records — this
+ * watcher covers plain application-level scheduled work.)
+ *
+ * Each entry carries `familyHash` (`schedule:<name>`) and `durationMs`, so repeated
+ * runs of the same task roll up and feed the slow-hotspot metrics cards. Recording
+ * is fire-and-forget and fully guarded: a telescope failure can never break (or
+ * delay) a scheduled task.
+ *
+ * Idiomatic Adonis: a plain class, no DI decorators. The provider constructs it
+ * from `config/telescope_watchers.ts` and calls {@link start} to publish it as the
+ * default backing the bare {@link scheduleTask} / {@link recordScheduledRun}
+ * helpers; {@link stop} unpublishes.
+ */
+export class ScheduleWatcher {
+    type = EntryType.ScheduledTask;
+    slowMs;
+    clock;
+    constructor(options = {}) {
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+        this.clock = options.clock ?? { now: () => Date.now() };
+    }
+    /** Publish this configured instance as the default the standalone helpers
+     *  inherit. Does NOT patch any global. Named `start`/`stop` to match the other
+     *  watchers' provider lifecycle. */
+    start() {
+        setDefaultScheduleWatcher(this);
+    }
+    /** Unpublish this instance as the default (if it is). Never touches globals. */
+    stop() {
+        if (getDefaultScheduleWatcher() === this)
+            setDefaultScheduleWatcher(null);
+    }
+    /** Record one already-completed scheduled run. Fire-and-forget; never throws. */
+    record(run) {
+        safeRecord(buildScheduleEntry(run, this.slowMs), 'ScheduleWatcher');
+    }
+    /**
+     * Time `fn` as a scheduled run named `name`. Records `completed` on
+     * return/resolve and `failed` on throw/reject, always re-throwing so the
+     * scheduler's own error handling is unaffected. Works with sync and async `fn`.
+     *
+     * @example
+     *   scheduler.call(() => scheduleTask('prune-sessions', () => Session.pruneExpired(), {
+     *     schedule: '0 * * * *',
+     *   })).hourly()
+     */
+    scheduleTask(name, fn, options = {}) {
+        const startedAt = this.clock.now();
+        const finish = (status, error) => {
+            this.record({
+                name,
+                status,
+                durationMs: Math.max(0, this.clock.now() - startedAt),
+                schedule: options.schedule ?? null,
+                kind: options.kind ?? 'cron',
+                error,
+            });
+        };
+        let result;
+        try {
+            result = fn();
+        }
+        catch (error) {
+            finish('failed', error);
+            throw error;
+        }
+        if (isPromiseLike(result)) {
+            return result.then((value) => {
+                finish('completed', undefined);
+                return value;
+            }, (error) => {
+                finish('failed', error);
+                throw error;
+            });
+        }
+        finish('completed', undefined);
+        return result;
+    }
+}
+/** Narrow a value to a thenable so async `fn`s are awaited without importing a Promise type. */
+function isPromiseLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.then === 'function');
+}
+/** Map a scheduled run to a telescope {@link RecordInput}. Exported so the entry
+ *  shape can be unit-tested without a live watcher. */
+export function buildScheduleEntry(run, slowMs = DEFAULT_SLOW_MS) {
+    const durationMs = Math.max(0, run.durationMs);
+    const failed = run.status === 'failed';
+    const failureReason = failed && run.error !== undefined ? errorMessage(run.error) : null;
+    const kind = run.kind ?? 'cron';
+    const schedule = typeof run.schedule === 'string' ? run.schedule : null;
+    const attempts = typeof run.attempts === 'number' ? run.attempts : null;
+    const traceId = currentTraceId();
+    const content = {
+        name: run.name,
+        schedule,
+        kind,
+        durationMs,
+        status: run.status,
+        attempts,
+        failureReason,
+        traceId,
+    };
+    const tags = ['schedule', `schedule:${kind}`, `task:${run.name}`, `status:${run.status}`];
+    if (failed)
+        tags.push('failed');
+    if (durationMs >= slowMs)
+        tags.push('slow');
+    return {
+        type: EntryType.ScheduledTask,
+        // Group by task name so every run of the same task rolls up — the slow-hotspot key.
+        familyHash: `schedule:${run.name}`,
+        content,
+        durationMs,
+        origin: 'schedule',
+        traceId,
+        tags,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Record one scheduled-task run through the provider-published default watcher.
+ * A NO-OP when the schedule watcher is not enabled, so it is safe to call from a
+ * scheduler callback unconditionally.
+ *
+ * @example
+ *   import { recordScheduledRun } from '@adonis-agora/telescope/watchers'
+ *   recordScheduledRun({ name: 'prune-sessions', status: 'completed', durationMs: 42 })
+ */
+export function recordScheduledRun(run) {
+    getDefaultScheduleWatcher()?.record(run);
+}
+/**
+ * Time `fn` as a scheduled run through the provider-published default watcher. A
+ * no-op passthrough (just runs `fn`) when the schedule watcher is not enabled.
+ * This is the recommended integration point: wrap the closure you hand your
+ * scheduler.
+ *
+ * @example
+ *   import { scheduleTask } from '@adonis-agora/telescope/watchers'
+ *   scheduler.call(() => scheduleTask('report', () => sendDailyReport())).daily()
+ */
+export function scheduleTask(name, fn, options) {
+    const watcher = getDefaultScheduleWatcher();
+    if (watcher)
+        return watcher.scheduleTask(name, fn, options);
+    return fn();
+}
+//# sourceMappingURL=schedule_watcher.js.map

package/dist/src/watchers/schedule_watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule_watcher.js","sourceRoot":"","sources":["../../../src/watchers/schedule_watcher.ts"],"names":[],"mappings":"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"}

package/dist/stubs/config/telescope.stub

@@ -1,65 +0,0 @@
-{{{
-  exports({ to: app.configPath('telescope.ts') })
-}}}
-import { defineConfig, storage } from '@adonis-agora/telescope'
-
-/**
- * Configuration for `@adonis-agora/telescope`. Everything is optional — the defaults use
- * the in-memory store with both watchers (`request` + `diagnostics`) enabled and a
- * 1000-entry cap.
- */
-export default defineConfig({
-  /**
-   * Master switch. Set to `false` to disable all recording (zero overhead).
-   */
-  // enabled: true,
-
-  /**
-   * Which named store backs telescope. The active driver is selected by `store`
-   * and built from the `stores` map below.
-   */
-  store: 'memory',
-
-  /**
-   * Named store drivers, built with the `storage` factory. Each is a lazy thunk —
-   * its peer dependency is only imported when that driver is the active one.
-   *
-   * To persist entries across restarts, install `@adonisjs/lucid`, publish the
-   * migration (`node ace make:migration create_telescope_entries_table`, copying the
-   * body from this package's stub) or pass `autoCreateTable: true`, switch
-   * `store` to `'lucid'`, and uncomment the lucid driver:
-   */
-  stores: {
-    memory: storage.memory({ limit: 1000 }),
-    // lucid: storage.lucid({ connection: 'pg' }),
-  },
-
-  /**
-   * Active watchers. Omit one to disable it.
-   *  - 'request'     — records each HTTP request (method, url, status, duration).
-   *  - 'diagnostics' — records every `agora:<lib>:<event>` diagnostics publish.
-   */
-  // watchers: ['request', 'diagnostics'],
-
-  /**
-   * Sensitive-data redaction. Every entry's content is scrubbed before it is
-   * persisted — a built-in set of sensitive keys (`authorization`, `cookie`,
-   * `password`, `token`, `api_key`, `secret`, `set-cookie`, …) is masked with
-   * `[REDACTED]`, case-insensitively, at any depth. ENABLED by default.
-   *
-   * Add your own keys, or disable redaction entirely:
-   */
-  // redact: {
-  //   enabled: true,
-  //   keys: ['ssn', 'credit_card'],
-  // },
-
-  /**
-   * Live SSE streaming of new entries to the dashboard. ENABLED by default and
-   * zero-overhead while no dashboard is connected. Set `enabled: false` to turn
-   * the `<telescope>/api/stream` endpoint off entirely.
-   */
-  // stream: {
-  //   enabled: true,
-  // },
-})

package/dist/stubs/config/telescope_ai.stub

@@ -1,36 +0,0 @@
-{{{
-  exports({ to: app.configPath('telescope_ai.ts') })
-}}}
-import env from '#start/env'
-import { defineConfig } from '@adonis-agora/telescope/ai'
-
-/**
- * Configuration for `@adonis-agora/telescope/ai`. Diagnosis is on when an Anthropic API
- * key resolves from the environment; with no key the diagnoser is a safe no-op.
- *
- * Add `ANTHROPIC_API_KEY` to your `.env` and validate it in `start/env.ts`:
- *   ANTHROPIC_API_KEY: Env.schema.string.optional()
- */
-export default defineConfig({
-  /**
-   * Master switch. Set to `false` to disable diagnosis entirely.
-   */
-  // enabled: true,
-
-  /**
-   * The Anthropic API key — sourced from the environment, never hardcoded.
-   */
-  apiKey: env.get('ANTHROPIC_API_KEY'),
-
-  /**
-   * Claude model id. Defaults to `claude-sonnet-4-6` (best speed/intelligence
-   * balance). Use `claude-opus-4-8` for the most capable diagnosis, or
-   * `claude-haiku-4-5-20251001` for the cheapest.
-   */
-  // model: 'claude-sonnet-4-6',
-
-  /**
-   * Hard cap on generated tokens per diagnosis. Default 1024.
-   */
-  // maxTokens: 1024,
-})

package/dist/stubs/config/telescope_alerts.stub

@@ -1,47 +0,0 @@
-{{{
-  exports({ to: app.configPath('telescope_alerts.ts') })
-}}}
-import { defineConfig } from '@adonis-agora/telescope/alerts'
-
-/**
- * Configuration for `@adonis-agora/telescope/alerts`. By default alerting is on, polls the
- * telescope store every 30s for brand-new exception families, and logs each alert
- * to the console. Add a Slack or generic webhook channel to ship alerts off-box.
- */
-export default defineConfig({
-  /**
-   * Master switch. Set to `false` to disable alerting entirely.
-   */
-  // enabled: true,
-
-  /**
-   * Delivery destinations. Each fired alert is sent to every channel concurrently;
-   * one channel failing never blocks the others. Accepts declarative specs or
-   * pre-built channel objects (slackChannel/webhookChannel/customChannel).
-   */
-  // channels: [
-  //   { type: 'console' },
-  //   { type: 'slack', url: env.get('TELESCOPE_SLACK_WEBHOOK') },
-  //   { type: 'webhook', url: env.get('TELESCOPE_ALERT_WEBHOOK') },
-  // ],
-
-  /**
-   * Rules to evaluate.
-   *  - { type: 'new-exception', window } — page the first time an exception family
-   *    is seen within `window` (and again after it elapses / on resolve).
-   *  - { type: 'exception-rate', window, threshold } — page when >= threshold
-   *    exceptions are recorded in the trailing `window`.
-   */
-  // rules: [{ type: 'new-exception', window: '1h' }],
-
-  /**
-   * External dashboard URL — when set, Slack alerts include a deep link to the entry.
-   */
-  // dashboardUrl: 'https://telescope.example.com/',
-
-  /**
-   * Poll cadence and re-notify cooldown (duration strings).
-   */
-  // every: '30s',
-  // cooldown: '15m',
-})

package/dist/stubs/config/telescope_ui.stub

@@ -1,53 +0,0 @@
-{{{
-  exports({ to: app.configPath('telescope_ui.ts') })
-}}}
-import { defineConfig } from '@adonis-agora/telescope/ui'
-
-/**
- * Configuration for `@adonis-agora/telescope/ui`. By default the dashboard mounts at
- * `/telescope` and is reachable automatically outside production. In production it
- * is denied unless you set a `token` / `basic` credential below, or supply your
- * own `authorize` hook delegating to your app's auth.
- */
-export default defineConfig({
-  /**
-   * Master switch. Set to `false` to register no routes at all.
-   */
-  // enabled: true,
-
-  /**
-   * URL prefix. The dashboard is served here; the JSON API lives at `<path>/api/*`.
-   */
-  // path: '/telescope',
-
-  /**
-   * Access-decision hook. Return `true` to allow the request, `false` to reject it
-   * (the guard answers 401 when no credential was presented, 403 when one was and
-   * was rejected). Delegate to your own app auth here, e.g.:
-   */
-  // authorize: (ctx) => ctx.auth?.user?.isAdmin === true,
-
-  /**
-   * Built-in credentials for the default policy (ignored when `authorize` is set).
-   * Gate a production dashboard without writing a hook:
-   *  - token: allow `Authorization: Bearer <token>` or `?token=<token>`
-   *  - basic: allow HTTP Basic auth
-   */
-  // credentials: {
-  //   token: env.get('TELESCOPE_UI_TOKEN'),
-  //   basic: { username: 'admin', password: env.get('TELESCOPE_UI_PASSWORD') },
-  // },
-
-  /**
-   * Request REPLAY: re-issue a captured request from the dashboard against the
-   * LOCAL server. DISABLED BY DEFAULT because it re-runs a real request that may
-   * MUTATE state (a captured POST/DELETE runs again). It only ever targets
-   * `127.0.0.1:<port>` (same-origin, never an arbitrary URL) and strips
-   * cookie/authorization/host headers. Enable it knowingly:
-   */
-  // replay: {
-  //   enabled: true,
-  //   // port: 3333,      // defaults to PORT env or 3000
-  //   // timeoutMs: 30000,
-  // },
-})

package/dist/stubs/config/telescope_watchers.stub

@@ -1,41 +0,0 @@
-{{{
-  exports({ to: app.configPath('telescope_watchers.ts') })
-}}}
-import { defineConfig } from '@adonis-agora/telescope/watchers'
-
-/**
- * Configuration for `@adonis-agora/telescope/watchers`. By default only the Lucid
- * `query` watcher is enabled — its `db:query` event is verified against the
- * installed `@adonisjs/lucid` types. The `mail` and `cache` watchers are opt-in.
- */
-export default defineConfig({
-  /**
-   * Master switch. Set to `false` to start no per-technology watcher.
-   */
-  // enabled: true,
-
-  /**
-   * Active watchers. Omit one to disable it.
-   *  - 'query'       — records every Lucid SQL query (sql, bindings, duration, connection).
-   *  - 'mail'        — records every email sent (mail:sent).
-   *  - 'cache'       — records @adonisjs/cache hit/miss/write/delete events.
-   *  - 'http-client' — records every outbound fetch call (method, url, status, duration).
-   *  - 'logs'        — records AdonisJS logger output (level, message, structured fields).
-   *  - 'queue'       — records @adonisjs/queue job executions (optional peer; engine
-   *                    diagnostics-channel trace). No-op when the peer is absent.
-   *  - 'events'      — records every event emitted through the core Emitter (onAny),
-   *                    with an ignore-list (db:query / mail:sent are excluded by default).
-   *  - 'redis'       — records @adonisjs/redis commands (optional peer; wraps the
-   *                    ioredis sendCommand). No-op when the peer is absent.
-   *
-   * Note: the 'mail' / 'cache' / 'queue' / 'redis' event contracts are best-effort —
-   * those packages are not present in this repo, so their event names/payloads could
-   * not be verified against their types. See the package README.
-   *
-   * There is intentionally NO 'schedule' watcher: AdonisJS ships no first-party
-   * scheduler and community schedulers expose no event/hook surface to tap. In the
-   * Agora ecosystem, @adonis-agora/durable bridges scheduled/cron runs onto the
-   * diagnostics bus, which the diagnostics watcher already records.
-   */
-  // watchers: ['query'],
-})

package/dist/stubs/database/migrations/create_telescope_entries_table.stub

@@ -4,9 +4,9 @@
 import { BaseSchema } from '@adonisjs/lucid/schema'
 
 /**
- * Creates the table the `lucid` telescope store persists entries into.
+ * Creates the table the 'lucid' telescope store persists entries into.
  *
- * `content` and `tags` are JSON text columns; `created_at` is stored as epoch
+ * 'content' and 'tags' are JSON text columns; 'created_at' is stored as epoch
  * milliseconds (a plain integer) so newest-first ordering and age-based pruning
  * are driver-agnostic integer comparisons across sqlite / Postgres / MySQL.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/telescope",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Laravel Telescope-style headless observability for AdonisJS — records HTTP requests and every Agora diagnostics event as queryable entries, plus opt-in subpaths for per-technology watchers, a web dashboard, AI exception diagnosis, and alerting.",
   "license": "MIT",
   "repository": {
@@ -63,6 +63,16 @@
       "import": "./dist/providers/telescope_ai_provider.js",
       "default": "./dist/providers/telescope_ai_provider.js"
     },
+    "./mcp": {
+      "types": "./dist/src/mcp/index.d.ts",
+      "import": "./dist/src/mcp/index.js",
+      "default": "./dist/src/mcp/index.js"
+    },
+    "./mcp_provider": {
+      "types": "./dist/providers/telescope_mcp_provider.d.ts",
+      "import": "./dist/providers/telescope_mcp_provider.js",
+      "default": "./dist/providers/telescope_mcp_provider.js"
+    },
     "./alerts": {
       "types": "./dist/src/alerts/index.d.ts",
       "import": "./dist/src/alerts/index.js",
@@ -131,7 +141,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && pnpm run copy:stubs && pnpm run copy:assets",
-    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations && cp stubs/config/telescope.stub dist/stubs/config/telescope.stub && cp stubs/config/telescope_watchers.stub dist/stubs/config/telescope_watchers.stub && cp stubs/config/telescope_ui.stub dist/stubs/config/telescope_ui.stub && cp stubs/config/telescope_ai.stub dist/stubs/config/telescope_ai.stub && cp stubs/config/telescope_alerts.stub dist/stubs/config/telescope_alerts.stub && cp stubs/database/migrations/create_telescope_entries_table.stub dist/stubs/database/migrations/create_telescope_entries_table.stub",
+    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations && cp stubs/config/telescope.stub dist/stubs/config/telescope.stub && cp stubs/config/telescope_watchers.stub dist/stubs/config/telescope_watchers.stub && cp stubs/config/telescope_ui.stub dist/stubs/config/telescope_ui.stub && cp stubs/config/telescope_ai.stub dist/stubs/config/telescope_ai.stub && cp stubs/config/telescope_alerts.stub dist/stubs/config/telescope_alerts.stub && cp stubs/config/telescope_mcp.stub dist/stubs/config/telescope_mcp.stub && cp stubs/database/migrations/create_telescope_entries_table.stub dist/stubs/database/migrations/create_telescope_entries_table.stub",
     "copy:assets": "mkdir -p dist/src/ui && cp src/ui/dashboard.html dist/src/ui/dashboard.html",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",