@adonis-agora/telescope 0.4.0 → 0.5.0

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

@@ -0,0 +1,106 @@
+import type { Entry } from '../entry.js';
+import type { Diagnosis, ExceptionEntryContent } from './diagnoser.js';
+import type { DiagnoseOptions } from './telescope_ai_diagnoser.js';
+/**
+ * Default per-diagnosis wall-clock budget the coordinator enforces (ms). The
+ * on-demand MCP call and the alert path both wait AT MOST this long for a model
+ * response; a slower diagnosis loses the race and the caller proceeds without it
+ * (the underlying call keeps running and its result still lands in the cache for
+ * the next reader).
+ */
+declare const DEFAULT_TIMEOUT_MS = 8000;
+/**
+ * The minimal diagnoser surface the coordinator drives. {@link TelescopeAiDiagnoser}
+ * satisfies it; a test injects a fake. Declared STRUCTURALLY so the coordinator —
+ * and everything that imports it, including the core `index.ts` — has NO dependency
+ * on the Anthropic SDK. The host supplies the concrete provider; when it supplies
+ * none, `diagnoser` is `null` and the coordinator is an inert no-op.
+ */
+export interface DiagnoserLike {
+    diagnose(entry: Entry<ExceptionEntryContent>, options?: DiagnoseOptions): Promise<Diagnosis | null>;
+}
+/**
+ * A compact, transport-friendly projection of a {@link Diagnosis} (drops the
+ * `cached` flag). This is what the alerter attaches to an alert payload, so a
+ * Slack/webhook consumer sees a stable, minimal shape.
+ */
+export interface DiagnosisSummary {
+    cause: string;
+    fix: string;
+    confidence: string;
+    model: string;
+}
+/** Construction deps for {@link DiagnosisCoordinator}. */
+export interface DiagnosisCoordinatorOptions {
+    /**
+     * The resolved diagnoser, or `null` when AI is unconfigured. When `null`,
+     * {@link DiagnosisCoordinator.isConfigured} is `false` and every diagnose call
+     * resolves to `null` — the feature is entirely inert with no configured provider.
+     */
+    diagnoser: DiagnoserLike | null;
+    /** Per-diagnosis timeout in ms. `<= 0` disables the timeout. Default 8000. */
+    timeoutMs?: number;
+    /** Failure log sink. Defaults to `console.warn`. */
+    logger?: (message: string) => void;
+}
+/**
+ * Central AI-diagnosis coordinator — the single seam the MCP `diagnose_exception`
+ * tool and the alerter's `new-exception` path both call. It owns the resolved
+ * diagnoser and adds three safety properties on top of it:
+ *
+ *  - **Optional / lazy**: constructed with `diagnoser: null` when the host has not
+ *    configured AI, in which case it is a pure no-op ({@link isConfigured} is
+ *    `false` and diagnose calls return `null`). Nothing imports the LLM SDK through
+ *    it — the provider supplies the concrete diagnoser.
+ *  - **De-duped**: concurrent diagnose calls for the SAME exception family share one
+ *    in-flight promise, so two simultaneous callers (an MCP request and an alert)
+ *    never trigger two model calls. Completed diagnoses are additionally cached by
+ *    the underlying diagnoser (by family hash).
+ *  - **Fail-safe**: a per-call timeout bounds the wait, and ANY diagnoser failure
+ *    (rejection or timeout) resolves to `null` and is logged — it NEVER throws into
+ *    the host's MCP transport or alert flush path.
+ */
+export declare class DiagnosisCoordinator {
+    private readonly diagnoser;
+    private readonly timeoutMs;
+    private readonly logger;
+    /** In-flight diagnoses keyed by family hash, so concurrent callers coalesce. */
+    private readonly inFlight;
+    constructor(options: DiagnosisCoordinatorOptions);
+    /** Whether a real diagnoser is wired. When `false`, all diagnose calls no-op to `null`. */
+    isConfigured(): boolean;
+    /**
+     * Diagnose one exception entry, timeout-bounded and fail-safe. Resolves to `null`
+     * when unconfigured or on any failure/timeout — NEVER throws. Concurrent calls for
+     * the same family hash share a single in-flight diagnosis.
+     */
+    diagnose(entry: Entry<ExceptionEntryContent>, options?: DiagnoseOptions): Promise<Diagnosis | null>;
+    /**
+     * Diagnose and render the result as markdown for the MCP `diagnose_exception`
+     * tool. Returns `null` when unconfigured or on failure, so the tool degrades to
+     * its "not configured / no result" message.
+     */
+    diagnoseMarkdown(entry: Entry<ExceptionEntryContent>, options?: DiagnoseOptions): Promise<string | null>;
+    /**
+     * Diagnose and project to a compact {@link DiagnosisSummary} for the alerter to
+     * attach to an alert payload. Returns `null` when unconfigured or on failure, so
+     * the alert simply omits the "Probable cause (AI)" section.
+     */
+    diagnoseSummary(entry: Entry<ExceptionEntryContent>, options?: DiagnoseOptions): Promise<DiagnosisSummary | null>;
+    /** Run one diagnosis under the timeout, swallowing every failure to `null`. */
+    private run;
+    /**
+     * Race `promise` against the configured timeout. On timeout resolves `null`; a
+     * late rejection of the underlying promise is swallowed so it never surfaces as
+     * an unhandled rejection after the timer has already won.
+     */
+    private withTimeout;
+}
+/**
+ * Render a {@link Diagnosis} as compact markdown for the MCP tool. Kept small and
+ * agent-facing: a heading, a confidence/model line, the probable cause, and the
+ * suggested fix.
+ */
+export declare function formatDiagnosisMarkdown(diagnosis: Diagnosis): string;
+export { DEFAULT_TIMEOUT_MS };
+//# sourceMappingURL=diagnosis_coordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnosis_coordinator.d.ts","sourceRoot":"","sources":["../../../src/ai/diagnosis_coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;;GAMG;AACH,QAAA,MAAM,kBAAkB,OAAQ,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CACN,KAAK,EAAE,KAAK,CAAC,qBAAqB,CAAC,EACnC,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,SAAS,EAAE,aAAa,GAAG,IAAI,CAAC;IAChC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;gBAE7D,OAAO,EAAE,2BAA2B;IAMhD,2FAA2F;IAC3F,YAAY,IAAI,OAAO;IAIvB;;;;OAIG;IACG,QAAQ,CACZ,KAAK,EAAE,KAAK,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAoB5B;;;;OAIG;IACG,gBAAgB,CACpB,KAAK,EAAE,KAAK,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKzB;;;;OAIG;IACG,eAAe,CACnB,KAAK,EAAE,KAAK,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAWnC,+EAA+E;YACjE,GAAG;IAajB;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAcpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAcpE;AAMD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/src/ai/diagnosis_coordinator.js

