@adonis-agora/telescope 0.1.0

package/dist/src/ai/prompt.js

@@ -0,0 +1,66 @@
+/**
+ * Cap on stack frames sent to the model. The TOP frames carry the throw site and
+ * the immediate callers — the highest-signal part for root-causing — while a deep
+ * tail mostly burns input tokens. Clipping keeps the prompt bounded and cheap.
+ */
+const STACK_FRAME_LIMIT = 25;
+/**
+ * The system prompt. Frames the model as a senior engineer triaging a PRODUCTION
+ * exception and pins the OUTPUT CONTRACT to a strict JSON object so the result is
+ * machine-parseable (cause / fix / confidence) for the dashboard and any
+ * downstream alerting. We ask for confidence explicitly so an operator can
+ * calibrate trust — a low-confidence guess is still useful but should be read as
+ * such.
+ */
+export const SYSTEM_PROMPT = [
+    'You are a senior backend engineer triaging a production exception for a teammate',
+    'in an AdonisJS application. You are given an exception (name, message, stack) and,',
+    'when available, the HTTP route it came from and other telescope entries recorded',
+    'in the same request trace.',
+    '',
+    'Respond with ONLY a single JSON object — no prose, no markdown fences — with',
+    'exactly these keys:',
+    '  "cause": string — two to three sentences on WHAT failed and WHY, grounded in',
+    '           the message and stack. Do not restate the exception verbatim.',
+    '  "fix": string — a concrete, actionable smallest-correct change. Mention a',
+    '         guard/validation if the input looks malformed.',
+    '  "confidence": one of "high", "medium", "low" — your confidence in the diagnosis.',
+    '',
+    'Do not invent file paths or framework details unsupported by the stack. If the',
+    'stack is missing, reason from the message and route and lower your confidence.',
+].join('\n');
+/**
+ * Assemble the USER message from an exception entry and any related trace entries.
+ * Plain labelled sections (not JSON) read better for an LLM. Absent fields are
+ * omitted rather than rendered as `null`, so the model isn't nudged to comment on
+ * missing data.
+ */
+export function buildUserPrompt(entry, related = []) {
+    const content = entry.content;
+    const lines = [];
+    lines.push(`Exception: ${content.name}: ${content.message}`);
+    const routeLine = [content.method, content.url].filter((part) => part).join(' ');
+    if (routeLine !== '')
+        lines.push(`Route: ${routeLine}`);
+    if (entry.traceId !== null)
+        lines.push(`Trace: ${entry.traceId}`);
+    if (typeof content.stack === 'string' && content.stack.trim() !== '') {
+        lines.push('', 'Stack:', clipStack(content.stack));
+    }
+    else {
+        lines.push('', 'Stack: (none captured)');
+    }
+    if (related.length > 0) {
+        lines.push('', 'Other entries in the same trace:');
+        for (const r of related) {
+            lines.push(`- [${r.type}] ${r.summary}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Keep at most the first {@link STACK_FRAME_LIMIT} lines of the stack. */
+function clipStack(stack) {
+    return stack.split('\n').slice(0, STACK_FRAME_LIMIT).join('\n');
+}
+export { STACK_FRAME_LIMIT };
+//# sourceMappingURL=prompt.js.map

package/dist/src/ai/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../src/ai/prompt.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,kFAAkF;IAClF,oFAAoF;IACpF,kFAAkF;IAClF,4BAA4B;IAC5B,EAAE;IACF,8EAA8E;IAC9E,qBAAqB;IACrB,gFAAgF;IAChF,0EAA0E;IAC1E,6EAA6E;IAC7E,yDAAyD;IACzD,oFAAoF;IACpF,EAAE;IACF,gFAAgF;IAChF,gFAAgF;CACjF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAQb;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAmC,EACnC,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,cAAc,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAE7D,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjF,IAAI,SAAS,KAAK,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAElE,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,wBAAwB,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,kCAAkC,CAAC,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/src/ai/telescope_ai_diagnoser.d.ts

@@ -0,0 +1,79 @@
+import type { Entry } from '../entry.js';
+import { type Diagnosis, type ExceptionEntryContent } from './diagnoser.js';
+import { type DiagnosisStore } from './diagnosis_cache.js';
+/**
+ * The minimal slice of the Anthropic SDK client the diagnoser uses. Declared
+ * structurally so tests can inject a fake without the real SDK, and so the
+ * package depends on `@anthropic-ai/sdk` only as a PEER (the host owns the
+ * version). The real `Anthropic` instance satisfies this shape.
+ */
+export interface AnthropicMessagesClient {
+    messages: {
+        create(body: {
+            model: string;
+            max_tokens: number;
+            system?: string;
+            messages: {
+                role: 'user' | 'assistant';
+                content: string;
+            }[];
+        }): Promise<{
+            content: Array<{
+                type: string;
+                text?: string;
+            }>;
+        }>;
+    };
+}
+/** Options for {@link TelescopeAiDiagnoser}. */
+export interface TelescopeAiDiagnoserOptions {
+    /** The Anthropic SDK client (or any value matching {@link AnthropicMessagesClient}). */
+    client: AnthropicMessagesClient;
+    /** Claude model id (e.g. `claude-sonnet-4-6`). */
+    model: string;
+    /** Hard cap on generated tokens per diagnosis. */
+    maxTokens: number;
+    /** Whether diagnosis is active. When `false`, {@link diagnose} is a no-op. Default `true`. */
+    enabled?: boolean;
+    /** Pluggable cache. Defaults to an in-memory {@link DiagnosisCache}. */
+    cache?: DiagnosisStore;
+    /** Failure log sink. Defaults to `console.warn`. */
+    logger?: (message: string) => void;
+}
+/** Per-call options for {@link TelescopeAiDiagnoser.diagnose}. */
+export interface DiagnoseOptions {
+    /**
+     * Other telescope entries recorded in the same trace (queries, the request,
+     * diagnostics). Summarized into the prompt as extra context. Optional.
+     */
+    related?: Entry[];
+    /** Bypass the cache and force a fresh API call (still writes the result back). */
+    force?: boolean;
+}
+/**
+ * AI-assisted diagnosis of `exception` telescope entries via the Anthropic Claude
+ * Messages API. {@link diagnose} builds a prompt from the exception entry (plus
+ * any related trace entries), calls Claude, parses a structured
+ * {@link Diagnosis}, and caches it by the exception's family hash so the same
+ * error is never diagnosed twice.
+ *
+ * Safe by construction: disabled / no client → no-op (`null`); a missing family
+ * hash skips caching; a model or parse failure is logged and resolves to `null`
+ * rather than throwing into the caller's path.
+ */
+export declare class TelescopeAiDiagnoser {
+    private readonly client;
+    private readonly model;
+    private readonly maxTokens;
+    private readonly enabled;
+    private readonly cache;
+    private readonly logger;
+    constructor(options: TelescopeAiDiagnoserOptions);
+    /**
+     * Diagnose one exception entry. Returns the cached diagnosis when the entry's
+     * family has already been diagnosed (no second API call), otherwise calls Claude
+     * once and caches the result. Resolves to `null` when disabled or on any failure.
+     */
+    diagnose(entry: Entry<ExceptionEntryContent>, options?: DiagnoseOptions): Promise<Diagnosis | null>;
+}
+//# sourceMappingURL=telescope_ai_diagnoser.d.ts.map

package/dist/src/ai/telescope_ai_diagnoser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telescope_ai_diagnoser.d.ts","sourceRoot":"","sources":["../../../src/ai/telescope_ai_diagnoser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAkB,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3E;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE;QACR,MAAM,CAAC,IAAI,EAAE;YACX,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,EAAE,MAAM,CAAC;YACnB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,QAAQ,EAAE;gBAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,EAAE,CAAC;SAC7D,GAAG,OAAO,CAAC;YAAE,OAAO,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;KAClE,CAAC;CACH;AAED,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IAC1C,wFAAwF;IACxF,MAAM,EAAE,uBAAuB,CAAC;IAChC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;IAClB,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAEvC,OAAO,EAAE,2BAA2B;IAShD;;;;OAIG;IACG,QAAQ,CACZ,KAAK,EAAE,KAAK,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAgD7B"}

package/dist/src/ai/telescope_ai_diagnoser.js

@@ -0,0 +1,111 @@
+import { parseDiagnosis } from './diagnoser.js';
+import { DiagnosisCache } from './diagnosis_cache.js';
+import { SYSTEM_PROMPT, buildUserPrompt } from './prompt.js';
+/**
+ * AI-assisted diagnosis of `exception` telescope entries via the Anthropic Claude
+ * Messages API. {@link diagnose} builds a prompt from the exception entry (plus
+ * any related trace entries), calls Claude, parses a structured
+ * {@link Diagnosis}, and caches it by the exception's family hash so the same
+ * error is never diagnosed twice.
+ *
+ * Safe by construction: disabled / no client → no-op (`null`); a missing family
+ * hash skips caching; a model or parse failure is logged and resolves to `null`
+ * rather than throwing into the caller's path.
+ */
+export class TelescopeAiDiagnoser {
+    client;
+    model;
+    maxTokens;
+    enabled;
+    cache;
+    logger;
+    constructor(options) {
+        this.client = options.client;
+        this.model = options.model;
+        this.maxTokens = options.maxTokens;
+        this.enabled = options.enabled ?? true;
+        this.cache = options.cache ?? new DiagnosisCache();
+        this.logger = options.logger ?? ((message) => console.warn(message));
+    }
+    /**
+     * Diagnose one exception entry. Returns the cached diagnosis when the entry's
+     * family has already been diagnosed (no second API call), otherwise calls Claude
+     * once and caches the result. Resolves to `null` when disabled or on any failure.
+     */
+    async diagnose(entry, options = {}) {
+        if (!this.enabled)
+            return null;
+        const familyHash = entry.familyHash;
+        if (familyHash !== null && options.force !== true) {
+            const cached = this.cache.get(familyHash);
+            if (cached !== null)
+                return { ...cached, cached: true };
+        }
+        const userPrompt = buildUserPrompt(entry, summarizeRelated(options.related ?? []));
+        let text;
+        try {
+            const response = await this.client.messages.create({
+                model: this.model,
+                max_tokens: this.maxTokens,
+                system: SYSTEM_PROMPT,
+                messages: [{ role: 'user', content: userPrompt }],
+            });
+            text = extractText(response);
+        }
+        catch (error) {
+            this.logger(`Telescope AI: diagnosis API call failed: ${asMessage(error)}`);
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = parseDiagnosis(text);
+        }
+        catch (error) {
+            this.logger(`Telescope AI: could not parse diagnosis: ${asMessage(error)}`);
+            return null;
+        }
+        const diagnosis = {
+            cause: parsed.cause,
+            fix: parsed.fix,
+            confidence: parsed.confidence,
+            model: this.model,
+            cached: false,
+        };
+        if (familyHash !== null) {
+            // Store the un-flagged form; reads stamp `cached: true` on the way out.
+            this.cache.set(familyHash, diagnosis);
+        }
+        return diagnosis;
+    }
+}
+/** Concatenate the text blocks of a Messages API response. */
+function extractText(response) {
+    return response.content
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text ?? '')
+        .join('\n')
+        .trim();
+}
+/** Build a short, bounded summary of each related entry for the prompt. */
+function summarizeRelated(related) {
+    const summaries = [];
+    for (const entry of related) {
+        if (entry.type === 'exception')
+            continue; // the subject itself / sibling exceptions
+        let summary;
+        try {
+            summary = JSON.stringify(entry.content);
+        }
+        catch {
+            summary = '(uninspectable content)';
+        }
+        if (summary.length > 500)
+            summary = `${summary.slice(0, 500)}…`;
+        summaries.push({ type: entry.type, summary });
+    }
+    return summaries;
+}
+function asMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=telescope_ai_diagnoser.js.map

package/dist/src/ai/telescope_ai_diagnoser.js.map

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

package/dist/src/alerts/alert_channel.d.ts

@@ -0,0 +1,69 @@
+import type { AlertPayload } from './alert_rule.js';
+import { type SlackChannelOptions } from './slack_format.js';
+/**
+ * A delivery destination for a fired alert. An alert fans out to EVERY configured
+ * channel concurrently, and a single channel failing NEVER blocks the others (the
+ * {@link Alerter} isolates and warn-logs failures per channel). Implementations
+ * may reject freely — the alerter catches it; the contract is simply "deliver this
+ * payload, or reject, and we'll log it".
+ *
+ * `name` is a stable, human-readable identifier used only for rate-limited failure
+ * logging (e.g. `"slack"`, `"webhook"`, `"console"`) so an operator can tell WHICH
+ * destination is failing without leaking its URL.
+ */
+export interface AlertChannel {
+    /** Stable identifier for failure logging (never the raw URL/secret). */
+    name: string;
+    /** Deliver the payload. Rejecting is fine — the alerter isolates + logs it. */
+    send(alert: AlertPayload): Promise<void>;
+}
+/**
+ * Injectable `fetch` seam so tests can drive the HTTP channels deterministically
+ * without a real network. Mirrors the subset of `fetch` the channels use.
+ */
+export type ChannelFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<unknown>;
+/**
+ * Generic JSON webhook channel — POSTs the {@link AlertPayload} as-is so any relay
+ * that parses the raw body works.
+ *
+ * @param url Destination that receives `POST <AlertPayload as JSON>`.
+ * @param fetchImpl Test seam; defaults to global `fetch`.
+ */
+export declare function webhookChannel(url: string, fetchImpl?: ChannelFetch): AlertChannel;
+/**
+ * Slack-formatted channel — POSTs Block Kit JSON to a Slack incoming webhook so
+ * the message renders as a rich card (severity header, fielded context, a
+ * truncated stack snippet, and a deep link to the dashboard entry when
+ * `dashboardUrl` is configured) instead of a raw JSON blob.
+ *
+ * @param url Slack incoming webhook URL.
+ * @param options Formatting knobs (`username`/`iconEmoji` overrides).
+ * @param fetchImpl Test seam; defaults to global `fetch`.
+ */
+export declare function slackChannel(url: string, options?: SlackChannelOptions, fetchImpl?: ChannelFetch): AlertChannel;
+/** The sink a {@link consoleChannel} writes a one-line summary to. */
+export type ConsoleSink = (message: string) => void;
+/**
+ * Console channel — logs a one-line summary of each alert. The zero-config default
+ * destination: useful in development and as a safety net so an alert is never
+ * silently dropped when no remote channel is configured.
+ *
+ * @param sink Where to write; defaults to `console.warn`.
+ */
+export declare function consoleChannel(sink?: ConsoleSink): AlertChannel;
+/**
+ * Custom channel — the escape hatch. The host supplies an arbitrary async sink
+ * (send an email, publish to SNS, page someone, …) and Telescope calls it with the
+ * rich {@link AlertPayload}. As with every channel, a rejection is isolated and
+ * logged by the alerter, so the host's `fn` may freely throw.
+ *
+ * @param fn Async sink invoked with the fired alert payload.
+ * @param name Identifier for failure logging. Defaults to `"custom"`.
+ */
+export declare function customChannel(fn: (alert: AlertPayload) => Promise<void>, name?: string): AlertChannel;
+//# sourceMappingURL=alert_channel.d.ts.map

package/dist/src/alerts/alert_channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert_channel.d.ts","sourceRoot":"","sources":["../../../src/alerts/alert_channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,KAAK,mBAAmB,EAAsB,MAAM,mBAAmB,CAAC;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAQD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,KACzF,OAAO,CAAC,OAAO,CAAC,CAAC;AAqCtB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,YAAY,CAQlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,mBAAmB,EAC7B,SAAS,CAAC,EAAE,YAAY,GACvB,YAAY,CAQd;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAapD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,YAAY,CAS/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,EAC1C,IAAI,SAAW,GACd,YAAY,CAEd"}

package/dist/src/alerts/alert_channel.js

@@ -0,0 +1,114 @@
+import { formatSlackMessage } from './slack_format.js';
+/**
+ * POST timeout for the built-in HTTP channels. A hung endpoint must never stall
+ * the alerter's fan-out, so every request is raced against an abort timer.
+ */
+const HTTP_CHANNEL_TIMEOUT_MS = 5_000;
+/**
+ * POST a JSON body to `url` with a hard abort timeout. Shared by the webhook and
+ * Slack channels — the ONLY difference between them is the body shape, so the
+ * transport lives here once. Rejects on network error / timeout / non-2xx; the
+ * alerter turns that rejection into a rate-limited warn.
+ */
+async function postJson(fetchImpl, url, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HTTP_CHANNEL_TIMEOUT_MS);
+    timeout.unref?.();
+    try {
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        // A real `fetch` resolves even on a 4xx/5xx; surface those as failures so a
+        // misconfigured webhook is warn-logged rather than silently swallowed. Test
+        // doubles that resolve `undefined` are treated as success.
+        if (response !== undefined &&
+            response !== null &&
+            typeof response === 'object' &&
+            'ok' in response &&
+            response.ok === false) {
+            const status = 'status' in response ? response.status : 'unknown';
+            throw new Error(`HTTP ${String(status)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Generic JSON webhook channel — POSTs the {@link AlertPayload} as-is so any relay
+ * that parses the raw body works.
+ *
+ * @param url Destination that receives `POST <AlertPayload as JSON>`.
+ * @param fetchImpl Test seam; defaults to global `fetch`.
+ */
+export function webhookChannel(url, fetchImpl) {
+    const send = fetchImpl ?? ((u, init) => fetch(u, init));
+    return {
+        name: 'webhook',
+        send(alert) {
+            return postJson(send, url, alert);
+        },
+    };
+}
+/**
+ * Slack-formatted channel — POSTs Block Kit JSON to a Slack incoming webhook so
+ * the message renders as a rich card (severity header, fielded context, a
+ * truncated stack snippet, and a deep link to the dashboard entry when
+ * `dashboardUrl` is configured) instead of a raw JSON blob.
+ *
+ * @param url Slack incoming webhook URL.
+ * @param options Formatting knobs (`username`/`iconEmoji` overrides).
+ * @param fetchImpl Test seam; defaults to global `fetch`.
+ */
+export function slackChannel(url, options, fetchImpl) {
+    const send = fetchImpl ?? ((u, init) => fetch(u, init));
+    return {
+        name: 'slack',
+        send(alert) {
+            return postJson(send, url, formatSlackMessage(alert, options));
+        },
+    };
+}
+/** One-line human summary of an alert for the console channel. */
+function summarize(alert) {
+    const base = `[telescope-alert] ${alert.rule.type} on ${alert.instanceId}`;
+    if (alert.exception !== undefined) {
+        const { class: cls, message, route, occurrences } = alert.exception;
+        const where = route !== null ? ` (${route})` : '';
+        return `${base}: ${cls}: ${message}${where} — ${occurrences}× in window`;
+    }
+    return `${base}: value ${alert.value} (threshold ${alert.threshold})`;
+}
+/**
+ * Console channel — logs a one-line summary of each alert. The zero-config default
+ * destination: useful in development and as a safety net so an alert is never
+ * silently dropped when no remote channel is configured.
+ *
+ * @param sink Where to write; defaults to `console.warn`.
+ */
+export function consoleChannel(sink) {
+    const write = sink ?? ((message) => console.warn(message));
+    return {
+        name: 'console',
+        send(alert) {
+            write(summarize(alert));
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Custom channel — the escape hatch. The host supplies an arbitrary async sink
+ * (send an email, publish to SNS, page someone, …) and Telescope calls it with the
+ * rich {@link AlertPayload}. As with every channel, a rejection is isolated and
+ * logged by the alerter, so the host's `fn` may freely throw.
+ *
+ * @param fn Async sink invoked with the fired alert payload.
+ * @param name Identifier for failure logging. Defaults to `"custom"`.
+ */
+export function customChannel(fn, name = 'custom') {
+    return { name, send: fn };
+}
+//# sourceMappingURL=alert_channel.js.map

package/dist/src/alerts/alert_channel.js.map

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

package/dist/src/alerts/alert_rule.d.ts

@@ -0,0 +1,86 @@
+import type { AlertChannel } from './alert_channel.js';
+/**
+ * A single alerting rule. Ported (trimmed) from the aviary telescope core. This
+ * Adonis port focuses on the two rules the headless `@adonis-agora/telescope` store can
+ * back today:
+ *
+ * - `new-exception`  — fires the FIRST time an exception's `familyHash` is seen
+ *                      within `window` (a genuinely NEW error family), and again
+ *                      if the family re-appears after the window has elapsed (the
+ *                      "re-occurring after being resolved" signal). Deduplication
+ *                      is per-process via {@link NewExceptionTracker}.
+ * - `exception-rate` — fires when `>= threshold` exception entries were recorded
+ *                      in the trailing `window`.
+ */
+export type AlertRule = {
+    type: 'new-exception';
+    window: string;
+} | {
+    type: 'exception-rate';
+    window: string;
+    threshold: number;
+};
+/**
+ * Rich exception context attached to a `new-exception` alert. Pulled from the
+ * exception {@link Entry} that fired the rule. Absent on rate-rule alerts.
+ */
+export interface ExceptionAlertContext {
+    /** Stable family hash that was first-seen this window. */
+    familyHash: string;
+    /** Exception class name (e.g. `TypeError`). */
+    class: string;
+    /** Exception message. */
+    message: string;
+    /** Truncated stack (first frames), or `null`. */
+    stack: string | null;
+    /** Request route/uri associated with the exception, or `null`. */
+    route: string | null;
+    /** Request method, or `null`. */
+    method: string | null;
+    /** Response status code, or `null`. */
+    statusCode: number | null;
+    /** Authenticated user id from a `user:<id>` tag, or `null`. */
+    user: string | null;
+    /** Times this family was seen in the window (>= 1; 1 on first-occurrence). */
+    occurrences: number;
+    /** Exception entry id (for the dashboard deep link). */
+    entryId: string;
+}
+/**
+ * The shape delivered to every {@link AlertChannel} when a rule fires.
+ */
+export interface AlertPayload {
+    rule: AlertRule;
+    /** The measured value that crossed the threshold. */
+    value: number;
+    /** The rule's threshold (`threshold`, or `1` for `new-exception`). */
+    threshold: number;
+    /** ISO-8601 fire time. */
+    firedAt: string;
+    /** The reporting instance identifier. */
+    instanceId: string;
+    /** Rich context for `new-exception` alerts; absent for rate rules. */
+    exception?: ExceptionAlertContext;
+    /** External dashboard URL when configured (lets channels build deep links). */
+    dashboardUrl?: string;
+}
+/**
+ * Validated, boot-resolved alerting config (durations normalized to ms).
+ */
+export interface ResolvedAlerts {
+    /** Whether alerting is active. */
+    enabled: boolean;
+    /** All delivery destinations. */
+    channels: AlertChannel[];
+    /** External dashboard URL for deep links, or `null` when unset. */
+    dashboardUrl: string | null;
+    /** Poll cadence for the exception-entry source, in ms. */
+    intervalMs: number;
+    /** Per-rule / per-family re-notify suppression, in ms. */
+    cooldownMs: number;
+    /** The reporting instance identifier. */
+    instanceId: string;
+    /** Rules to evaluate. */
+    rules: AlertRule[];
+}
+//# sourceMappingURL=alert_rule.d.ts.map

package/dist/src/alerts/alert_rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert_rule.d.ts","sourceRoot":"","sources":["../../../src/alerts/alert_rule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iCAAiC;IACjC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uCAAuC;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,mEAAmE;IACnE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB"}

package/dist/src/alerts/alert_rule.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alert_rule.js.map

package/dist/src/alerts/alert_rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert_rule.js","sourceRoot":"","sources":["../../../src/alerts/alert_rule.ts"],"names":[],"mappings":""}

package/dist/src/alerts/alerter.d.ts

@@ -0,0 +1,72 @@
+import type { Entry } from '../entry.js';
+import type { ResolvedAlerts } from './alert_rule.js';
+export interface AlerterDeps {
+    alerts: ResolvedAlerts;
+    /** Wall-clock seam (ms). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Cap on tracked error families for the `new-exception` rule (test seam). */
+    maxFamilies?: number;
+    /** Failure log sink. Defaults to `console.warn`. */
+    logger?: (message: string) => void;
+}
+/**
+ * Wires a source of exception {@link Entry} objects → rule evaluation → channels.
+ *
+ * Two evaluation paths, both driven by {@link evaluate} (called once per poll with
+ * the exception entries observed since the last poll):
+ *  1. The `new-exception` rule fires the FIRST time a family hash is seen within
+ *     its window (and again after the window elapses / a {@link resolveFamily}),
+ *     deduped by {@link NewExceptionTracker} and rate-limited by the per-family
+ *     cooldown.
+ *  2. The `exception-rate` rule fires when the running count of exception entries
+ *     in its trailing window crosses the threshold, rate-limited by a per-rule
+ *     cooldown.
+ *
+ * Every fired alert fans out to ALL configured channels concurrently; one channel
+ * failing never blocks the others. NEVER throws into the caller: a channel failure
+ * is warn-logged (rate-limited per channel) and otherwise swallowed.
+ */
+export declare class Alerter {
+    private readonly deps;
+    private readonly now;
+    private readonly logger;
+    private readonly tracker;
+    /** Per-rule-index last-fired wall time for the rate-rule cooldown. */
+    private readonly lastFiredAt;
+    /** Per-family last-fired wall time for the `new-exception` cooldown. */
+    private readonly lastFiredFamily;
+    /** Channels we've already warned about (rate-limit failure logs by name). */
+    private readonly warnedChannels;
+    /** Sliding-window timestamps of recent exception entries (rate rule). */
+    private readonly recentExceptions;
+    constructor(deps: AlerterDeps);
+    /**
+     * Evaluate every rule over a freshly-observed batch of exception entries. Safe
+     * to call with an empty batch (rate rules still re-check their window against
+     * already-recorded timestamps). Never throws into the caller.
+     */
+    evaluate(exceptionEntries: Entry[]): Promise<void>;
+    /**
+     * Explicitly forget a family so its next occurrence pages again immediately —
+     * the "resolved → re-occurred" path. Also clears its cooldown.
+     */
+    resolveFamily(familyHash: string): void;
+    /** Number of error families currently tracked (test/observability seam). */
+    get trackedFamilies(): number;
+    private evaluateNewException;
+    private evaluateExceptionRate;
+    /** Find a configured rule of `type` with its array index, or `null`. */
+    private findRule;
+    private inCooldown;
+    private familyInCooldown;
+    private buildRatePayload;
+    private buildNewExceptionPayload;
+    /**
+     * Fan the payload out to every channel concurrently. Each channel's failure is
+     * isolated (`Promise.allSettled`) and warn-logged ONCE per channel name so a
+     * persistently-down destination doesn't flood the logs. Never rejects.
+     */
+    private dispatch;
+    private warnChannelFailure;
+}
+//# sourceMappingURL=alerter.d.ts.map

package/dist/src/alerts/alerter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerter.d.ts","sourceRoot":"","sources":["../../../src/alerts/alerter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,cAAc,CAAC;IACvB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,OAAO;IAaN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;gBAEpB,IAAI,EAAE,WAAW;IAM9C;;;;OAIG;IACG,QAAQ,CAAC,gBAAgB,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKvC,4EAA4E;IAC5E,IAAI,eAAe,IAAI,MAAM,CAE5B;YAEa,oBAAoB;YAyBpB,qBAAqB;IAiBnC,wEAAwE;IACxE,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,wBAAwB;IAmBhC;;;;OAIG;YACW,QAAQ;IAWtB,OAAO,CAAC,kBAAkB;CAM3B"}