@runcore-sh/runcore 0.1.2

package/dist/health/alerting.js

@@ -0,0 +1,373 @@
+/**
+ * Threshold-based alerting system for Core health monitoring.
+ *
+ * Evaluates health check results against configured thresholds, manages
+ * alert lifecycle (firing → acknowledged → resolved), dispatches
+ * notifications, and maintains alert history.
+ *
+ * Integrates with HealthChecker via its public API — no modifications
+ * to the core checker are needed.
+ */
+import { creditsExtractor } from "./checks/openrouter.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("health.alerting");
+// ─── Default configuration ─────────────────────────────────────────────────
+const DEFAULT_EVALUATION_INTERVAL_MS = 30_000;
+const DEFAULT_MAX_HISTORY = 100;
+const DEFAULT_NOTIFICATION_COOLDOWN_MS = 300_000; // 5 minutes
+// ─── Built-in metric extractors ─────────────────────────────────────────────
+/** Parse metrics from the built-in memory check detail string. */
+function memoryExtractor(detail) {
+    const metrics = {};
+    const heapMatch = detail.match(/heap\s+(\d+)MB/i);
+    const rssMatch = detail.match(/rss\s+(\d+)MB/i);
+    if (heapMatch)
+        metrics["heap"] = parseInt(heapMatch[1], 10);
+    if (rssMatch)
+        metrics["rss"] = parseInt(rssMatch[1], 10);
+    return metrics;
+}
+/** Parse metrics from the event loop check detail string. */
+function eventLoopExtractor(detail) {
+    const match = detail.match(/drift\s+(\d+)ms/i);
+    return match ? { drift: parseInt(match[1], 10) } : {};
+}
+/** Parse utilization percentage from agent capacity check. */
+function utilizationExtractor(detail) {
+    const match = detail.match(/(\d+)%/);
+    return match ? { utilization: parseInt(match[1], 10) } : {};
+}
+/** Parse failure count from sync check. */
+function failureCountExtractor(detail) {
+    const match = detail.match(/failures:\s*(\d+)/i);
+    return match ? { failures: parseInt(match[1], 10) } : {};
+}
+/** Parse CPU percentage from cpu check. */
+function cpuExtractor(detail) {
+    const match = detail.match(/cpu\s+(\d+)%/i);
+    return match ? { usage: parseInt(match[1], 10) } : {};
+}
+/** Parse disk usage percentage and free MB from disk usage check. */
+function diskUsageExtractor(detail) {
+    const metrics = {};
+    const usedMatch = detail.match(/disk\s+(\d+)%/i);
+    const freeMatch = detail.match(/(\d+)MB\s+free/i);
+    if (usedMatch)
+        metrics["used"] = parseInt(usedMatch[1], 10);
+    if (freeMatch)
+        metrics["freeMB"] = parseInt(freeMatch[1], 10);
+    return metrics;
+}
+/** Built-in extractors for known check types. */
+const BUILT_IN_EXTRACTORS = {
+    memory: memoryExtractor,
+    event_loop: eventLoopExtractor,
+    agent_capacity: utilizationExtractor,
+    sync: failureCountExtractor,
+    cpu: cpuExtractor,
+    disk_usage: diskUsageExtractor,
+    openrouter_credits: creditsExtractor,
+};
+// ─── AlertManager ───────────────────────────────────────────────────────────
+export class AlertManager {
+    checker;
+    dispatcher;
+    config;
+    extractors = new Map();
+    activeAlerts = new Map();
+    history = [];
+    breachCounts = new Map();
+    lastNotified = new Map();
+    timer = null;
+    lastEvaluation = null;
+    idCounter = 0;
+    constructor(checker, config, dispatcher) {
+        this.checker = checker;
+        this.dispatcher = dispatcher ?? null;
+        this.config = {
+            enabled: config.enabled,
+            evaluationIntervalMs: config.evaluationIntervalMs ?? DEFAULT_EVALUATION_INTERVAL_MS,
+            maxHistorySize: config.maxHistorySize ?? DEFAULT_MAX_HISTORY,
+            notificationCooldownMs: config.notificationCooldownMs ?? DEFAULT_NOTIFICATION_COOLDOWN_MS,
+            thresholds: config.thresholds,
+            notifications: config.notifications,
+        };
+        // Register built-in extractors for known check names
+        for (const [name, extractor] of Object.entries(BUILT_IN_EXTRACTORS)) {
+            this.extractors.set(name, extractor);
+        }
+    }
+    // ─── Metric extractors ─────────────────────────────────────────────────
+    /** Register a custom metric extractor for a check name. */
+    registerExtractor(checkName, extractor) {
+        this.extractors.set(checkName, extractor);
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────────
+    /** Start the alerting evaluation loop. */
+    start() {
+        if (!this.config.enabled || this.timer)
+            return;
+        log.info("alerting evaluation loop started", { intervalMs: this.config.evaluationIntervalMs });
+        this.timer = setInterval(() => this.evaluate(), this.config.evaluationIntervalMs);
+    }
+    /** Stop the alerting evaluation loop. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            log.info("alerting evaluation loop stopped");
+        }
+    }
+    /** Run a single evaluation cycle. Returns IDs of newly fired or resolved alerts. */
+    async evaluate() {
+        const fired = [];
+        const resolved = [];
+        let healthResult;
+        try {
+            healthResult = await this.checker.check();
+        }
+        catch (err) {
+            log.error("alert evaluation failed — health check threw", { error: String(err) });
+            return { fired, resolved };
+        }
+        this.lastEvaluation = new Date().toISOString();
+        // Track which thresholds are still breaching
+        const activeThresholdIds = new Set();
+        for (const threshold of this.config.thresholds) {
+            const thresholdId = `${threshold.checkName}:${threshold.metric}`;
+            const checkResult = healthResult.checks[threshold.checkName];
+            if (!checkResult?.detail) {
+                // Check not found or no detail — clear breach count
+                this.breachCounts.set(thresholdId, 0);
+                continue;
+            }
+            // Extract metric value
+            const extractor = this.extractors.get(threshold.checkName);
+            if (!extractor)
+                continue;
+            const metrics = extractor(checkResult.detail);
+            const value = metrics[threshold.metric];
+            if (value === undefined)
+                continue;
+            // Determine severity
+            let severity = null;
+            let breachedThreshold = 0;
+            if (value >= threshold.criticalThreshold) {
+                severity = "critical";
+                breachedThreshold = threshold.criticalThreshold;
+            }
+            else if (value >= threshold.warningThreshold) {
+                severity = "warning";
+                breachedThreshold = threshold.warningThreshold;
+            }
+            if (severity) {
+                const requiredBreaches = threshold.consecutiveBreaches ?? 1;
+                const count = (this.breachCounts.get(thresholdId) ?? 0) + 1;
+                this.breachCounts.set(thresholdId, count);
+                if (count >= requiredBreaches) {
+                    activeThresholdIds.add(thresholdId);
+                    const existing = this.activeAlerts.get(thresholdId);
+                    if (existing) {
+                        // Update severity if it escalated
+                        if (severity === "critical" &&
+                            existing.severity === "warning") {
+                            existing.severity = "critical";
+                            existing.value = value;
+                            existing.threshold = breachedThreshold;
+                            existing.message = this.formatMessage(threshold, severity, value, breachedThreshold);
+                            this.notifyIfAllowed(existing);
+                        }
+                    }
+                    else {
+                        // New alert
+                        const alert = this.createAlert(thresholdId, threshold, severity, value, breachedThreshold);
+                        this.activeAlerts.set(thresholdId, alert);
+                        fired.push(alert.id);
+                        log.info("alert fired", {
+                            alertId: alert.id,
+                            thresholdId,
+                            severity,
+                            metric: threshold.metric,
+                            value,
+                            threshold: breachedThreshold,
+                        });
+                        this.notifyIfAllowed(alert);
+                    }
+                }
+            }
+            else {
+                // Value is below thresholds — clear breach count
+                this.breachCounts.set(thresholdId, 0);
+            }
+        }
+        // Resolve alerts whose thresholds are no longer breaching
+        for (const [thresholdId, alert] of this.activeAlerts) {
+            if (!activeThresholdIds.has(thresholdId) && alert.state !== "resolved") {
+                alert.state = "resolved";
+                alert.resolvedAt = new Date().toISOString();
+                resolved.push(alert.id);
+                log.info("alert resolved", { alertId: alert.id, thresholdId, checkName: alert.checkName });
+                this.addToHistory(alert);
+                this.activeAlerts.delete(thresholdId);
+                this.lastNotified.delete(thresholdId);
+                this.notifyResolved(alert);
+            }
+        }
+        return { fired, resolved };
+    }
+    // ─── Alert acknowledgment ──────────────────────────────────────────────
+    /** Acknowledge an active alert. Returns true if the alert was found and acknowledged. */
+    acknowledge(alertId, by) {
+        for (const alert of this.activeAlerts.values()) {
+            if (alert.id === alertId && alert.state === "firing") {
+                alert.state = "acknowledged";
+                alert.acknowledgedAt = new Date().toISOString();
+                alert.acknowledgedBy = by;
+                log.info("alert acknowledged", { alertId, by });
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Manually resolve an active alert. */
+    resolve(alertId) {
+        for (const [thresholdId, alert] of this.activeAlerts) {
+            if (alert.id === alertId) {
+                alert.state = "resolved";
+                alert.resolvedAt = new Date().toISOString();
+                this.addToHistory(alert);
+                this.activeAlerts.delete(thresholdId);
+                this.lastNotified.delete(thresholdId);
+                return true;
+            }
+        }
+        return false;
+    }
+    // ─── Query ──────────────────────────────────────────────────────────────
+    /** Get all active alerts (firing + acknowledged). */
+    getActive() {
+        return [...this.activeAlerts.values()];
+    }
+    /** Get alert history (resolved alerts, most recent first). */
+    getHistory() {
+        return [...this.history];
+    }
+    /** Get a single alert by ID (active or historical). */
+    getAlert(id) {
+        for (const alert of this.activeAlerts.values()) {
+            if (alert.id === id)
+                return alert;
+        }
+        return this.history.find((a) => a.id === id);
+    }
+    /** Get dashboard summary. */
+    getSummary() {
+        const firing = [];
+        const acknowledged = [];
+        const bySeverity = {
+            warning: 0,
+            critical: 0,
+        };
+        for (const alert of this.activeAlerts.values()) {
+            bySeverity[alert.severity]++;
+            if (alert.state === "firing")
+                firing.push(alert);
+            else if (alert.state === "acknowledged")
+                acknowledged.push(alert);
+        }
+        return {
+            activeCount: this.activeAlerts.size,
+            bySeverity,
+            firing,
+            acknowledged,
+            recentlyResolved: this.history.slice(0, 10),
+            lastEvaluation: this.lastEvaluation,
+        };
+    }
+    /** Get the current configuration (read-only snapshot). */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─── Configuration updates ──────────────────────────────────────────────
+    /** Update thresholds at runtime. */
+    updateThresholds(thresholds) {
+        this.config.thresholds = thresholds;
+    }
+    /** Update notification preferences at runtime. */
+    updateNotifications(notifications) {
+        this.config.notifications = notifications;
+    }
+    /** Enable or disable the alerting system. */
+    setEnabled(enabled) {
+        this.config.enabled = enabled;
+        if (!enabled)
+            this.stop();
+    }
+    // ─── Private helpers ────────────────────────────────────────────────────
+    createAlert(thresholdId, threshold, severity, value, breachedThreshold) {
+        return {
+            id: `alert_${Date.now()}_${++this.idCounter}`,
+            thresholdId,
+            checkName: threshold.checkName,
+            metric: threshold.metric,
+            severity,
+            state: "firing",
+            value,
+            threshold: breachedThreshold,
+            message: this.formatMessage(threshold, severity, value, breachedThreshold),
+            firedAt: new Date().toISOString(),
+        };
+    }
+    formatMessage(threshold, severity, value, breachedThreshold) {
+        const label = threshold.label ?? `${threshold.checkName}/${threshold.metric}`;
+        return `${label} is ${value} (${severity} threshold: ${breachedThreshold})`;
+    }
+    addToHistory(alert) {
+        this.history.unshift({ ...alert });
+        if (this.history.length > this.config.maxHistorySize) {
+            this.history.length = this.config.maxHistorySize;
+        }
+    }
+    notifyIfAllowed(alert) {
+        if (!this.dispatcher)
+            return;
+        const thresholdId = alert.thresholdId;
+        const lastTime = this.lastNotified.get(thresholdId) ?? 0;
+        const now = Date.now();
+        if (now - lastTime < this.config.notificationCooldownMs)
+            return;
+        this.lastNotified.set(thresholdId, now);
+        this.dispatchToChannels(alert);
+    }
+    notifyResolved(alert) {
+        if (!this.dispatcher)
+            return;
+        this.dispatchToChannels(alert);
+    }
+    dispatchToChannels(alert) {
+        if (!this.dispatcher)
+            return;
+        for (const pref of this.config.notifications) {
+            // Check severity filter
+            if (!this.meetsMinSeverity(alert.severity, pref.minSeverity))
+                continue;
+            // Check name filter
+            if (pref.checkFilter &&
+                pref.checkFilter.length > 0 &&
+                !pref.checkFilter.includes(alert.checkName)) {
+                continue;
+            }
+            // Fire and forget
+            log.debug("dispatching alert to channel", { alertId: alert.id, channel: pref.channel, state: alert.state });
+            this.dispatcher.sendTo(pref.channel, alert);
+        }
+    }
+    meetsMinSeverity(actual, minimum) {
+        const levels = {
+            warning: 0,
+            critical: 1,
+        };
+        return levels[actual] >= levels[minimum];
+    }
+}
+//# sourceMappingURL=alerting.js.map

package/dist/health/alerting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerting.js","sourceRoot":"","sources":["../../src/health/alerting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,GAAG,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC;AAE5C,8EAA8E;AAE9E,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAC9C,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,gCAAgC,GAAG,OAAO,CAAC,CAAC,YAAY;AAE9D,+EAA+E;AAE/E,kEAAkE;AAClE,SAAS,eAAe,CAAC,MAAc;IACrC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChD,IAAI,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5D,IAAI,QAAQ;QAAE,OAAO,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,6DAA6D;AAC7D,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,8DAA8D;AAC9D,SAAS,oBAAoB,CAAC,MAAc;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,2CAA2C;AAC3C,SAAS,qBAAqB,CAAC,MAAc;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,2CAA2C;AAC3C,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,qEAAqE;AACrE,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAClD,IAAI,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5D,IAAI,SAAS;QAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iDAAiD;AACjD,MAAM,mBAAmB,GAAoC;IAC3D,MAAM,EAAE,eAAe;IACvB,UAAU,EAAE,kBAAkB;IAC9B,cAAc,EAAE,oBAAoB;IACpC,IAAI,EAAE,qBAAqB;IAC3B,GAAG,EAAE,YAAY;IACjB,UAAU,EAAE,kBAAkB;IAC9B,kBAAkB,EAAE,gBAAgB;CACrC,CAAC;AAEF,+EAA+E;AAE/E,MAAM,OAAO,YAAY;IACf,OAAO,CAAgB;IACvB,UAAU,CAAgC;IAC1C,MAAM,CAAwB;IAE9B,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IAChD,YAAY,GAAG,IAAI,GAAG,EAAiB,CAAC;IACxC,OAAO,GAAY,EAAE,CAAC;IACtB,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,GAA0C,IAAI,CAAC;IACpD,cAAc,GAAkB,IAAI,CAAC;IACrC,SAAS,GAAG,CAAC,CAAC;IAEtB,YACE,OAAsB,EACtB,MAAmB,EACnB,UAAmC;QAEnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,IAAI,IAAI,CAAC;QAErC,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,oBAAoB,EAClB,MAAM,CAAC,oBAAoB,IAAI,8BAA8B;YAC/D,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,mBAAmB;YAC5D,sBAAsB,EACpB,MAAM,CAAC,sBAAsB,IAAI,gCAAgC;YACnE,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,aAAa,EAAE,MAAM,CAAC,aAAa;SACpC,CAAC;QAEF,qDAAqD;QACrD,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACpE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,0EAA0E;IAE1E,2DAA2D;IAC3D,iBAAiB,CAAC,SAAiB,EAAE,SAA0B;QAC7D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED,2EAA2E;IAE3E,0CAA0C;IAC1C,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QAC/C,GAAG,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;QAC/F,IAAI,CAAC,KAAK,GAAG,WAAW,CACtB,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EACrB,IAAI,CAAC,MAAM,CAAC,oBAAoB,CACjC,CAAC;IACJ,CAAC;IAED,yCAAyC;IACzC,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,QAAQ;QACZ,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,IAAI,YAAY,CAAC;QACjB,IAAI,CAAC;YACH,YAAY,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,8CAA8C,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClF,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE/C,6CAA6C;QAC7C,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;QAE7C,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC/C,MAAM,WAAW,GAAG,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;YACjE,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAE7D,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;gBACzB,oDAAoD;gBACpD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;gBACtC,SAAS;YACX,CAAC;YAED,uBAAuB;YACvB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC3D,IAAI,CAAC,SAAS;gBAAE,SAAS;YAEzB,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAElC,qBAAqB;YACrB,IAAI,QAAQ,GAAyB,IAAI,CAAC;YAC1C,IAAI,iBAAiB,GAAG,CAAC,CAAC;YAE1B,IAAI,KAAK,IAAI,SAAS,CAAC,iBAAiB,EAAE,CAAC;gBACzC,QAAQ,GAAG,UAAU,CAAC;gBACtB,iBAAiB,GAAG,SAAS,CAAC,iBAAiB,CAAC;YAClD,CAAC;iBAAM,IAAI,KAAK,IAAI,SAAS,CAAC,gBAAgB,EAAE,CAAC;gBAC/C,QAAQ,GAAG,SAAS,CAAC;gBACrB,iBAAiB,GAAG,SAAS,CAAC,gBAAgB,CAAC;YACjD,CAAC;YAED,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,gBAAgB,GAAG,SAAS,CAAC,mBAAmB,IAAI,CAAC,CAAC;gBAC5D,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC5D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;gBAE1C,IAAI,KAAK,IAAI,gBAAgB,EAAE,CAAC;oBAC9B,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;oBAEpC,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;oBACpD,IAAI,QAAQ,EAAE,CAAC;wBACb,kCAAkC;wBAClC,IACE,QAAQ,KAAK,UAAU;4BACvB,QAAQ,CAAC,QAAQ,KAAK,SAAS,EAC/B,CAAC;4BACD,QAAQ,CAAC,QAAQ,GAAG,UAAU,CAAC;4BAC/B,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;4BACvB,QAAQ,CAAC,SAAS,GAAG,iBAAiB,CAAC;4BACvC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,aAAa,CACnC,SAAS,EACT,QAAQ,EACR,KAAK,EACL,iBAAiB,CAClB,CAAC;4BACF,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;wBACjC,CAAC;oBACH,CAAC;yBAAM,CAAC;wBACN,YAAY;wBACZ,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAC5B,WAAW,EACX,SAAS,EACT,QAAQ,EACR,KAAK,EACL,iBAAiB,CAClB,CAAC;wBACF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;wBAC1C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;wBACrB,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE;4BACtB,OAAO,EAAE,KAAK,CAAC,EAAE;4BACjB,WAAW;4BACX,QAAQ;4BACR,MAAM,EAAE,SAAS,CAAC,MAAM;4BACxB,KAAK;4BACL,SAAS,EAAE,iBAAiB;yBAC7B,CAAC,CAAC;wBACH,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;oBAC9B,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,iDAAiD;gBACjD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACrD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACvE,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC;gBACzB,KAAK,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBAC5C,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACxB,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;gBAC3F,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACzB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBACtC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBACtC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAED,0EAA0E;IAE1E,yFAAyF;IACzF,WAAW,CAAC,OAAe,EAAE,EAAW;QACtC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,IAAI,KAAK,CAAC,EAAE,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACrD,KAAK,CAAC,KAAK,GAAG,cAAc,CAAC;gBAC7B,KAAK,CAAC,cAAc,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBAChD,KAAK,CAAC,cAAc,GAAG,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;gBAChD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wCAAwC;IACxC,OAAO,CAAC,OAAe;QACrB,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACrD,IAAI,KAAK,CAAC,EAAE,KAAK,OAAO,EAAE,CAAC;gBACzB,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC;gBACzB,KAAK,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBAC5C,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACzB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBACtC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBACtC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2EAA2E;IAE3E,qDAAqD;IACrD,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,8DAA8D;IAC9D,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,uDAAuD;IACvD,QAAQ,CAAC,EAAU;QACjB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,6BAA6B;IAC7B,UAAU;QACR,MAAM,MAAM,GAAY,EAAE,CAAC;QAC3B,MAAM,YAAY,GAAY,EAAE,CAAC;QACjC,MAAM,UAAU,GAAkC;YAChD,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,CAAC;SACZ,CAAC;QAEF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;iBAC5C,IAAI,KAAK,CAAC,KAAK,KAAK,cAAc;gBAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpE,CAAC;QAED,OAAO;YACL,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI;YACnC,UAAU;YACV,MAAM;YACN,YAAY;YACZ,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YAC3C,cAAc,EAAE,IAAI,CAAC,cAAc;SACpC,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,2EAA2E;IAE3E,oCAAoC;IACpC,gBAAgB,CAAC,UAA4B;QAC3C,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;IACtC,CAAC;IAED,kDAAkD;IAClD,mBAAmB,CAAC,aAAkC;QACpD,IAAI,CAAC,MAAM,CAAC,aAAa,GAAG,aAAa,CAAC;IAC5C,CAAC;IAED,6CAA6C;IAC7C,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;QAC9B,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,2EAA2E;IAEnE,WAAW,CACjB,WAAmB,EACnB,SAAyB,EACzB,QAAuB,EACvB,KAAa,EACb,iBAAyB;QAEzB,OAAO;YACL,EAAE,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE;YAC7C,WAAW;YACX,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,QAAQ;YACR,KAAK,EAAE,QAAQ;YACf,KAAK;YACL,SAAS,EAAE,iBAAiB;YAC5B,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,CAAC;YAC1E,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAClC,CAAC;IACJ,CAAC;IAEO,aAAa,CACnB,SAAyB,EACzB,QAAuB,EACvB,KAAa,EACb,iBAAyB;QAEzB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QAC9E,OAAO,GAAG,KAAK,OAAO,KAAK,KAAK,QAAQ,eAAe,iBAAiB,GAAG,CAAC;IAC9E,CAAC;IAEO,YAAY,CAAC,KAAY;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QACnD,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,KAAY;QAClC,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAE7B,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,GAAG,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,sBAAsB;YAAE,OAAO;QAEhE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAEO,cAAc,CAAC,KAAY;QACjC,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAEO,kBAAkB,CAAC,KAAY;QACrC,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAE7B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC7C,wBAAwB;YACxB,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;gBAAE,SAAS;YACvE,oBAAoB;YACpB,IACE,IAAI,CAAC,WAAW;gBAChB,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAC3C,CAAC;gBACD,SAAS;YACX,CAAC;YACD,kBAAkB;YAClB,GAAG,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YAC5G,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAEO,gBAAgB,CACtB,MAAqB,EACrB,OAAsB;QAEtB,MAAM,MAAM,GAAkC;YAC5C,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,CAAC;SACZ,CAAC;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/health/checker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Core HealthChecker — runs registered checks with timeouts and history tracking.
+ *
+ * Backward-compatible with the original src/health.ts API while adding:
+ * - Per-check timeouts (prevents a slow check from blocking probes)
+ * - Critical vs non-critical classification
+ * - Cached last-result for dashboard access without re-running
+ * - Timestamp on aggregate results
+ */
+import type { CheckResult, HealthCheckResult, HealthCheckFn, CheckRegistration, RegisterOptions } from "./types.js";
+export declare class HealthChecker {
+    private checks;
+    /** Register a named health check. Overwrites if name already exists. */
+    register(name: string, fn: HealthCheckFn, opts?: RegisterOptions): void;
+    /** Unregister a check by name. */
+    unregister(name: string): void;
+    /** Run all checks (or a single named check) and aggregate results. */
+    check(name?: string): Promise<HealthCheckResult>;
+    /**
+     * Liveness check — only critical checks can make this fail.
+     * Non-critical degraded/unhealthy checks are reported but don't affect the status.
+     */
+    liveness(): Promise<HealthCheckResult>;
+    /** List registered check names. */
+    list(): string[];
+    /** Get the last cached result for a check (without re-running). */
+    getLastResult(name: string): CheckResult | undefined;
+    /** Get registration info for a check. */
+    getRegistration(name: string): CheckRegistration | undefined;
+    private runCheck;
+}
+//# sourceMappingURL=checker.d.ts.map

package/dist/health/checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../src/health/checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAOpB,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAwC;IAEtD,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI;IASvE,kCAAkC;IAClC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,sEAAsE;IAChE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyDtD;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAiB5C,mCAAmC;IACnC,IAAI,IAAI,MAAM,EAAE;IAIhB,mEAAmE;IACnE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIpD,yCAAyC;IACzC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;YAI9C,QAAQ;CAyBvB"}

package/dist/health/checker.js

@@ -0,0 +1,138 @@
+/**
+ * Core HealthChecker — runs registered checks with timeouts and history tracking.
+ *
+ * Backward-compatible with the original src/health.ts API while adding:
+ * - Per-check timeouts (prevents a slow check from blocking probes)
+ * - Critical vs non-critical classification
+ * - Cached last-result for dashboard access without re-running
+ * - Timestamp on aggregate results
+ */
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("health.checker");
+const DEFAULT_TIMEOUT_MS = 5_000;
+export class HealthChecker {
+    checks = new Map();
+    /** Register a named health check. Overwrites if name already exists. */
+    register(name, fn, opts) {
+        log.debug("registering health check", { name, critical: opts?.critical ?? true, timeoutMs: opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS });
+        this.checks.set(name, {
+            fn,
+            critical: opts?.critical ?? true,
+            timeoutMs: opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        });
+    }
+    /** Unregister a check by name. */
+    unregister(name) {
+        this.checks.delete(name);
+    }
+    /** Run all checks (or a single named check) and aggregate results. */
+    async check(name) {
+        const checks = {};
+        if (name) {
+            const reg = this.checks.get(name);
+            if (!reg) {
+                return {
+                    status: "unhealthy",
+                    uptime: Math.round(process.uptime()),
+                    timestamp: new Date().toISOString(),
+                    checks: { [name]: { status: "unhealthy", detail: "check not found" } },
+                };
+            }
+            checks[name] = await this.runCheck(reg);
+        }
+        else {
+            const entries = [...this.checks.entries()];
+            const results = await Promise.allSettled(entries.map(([, reg]) => this.runCheck(reg)));
+            for (let i = 0; i < entries.length; i++) {
+                const [checkName] = entries[i];
+                const result = results[i];
+                checks[checkName] =
+                    result.status === "fulfilled"
+                        ? result.value
+                        : { status: "unhealthy", detail: String(result.reason) };
+            }
+        }
+        // Aggregate: unhealthy if any unhealthy, degraded if any degraded
+        let overall = "healthy";
+        for (const c of Object.values(checks)) {
+            if (c.status === "unhealthy") {
+                overall = "unhealthy";
+                break;
+            }
+            if (c.status === "degraded")
+                overall = "degraded";
+        }
+        log.debug("health check completed", { status: overall, checksRun: Object.keys(checks).length });
+        if (overall !== "healthy") {
+            log.warn("health check result is not healthy", {
+                status: overall,
+                unhealthyChecks: Object.entries(checks)
+                    .filter(([, c]) => c.status !== "healthy")
+                    .map(([n, c]) => ({ name: n, status: c.status, detail: c.detail })),
+            });
+        }
+        return {
+            status: overall,
+            uptime: Math.round(process.uptime()),
+            timestamp: new Date().toISOString(),
+            checks,
+        };
+    }
+    /**
+     * Liveness check — only critical checks can make this fail.
+     * Non-critical degraded/unhealthy checks are reported but don't affect the status.
+     */
+    async liveness() {
+        const full = await this.check();
+        let status = "healthy";
+        for (const [name, result] of Object.entries(full.checks)) {
+            const reg = this.checks.get(name);
+            if (!reg?.critical)
+                continue;
+            if (result.status === "unhealthy") {
+                status = "unhealthy";
+                break;
+            }
+            if (result.status === "degraded")
+                status = "degraded";
+        }
+        return { ...full, status };
+    }
+    /** List registered check names. */
+    list() {
+        return [...this.checks.keys()];
+    }
+    /** Get the last cached result for a check (without re-running). */
+    getLastResult(name) {
+        return this.checks.get(name)?.lastResult;
+    }
+    /** Get registration info for a check. */
+    getRegistration(name) {
+        return this.checks.get(name);
+    }
+    async runCheck(reg) {
+        const start = performance.now();
+        try {
+            const result = await Promise.race([
+                Promise.resolve(reg.fn()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`check timed out after ${reg.timeoutMs}ms`)), reg.timeoutMs)),
+            ]);
+            result.durationMs = Math.round(performance.now() - start);
+            result.lastChecked = new Date().toISOString();
+            reg.lastResult = result;
+            return result;
+        }
+        catch (err) {
+            const result = {
+                status: "unhealthy",
+                detail: err instanceof Error ? err.message : String(err),
+                durationMs: Math.round(performance.now() - start),
+                lastChecked: new Date().toISOString(),
+            };
+            log.error("health check failed", { detail: result.detail, durationMs: result.durationMs });
+            reg.lastResult = result;
+            return result;
+        }
+    }
+}
+//# sourceMappingURL=checker.js.map

package/dist/health/checker.js.map

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

package/dist/health/checks/openrouter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenRouter credit monitoring health check.
+ *
+ * Polls GET https://openrouter.ai/api/v1/key to report credit usage
+ * as a percentage. Maps to the "higher is worse" threshold model used
+ * by AlertManager.
+ */
+import type { HealthCheckFn } from "../types.js";
+/**
+ * Returns a health check function that polls the OpenRouter key endpoint.
+ *
+ * Detail format:
+ *   "credits 85% used, $2.30 remaining of $15.00 limit"
+ *   "credits unlimited (no limit set), $4.20 used"
+ *
+ * Status mapping:
+ *   limit === null     → healthy (unlimited)
+ *   percentUsed < 80   → healthy
+ *   percentUsed >= 80  → degraded
+ *   percentUsed >= 95  → unhealthy
+ *   API error / 401    → unhealthy
+ */
+export declare function openrouterCreditsCheck(): HealthCheckFn;
+/**
+ * Metric extractor for the credits check detail string.
+ * Parses "credits 85% used, ..." → { percentUsed: 85 }
+ */
+export declare function creditsExtractor(detail: string): Record<string, number>;
+//# sourceMappingURL=openrouter.d.ts.map

package/dist/health/checks/openrouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.d.ts","sourceRoot":"","sources":["../../../src/health/checks/openrouter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAgB9D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,aAAa,CA+CtD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGvE"}