@@ -0,0 +1,143 @@
+/**
+ * Default per-diagnosis wall-clock budget the coordinator enforces (ms). The
+ * on-demand MCP call and the alert path both wait AT MOST this long for a model
+ * response; a slower diagnosis loses the race and the caller proceeds without it
+ * (the underlying call keeps running and its result still lands in the cache for
+ * the next reader).
+ */
+const DEFAULT_TIMEOUT_MS = 8_000;
+/**
+ * Central AI-diagnosis coordinator — the single seam the MCP `diagnose_exception`
+ * tool and the alerter's `new-exception` path both call. It owns the resolved
+ * diagnoser and adds three safety properties on top of it:
+ *
+ *  - **Optional / lazy**: constructed with `diagnoser: null` when the host has not
+ *    configured AI, in which case it is a pure no-op ({@link isConfigured} is
+ *    `false` and diagnose calls return `null`). Nothing imports the LLM SDK through
+ *    it — the provider supplies the concrete diagnoser.
+ *  - **De-duped**: concurrent diagnose calls for the SAME exception family share one
+ *    in-flight promise, so two simultaneous callers (an MCP request and an alert)
+ *    never trigger two model calls. Completed diagnoses are additionally cached by
+ *    the underlying diagnoser (by family hash).
+ *  - **Fail-safe**: a per-call timeout bounds the wait, and ANY diagnoser failure
+ *    (rejection or timeout) resolves to `null` and is logged — it NEVER throws into
+ *    the host's MCP transport or alert flush path.
+ */
+export class DiagnosisCoordinator {
+    diagnoser;
+    timeoutMs;
+    logger;
+    /** In-flight diagnoses keyed by family hash, so concurrent callers coalesce. */
+    inFlight = new Map();
+    constructor(options) {
+        this.diagnoser = options.diagnoser;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.logger = options.logger ?? ((message) => console.warn(message));
+    }
+    /** Whether a real diagnoser is wired. When `false`, all diagnose calls no-op to `null`. */
+    isConfigured() {
+        return this.diagnoser !== null;
+    }
+    /**
+     * Diagnose one exception entry, timeout-bounded and fail-safe. Resolves to `null`
+     * when unconfigured or on any failure/timeout — NEVER throws. Concurrent calls for
+     * the same family hash share a single in-flight diagnosis.
+     */
+    async diagnose(entry, options = {}) {
+        const diagnoser = this.diagnoser;
+        if (diagnoser === null)
+            return null;
+        const familyHash = entry.familyHash;
+        if (familyHash !== null) {
+            const existing = this.inFlight.get(familyHash);
+            if (existing !== undefined)
+                return existing;
+        }
+        const task = this.run(diagnoser, entry, options);
+        if (familyHash !== null) {
+            this.inFlight.set(familyHash, task);
+            void task.finally(() => {
+                this.inFlight.delete(familyHash);
+            });
+        }
+        return task;
+    }
+    /**
+     * Diagnose and render the result as markdown for the MCP `diagnose_exception`
+     * tool. Returns `null` when unconfigured or on failure, so the tool degrades to
+     * its "not configured / no result" message.
+     */
+    async diagnoseMarkdown(entry, options = {}) {
+        const diagnosis = await this.diagnose(entry, options);
+        return diagnosis === null ? null : formatDiagnosisMarkdown(diagnosis);
+    }
+    /**
+     * Diagnose and project to a compact {@link DiagnosisSummary} for the alerter to
+     * attach to an alert payload. Returns `null` when unconfigured or on failure, so
+     * the alert simply omits the "Probable cause (AI)" section.
+     */
+    async diagnoseSummary(entry, options = {}) {
+        const diagnosis = await this.diagnose(entry, options);
+        if (diagnosis === null)
+            return null;
+        return {
+            cause: diagnosis.cause,
+            fix: diagnosis.fix,
+            confidence: diagnosis.confidence,
+            model: diagnosis.model,
+        };
+    }
+    /** Run one diagnosis under the timeout, swallowing every failure to `null`. */
+    async run(diagnoser, entry, options) {
+        try {
+            return await this.withTimeout(diagnoser.diagnose(entry, options));
+        }
+        catch (error) {
+            this.logger(`Telescope AI: diagnosis coordinator swallowed a failure: ${asMessage(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Race `promise` against the configured timeout. On timeout resolves `null`; a
+     * late rejection of the underlying promise is swallowed so it never surfaces as
+     * an unhandled rejection after the timer has already won.
+     */
+    withTimeout(promise) {
+        if (!(this.timeoutMs > 0))
+            return promise;
+        // Attach a no-op catch so a rejection that lands AFTER the timeout wins the
+        // race can't become an unhandled rejection. The race still observes the
+        // original promise, so a rejection BEFORE the timeout still propagates to `run`.
+        promise.catch(() => undefined);
+        return Promise.race([
+            promise,
+            new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(null), this.timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+    }
+}
+/**
+ * Render a {@link Diagnosis} as compact markdown for the MCP tool. Kept small and
+ * agent-facing: a heading, a confidence/model line, the probable cause, and the
+ * suggested fix.
+ */
+export function formatDiagnosisMarkdown(diagnosis) {
+    return [
+        '## Probable cause (AI diagnosis)',
+        '',
+        `**Confidence:** ${diagnosis.confidence} · **Model:** ${diagnosis.model}${diagnosis.cached ? ' · cached' : ''}`,
+        '',
+        diagnosis.cause.trim() !== '' ? diagnosis.cause : '(no cause returned)',
+        '',
+        '### Suggested fix',
+        '',
+        diagnosis.fix.trim() !== '' ? diagnosis.fix : '(no fix returned)',
+    ].join('\n');
+}
+function asMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export { DEFAULT_TIMEOUT_MS };
+//# sourceMappingURL=diagnosis_coordinator.js.map

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

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

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

@@ -1,12 +1,15 @@
 import type { ResolvedTelescopeAiConfig } from './define_config.js';
-import type { DiagnosisStore } from './diagnosis_cache.js';
+import { type DiagnosisStore } from './diagnosis_cache.js';
 import { TelescopeAiDiagnoser } from './telescope_ai_diagnoser.js';
 /**
- * Build a {@link TelescopeAiDiagnoser} from a resolved config, constructing the
- * real Anthropic SDK client from `config.apiKey`. Returns `null` when AI is
- * disabled or no key resolved — so the provider can wire a no-op without callers
+ * Build a {@link TelescopeAiDiagnoser} from a resolved config. Uses the
+ * host-supplied `config.client` verbatim when present (so a host can wire its own
+ * provider); otherwise constructs the real Anthropic SDK client from
+ * `config.apiKey`. Returns `null` when AI is disabled or neither a client nor a key
+ * resolved — so the provider can wire a no-op coordinator without callers
  * branching. A custom `cache` (e.g. Redis-backed) can be supplied for
- * cross-process diagnosis sharing.
+ * cross-process diagnosis sharing; otherwise an in-memory cache honouring
+ * `config.cacheTtlMs` is used.
  */
 export declare function createDiagnoser(config: ResolvedTelescopeAiConfig, options?: {
     cache?: DiagnosisStore;

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/ai/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAgC,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEjG;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,yBAAyB,EACjC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC3E,oBAAoB,GAAG,IAAI,CAc7B"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/ai/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAgC,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEjG;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,yBAAyB,EACjC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC3E,oBAAoB,GAAG,IAAI,CAuB7B"}

package/dist/src/ai/factory.js

@@ -1,23 +1,35 @@
 import Anthropic from '@anthropic-ai/sdk';
+import { DiagnosisCache } from './diagnosis_cache.js';
 import { TelescopeAiDiagnoser } from './telescope_ai_diagnoser.js';
 /**
- * Build a {@link TelescopeAiDiagnoser} from a resolved config, constructing the
- * real Anthropic SDK client from `config.apiKey`. Returns `null` when AI is
- * disabled or no key resolved — so the provider can wire a no-op without callers
+ * Build a {@link TelescopeAiDiagnoser} from a resolved config. Uses the
+ * host-supplied `config.client` verbatim when present (so a host can wire its own
+ * provider); otherwise constructs the real Anthropic SDK client from
+ * `config.apiKey`. Returns `null` when AI is disabled or neither a client nor a key
+ * resolved — so the provider can wire a no-op coordinator without callers
  * branching. A custom `cache` (e.g. Redis-backed) can be supplied for
- * cross-process diagnosis sharing.
+ * cross-process diagnosis sharing; otherwise an in-memory cache honouring
+ * `config.cacheTtlMs` is used.
  */
 export function createDiagnoser(config, options = {}) {
-    if (!config.enabled || config.apiKey === null)
+    if (!config.enabled)
         return null;
-    // The SDK's `Anthropic` instance satisfies the structural client contract.
-    const client = new Anthropic({ apiKey: config.apiKey });
+    // Prefer the host-supplied provider; else build the SDK client from the key.
+    let client = config.client;
+    if (client === null) {
+        if (config.apiKey === null)
+            return null;
+        // The SDK's `Anthropic` instance satisfies the structural client contract.
+        client = new Anthropic({ apiKey: config.apiKey });
+    }
+    const cache = options.cache ??
+        (config.cacheTtlMs !== null ? new DiagnosisCache({ ttlMs: config.cacheTtlMs }) : undefined);
     return new TelescopeAiDiagnoser({
         client,
         model: config.model,
         maxTokens: config.maxTokens,
         enabled: true,
-        ...(options.cache !== undefined ? { cache: options.cache } : {}),
+        ...(cache !== undefined ? { cache } : {}),
         ...(options.logger !== undefined ? { logger: options.logger } : {}),
     });
 }

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

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/ai/factory.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAG1C,OAAO,EAAgC,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEjG;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAiC,EACjC,UAA0E,EAAE;IAE5E,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE3D,2EAA2E;IAC3E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAuC,CAAC;IAE9F,OAAO,IAAI,oBAAoB,CAAC;QAC9B,MAAM;QACN,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/ai/factory.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAuB,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAgC,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEjG;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAiC,EACjC,UAA0E,EAAE;IAE5E,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAEjC,6EAA6E;IAC7E,IAAI,MAAM,GAAmC,MAAM,CAAC,MAAM,CAAC;IAC3D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACxC,2EAA2E;QAC3E,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAuC,CAAC;IAC1F,CAAC;IAED,MAAM,KAAK,GACT,OAAO,CAAC,KAAK;QACb,CAAC,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAE9F,OAAO,IAAI,oBAAoB,CAAC;QAC9B,MAAM;QACN,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC,CAAC;AACL,CAAC"}

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

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";
 export { TelescopeAiDiagnoser } from './telescope_ai_diagnoser.js';
 export type { AnthropicMessagesClient, DiagnoseOptions, TelescopeAiDiagnoserOptions, } from './telescope_ai_diagnoser.js';
 export { normalizeConfidence, parseDiagnosis } from './diagnoser.js';
@@ -9,6 +9,8 @@ export type { DiagnosisStore } from './diagnosis_cache.js';
 export { buildUserPrompt, STACK_FRAME_LIMIT, SYSTEM_PROMPT } from './prompt.js';
 export type { RelatedEntrySummary } from './prompt.js';
 export { createDiagnoser } from './factory.js';
+export { DEFAULT_TIMEOUT_MS, DiagnosisCoordinator, formatDiagnosisMarkdown, } from './diagnosis_coordinator.js';
+export type { DiagnoserLike, DiagnosisCoordinatorOptions, DiagnosisSummary, } from './diagnosis_coordinator.js';
 export { DEFAULT_MAX_TOKENS, DEFAULT_MODEL, defineConfig, resolveConfig, } from './define_config.js';
 export type { ResolvedTelescopeAiConfig, TelescopeAiConfig, } from './define_config.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5F,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5F,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,aAAa,EACb,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/src/ai/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.0';
 // — diagnoser —
 export { TelescopeAiDiagnoser } from './telescope_ai_diagnoser.js';
 // — diagnosis model + parsing —
@@ -10,6 +10,8 @@ export { DEFAULT_DIAGNOSIS_CACHE_MAX, DEFAULT_DIAGNOSIS_TTL_MS, DiagnosisCache,
 export { buildUserPrompt, STACK_FRAME_LIMIT, SYSTEM_PROMPT } from './prompt.js';
 // — factory (constructs the real Anthropic client) —
 export { createDiagnoser } from './factory.js';
+// — diagnosis coordinator (wires MCP + alerter) —
+export { DEFAULT_TIMEOUT_MS, DiagnosisCoordinator, formatDiagnosisMarkdown, } from './diagnosis_coordinator.js';
 // — config —
 export { DEFAULT_MAX_TOKENS, DEFAULT_MODEL, defineConfig, resolveConfig, } from './define_config.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,gBAAgB;AAChB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOnE,gCAAgC;AAChC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrE,YAAY;AACZ,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAG9B,aAAa;AACb,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGhF,qDAAqD;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,aAAa;AACb,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,gBAAgB;AAChB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOnE,gCAAgC;AAChC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrE,YAAY;AACZ,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAG9B,aAAa;AACb,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGhF,qDAAqD;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,kDAAkD;AAClD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAOpC,aAAa;AACb,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC"}

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

@@ -1,16 +1,29 @@
 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:
+ * A single alerting rule. Ported (trimmed) from the aviary telescope core.
  *
- * - `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`.
+ * Two families of rules, evaluated by two complementary services:
+ *
+ * - `new-exception` / `exception-rate` — the exception-driven rules the
+ *   {@link Alerter} evaluates over a freshly-polled batch of exception entries
+ *   (fed by the {@link ExceptionPoller}). They fire-and-cooldown; they do NOT
+ *   auto-resolve.
+ *     - `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 elapses.
+ *                        Dedup is per-process via {@link NewExceptionTracker}.
+ *     - `exception-rate` fires when `>= threshold` exception entries were recorded
+ *                        in the trailing `window`.
+ *
+ * - `metric-threshold` — the stateful rule the {@link AlerterService} evaluates on
+ *   an interval over a trailing `window`, reusing the SAME windowed aggregation
+ *   the dashboard shows (`summarizeStats`/`percentile` via `MetricsService`), so
+ *   an alert means exactly what the metrics view shows. It RAISES when the
+ *   computed metric first crosses `threshold` in the `comparator` direction and
+ *   AUTO-RESOLVES when it clears — with dedup (no duplicate raise while active)
+ *   and a post-resolve cooldown for flap control. Use it to page on
+ *   "request p99 > 800ms" (a slow endpoint), "cache hit-rate < 0.8", or an
+ *   exception spike (`exception-count >= N`).
  */
 export type AlertRule = {
     type: 'new-exception';
@@ -19,7 +32,31 @@ export type AlertRule = {
     type: 'exception-rate';
     window: string;
     threshold: number;
+} | {
+    type: 'metric-threshold';
+    /** The computed metric to evaluate (see {@link AlertMetric}). */
+    metric: AlertMetric;
+    /** Trailing window to aggregate over (e.g. `'5m'`). */
+    window: string;
+    /** `gte` fires when value >= threshold; `lte` when value <= threshold. */
+    comparator: 'gte' | 'lte';
+    /** The threshold the metric is compared against. */
+    threshold: number;
+    /**
+     * Minimum samples in the window before a percentile/ratio rule can fire —
+     * guards a p99 page against a single slow request on a quiet host. Default
+     * 1. Ignored for `exception-count` (a count of 0 is a meaningful value that
+     * must be able to auto-resolve a firing spike).
+     */
+    minSamples?: number;
 };
+/**
+ * The metrics a `metric-threshold` rule can evaluate. Each is derived from the
+ * SAME windowed aggregation the stats view uses (`summarizeStats`), so an alert
+ * means exactly what the dashboard shows. Latency metrics are in ms;
+ * `cache-hit-rate` is a ratio in [0, 1]; `exception-count` is a raw count.
+ */
+export type AlertMetric = 'request-p95-ms' | 'request-p99-ms' | 'query-p95-ms' | 'query-p99-ms' | 'cache-hit-rate' | 'exception-count';
 /**
  * Rich exception context attached to a `new-exception` alert. Pulled from the
  * exception {@link Entry} that fired the rule. Absent on rate-rule alerts.
@@ -46,6 +83,22 @@ export interface ExceptionAlertContext {
     /** Exception entry id (for the dashboard deep link). */
     entryId: string;
 }
+/**
+ * A compact AI probable-cause summary optionally attached to a `new-exception`
+ * alert by the {@link Alerter} when a diagnosis coordinator is configured. Kept
+ * structural (no dependency on the `ai` subpath) so alerting stays independent of
+ * whether AI is installed. Absent when AI is off or a diagnosis wasn't ready.
+ */
+export interface AlertDiagnosis {
+    /** Likely root cause — what failed and why. */
+    cause: string;
+    /** A concrete, actionable suggested fix. */
+    fix: string;
+    /** The model's confidence (`high` / `medium` / `low`). */
+    confidence: string;
+    /** The model id that produced the diagnosis. */
+    model: string;
+}
 /**
  * The shape delivered to every {@link AlertChannel} when a rule fires.
  */
@@ -59,8 +112,23 @@ export interface AlertPayload {
     firedAt: string;
     /** The reporting instance identifier. */
     instanceId: string;
-    /** Rich context for `new-exception` alerts; absent for rate rules. */
+    /**
+     * Whether this notification RAISES an alert or RESOLVES a previously-raised one.
+     * Present on stateful `metric-threshold` alerts; absent (⇒ `'firing'`) on the
+     * fire-and-cooldown exception rules, which carry no resolve signal.
+     */
+    status?: 'firing' | 'resolved';
+    /** The evaluated metric — present on `metric-threshold` alerts. */
+    metric?: AlertMetric;
+    /** Rich context for `new-exception` alerts; absent for rate/metric rules. */
     exception?: ExceptionAlertContext;
+    /**
+     * AI probable-cause analysis, attached to a `new-exception` alert when a
+     * diagnosis coordinator is configured and produced a result within the grace
+     * window. Absent when AI is off or no diagnosis was ready. Channels render it as
+     * a "Probable cause (AI)" section; the raw webhook payload carries it verbatim.
+     */
+    diagnosis?: AlertDiagnosis;
     /** External dashboard URL when configured (lets channels build deep links). */
     dashboardUrl?: string;
 }

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

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

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

@@ -1,5 +1,5 @@
 import type { Entry } from '../entry.js';
-import type { ResolvedAlerts } from './alert_rule.js';
+import type { AlertDiagnosis, ResolvedAlerts } from './alert_rule.js';
 export interface AlerterDeps {
     alerts: ResolvedAlerts;
     /** Wall-clock seam (ms). Defaults to `Date.now`. */
@@ -8,6 +8,14 @@ export interface AlerterDeps {
     maxFamilies?: number;
     /** Failure log sink. Defaults to `console.warn`. */
     logger?: (message: string) => void;
+    /**
+     * Optional AI probable-cause hook. When present, a `new-exception` alert awaits
+     * it (fail-safe / time-bounded by the caller — usually the diagnosis
+     * coordinator) and attaches the result to the payload's `diagnosis` field. Omit
+     * (the default) and alerts behave exactly as before, with no AI section. Must
+     * never throw; the alerter additionally guards it.
+     */
+    diagnose?: (entry: Entry) => Promise<AlertDiagnosis | null>;
 }
 /**
  * Wires a source of exception {@link Entry} objects → rule evaluation → channels.
@@ -54,6 +62,8 @@ export declare class Alerter {
     /** Number of error families currently tracked (test/observability seam). */
     get trackedFamilies(): number;
     private evaluateNewException;
+    /** Run the optional diagnose hook, swallowing any failure to `null`. */
+    private safeDiagnose;
     private evaluateExceptionRate;
     /** Find a configured rule of `type` with its array index, or `null`. */
     private findRule;

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

@@ -1 +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"}
+{"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,EACV,cAAc,EAId,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;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC7D;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;IA+BlC,wEAAwE;YAC1D,YAAY;YAWZ,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"}

package/dist/src/alerts/alerter.js

@@ -97,7 +97,27 @@ export class Alerter {
                 continue;
             this.lastFiredFamily.set(entry.familyHash, nowMs);
             const occurrences = occurrencesByFamily.get(entry.familyHash) ?? 1;
-            await this.dispatch(this.buildNewExceptionPayload(result.rule, entry, occurrences, nowMs));
+            const payload = this.buildNewExceptionPayload(result.rule, entry, occurrences, nowMs);
+            // Optionally enrich with an AI probable-cause section when a diagnose hook is
+            // wired. The hook is expected to be fail-safe/time-bounded (the coordinator
+            // is); we guard it anyway so a diagnosis failure never blocks the alert.
+            const diagnosis = await this.safeDiagnose(entry);
+            if (diagnosis !== null)
+                payload.diagnosis = diagnosis;
+            await this.dispatch(payload);
+        }
+    }
+    /** Run the optional diagnose hook, swallowing any failure to `null`. */
+    async safeDiagnose(entry) {
+        const diagnose = this.deps.diagnose;
+        if (diagnose === undefined)
+            return null;
+        try {
+            return await diagnose(entry);
+        }
+        catch (error) {
+            this.logger(`Telescope alert diagnosis failed: ${asMessage(error)}`);
+            return null;
         }
     }
     async evaluateExceptionRate(nowMs) {