@steadwing/openalerts 0.1.0 → 0.2.0

package/dist/core/evaluator.js

@@ -0,0 +1,150 @@
+import { ALL_RULES } from "./rules.js";
+import { DEFAULTS, } from "./types.js";
+/** Create a fresh evaluator state. */
+export function createEvaluatorState() {
+    const now = Date.now();
+    return {
+        windows: new Map(),
+        cooldowns: new Map(),
+        consecutives: new Map(),
+        hourlyAlerts: { count: 0, resetAt: now + 60 * 60 * 1000 },
+        lastHeartbeatTs: 0,
+        startedAt: now,
+        stats: {
+            messagesProcessed: 0,
+            messageErrors: 0,
+            messagesReceived: 0,
+            webhookErrors: 0,
+            stuckSessions: 0,
+            toolCalls: 0,
+            toolErrors: 0,
+            agentStarts: 0,
+            agentErrors: 0,
+            sessionsStarted: 0,
+            compactions: 0,
+            totalTokens: 0,
+            totalCostUsd: 0,
+            lastResetTs: now,
+        },
+    };
+}
+/**
+ * Warm the evaluator state from persisted events.
+ * Replays recent events to rebuild windows/counters without re-firing alerts.
+ */
+export function warmFromHistory(state, events) {
+    for (const event of events) {
+        if (event.type === "alert") {
+            // Restore cooldowns from recent alerts
+            state.cooldowns.set(event.fingerprint, event.ts);
+        }
+        // Don't replay diagnostic/heartbeat events through rules —
+        // that would re-fire alerts. Just restore cooldown state.
+    }
+}
+/**
+ * Process a single event through all rules.
+ * Returns alerts that should be fired (already filtered by cooldown + hourly cap).
+ */
+export function processEvent(state, config, event) {
+    const now = Date.now();
+    // Reset 24h stats daily
+    if (now - state.stats.lastResetTs > 24 * 60 * 60 * 1000) {
+        state.stats.messagesProcessed = 0;
+        state.stats.messageErrors = 0;
+        state.stats.messagesReceived = 0;
+        state.stats.webhookErrors = 0;
+        state.stats.stuckSessions = 0;
+        state.stats.toolCalls = 0;
+        state.stats.toolErrors = 0;
+        state.stats.agentStarts = 0;
+        state.stats.agentErrors = 0;
+        state.stats.sessionsStarted = 0;
+        state.stats.compactions = 0;
+        state.stats.totalTokens = 0;
+        state.stats.totalCostUsd = 0;
+        state.stats.lastResetTs = now;
+    }
+    // Track event types in stats
+    if (event.type === "infra.error") {
+        state.stats.webhookErrors++;
+    }
+    if (event.type === "tool.call" || event.type === "tool.error") {
+        state.stats.toolCalls++;
+        if (event.type === "tool.error")
+            state.stats.toolErrors++;
+    }
+    if (event.type === "agent.start") {
+        state.stats.agentStarts++;
+    }
+    if (event.type === "agent.error") {
+        state.stats.agentErrors++;
+    }
+    if (event.type === "session.start") {
+        state.stats.sessionsStarted++;
+    }
+    if (event.type === "llm.token_usage") {
+        if (typeof event.tokenCount === "number")
+            state.stats.totalTokens += event.tokenCount;
+        if (typeof event.costUsd === "number")
+            state.stats.totalCostUsd += event.costUsd;
+    }
+    if (event.type === "custom" && event.meta?.openclawHook === "message_received") {
+        state.stats.messagesReceived++;
+    }
+    if (event.type === "custom" && event.meta?.compaction === true) {
+        state.stats.compactions++;
+    }
+    // Reset hourly cap if expired
+    if (now >= state.hourlyAlerts.resetAt) {
+        state.hourlyAlerts.count = 0;
+        state.hourlyAlerts.resetAt = now + 60 * 60 * 1000;
+    }
+    const ctx = { state, config, now };
+    const fired = [];
+    for (const rule of ALL_RULES) {
+        const alert = rule.evaluate(event, ctx);
+        if (!alert)
+            continue;
+        // Check cooldown
+        const cooldownMs = resolveCooldownMs(config, rule);
+        const lastFired = state.cooldowns.get(alert.fingerprint);
+        if (lastFired && now - lastFired < cooldownMs)
+            continue;
+        // Check hourly cap
+        if (state.hourlyAlerts.count >= DEFAULTS.maxAlertsPerHour)
+            continue;
+        // Fire the alert
+        state.cooldowns.set(alert.fingerprint, now);
+        state.hourlyAlerts.count++;
+        fired.push(alert);
+    }
+    // Prune cooldown map if too large
+    if (state.cooldowns.size > DEFAULTS.maxCooldownEntries) {
+        const entries = [...state.cooldowns.entries()].sort((a, b) => a[1] - b[1]);
+        const toRemove = entries.slice(0, entries.length - DEFAULTS.maxCooldownEntries);
+        for (const [key] of toRemove) {
+            state.cooldowns.delete(key);
+        }
+    }
+    return fired;
+}
+/**
+ * Run the watchdog tick — checks for gateway-down condition.
+ * Called every 30 seconds by the engine timer.
+ */
+export function processWatchdogTick(state, config) {
+    return processEvent(state, config, { type: "watchdog.tick", ts: Date.now() });
+}
+/** Resolve the effective cooldown for a rule. */
+function resolveCooldownMs(config, rule) {
+    const override = config.rules?.[rule.id]?.cooldownMinutes;
+    if (typeof override === "number" && override > 0) {
+        return override * 60 * 1000;
+    }
+    const globalOverride = config.cooldownMinutes;
+    if (typeof globalOverride === "number" && globalOverride > 0) {
+        return globalOverride * 60 * 1000;
+    }
+    return rule.defaultCooldownMs;
+}

package/dist/core/event-bus.d.ts

@@ -0,0 +1,17 @@
+import type { OpenAlertsEvent } from "./types.js";
+export type EventListener = (event: OpenAlertsEvent) => void;
+/**
+ * Simple pub/sub event bus for OpenAlertsEvents.
+ * Replaces framework-specific event subscriptions (e.g., OpenClaw's onDiagnosticEvent).
+ */
+export declare class OpenAlertsEventBus {
+    private listeners;
+    /** Subscribe to all events. Returns an unsubscribe function. */
+    on(listener: EventListener): () => void;
+    /** Emit an event to all listeners. Errors in listeners are caught and logged. */
+    emit(event: OpenAlertsEvent): void;
+    /** Remove all listeners. */
+    clear(): void;
+    /** Current listener count. */
+    get size(): number;
+}

package/dist/core/event-bus.js

@@ -0,0 +1,31 @@
+/**
+ * Simple pub/sub event bus for OpenAlertsEvents.
+ * Replaces framework-specific event subscriptions (e.g., OpenClaw's onDiagnosticEvent).
+ */
+export class OpenAlertsEventBus {
+    listeners = new Set();
+    /** Subscribe to all events. Returns an unsubscribe function. */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Emit an event to all listeners. Errors in listeners are caught and logged. */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                console.error("[openalerts] event listener error:", err);
+            }
+        }
+    }
+    /** Remove all listeners. */
+    clear() {
+        this.listeners.clear();
+    }
+    /** Current listener count. */
+    get size() {
+        return this.listeners.size;
+    }
+}

package/dist/core/formatter.d.ts

@@ -0,0 +1,14 @@
+import type { AlertEvent, EvaluatorState, StoredEvent } from "./types.js";
+export declare function formatAlertMessage(alert: AlertEvent, opts?: {
+    diagnosisHint?: string;
+}): string;
+export declare function formatHealthOutput(opts: {
+    state: EvaluatorState;
+    channelActivity: Array<{
+        channel: string;
+        lastInbound: number | null;
+    }>;
+    activeAlerts: AlertEvent[];
+    platformConnected: boolean;
+}): string;
+export declare function formatAlertsOutput(events: StoredEvent[]): string;

package/dist/core/formatter.js

@@ -0,0 +1,124 @@
+// ─── Alert Messages (sent to user's channel) ────────────────────────────────
+export function formatAlertMessage(alert, opts) {
+    const prefix = alert.severity === "critical"
+        ? "[OpenAlerts] CRITICAL: "
+        : "[OpenAlerts] ";
+    const lines = [prefix + alert.title, "", alert.detail, "", "/health for full status."];
+    if (alert.severity === "critical" && opts?.diagnosisHint) {
+        lines[lines.length - 1] = opts.diagnosisHint;
+    }
+    return lines.join("\n");
+}
+// ─── /health Command Output ──────────────────────────────────────────────────
+export function formatHealthOutput(opts) {
+    const { state, channelActivity, activeAlerts, platformConnected } = opts;
+    const uptime = formatDuration(Date.now() - state.startedAt);
+    const heartbeatAgo = state.lastHeartbeatTs > 0
+        ? `${formatDuration(Date.now() - state.lastHeartbeatTs)} ago`
+        : "none yet";
+    const status = activeAlerts.length > 0 ? "DEGRADED" : "OK";
+    const lines = [
+        "System Health -- OpenAlerts",
+        "",
+        `Status: ${status}`,
+        `Uptime: ${uptime} | Last heartbeat: ${heartbeatAgo}`,
+    ];
+    // Active alerts
+    if (activeAlerts.length > 0) {
+        lines.push("");
+        lines.push(`!! ${activeAlerts.length} active alert${activeAlerts.length > 1 ? "s" : ""}:`);
+        for (const a of activeAlerts.slice(0, 5)) {
+            const ago = formatDuration(Date.now() - a.ts);
+            lines.push(`  [${a.severity.toUpperCase()}] ${a.title} (${ago} ago)`);
+        }
+    }
+    // Channel activity
+    if (channelActivity.length > 0) {
+        lines.push("");
+        lines.push("Channels:");
+        for (const ch of channelActivity) {
+            const ago = ch.lastInbound
+                ? `active (${formatDuration(Date.now() - ch.lastInbound)} ago)`
+                : "no activity";
+            lines.push(`  ${ch.channel.padEnd(10)}: ${ago}`);
+        }
+    }
+    // 24h stats
+    lines.push("");
+    const s = state.stats;
+    const rcvd = s.messagesReceived > 0 ? `, ${s.messagesReceived} received` : "";
+    lines.push(`24h: ${s.messagesProcessed} msgs processed${rcvd}, ${s.messageErrors} errors, ${s.stuckSessions} stuck`);
+    if (s.toolCalls > 0 || s.agentStarts > 0 || s.sessionsStarted > 0) {
+        const parts = [];
+        if (s.toolCalls > 0)
+            parts.push(`${s.toolCalls} tools${s.toolErrors > 0 ? ` (${s.toolErrors} err)` : ""}`);
+        if (s.agentStarts > 0)
+            parts.push(`${s.agentStarts} agents${s.agentErrors > 0 ? ` (${s.agentErrors} err)` : ""}`);
+        if (s.sessionsStarted > 0)
+            parts.push(`${s.sessionsStarted} sessions`);
+        if (s.compactions > 0)
+            parts.push(`${s.compactions} compactions`);
+        lines.push(`     ${parts.join(", ")}`);
+    }
+    if (s.totalTokens > 0) {
+        const tokenStr = s.totalTokens >= 1000 ? `${(s.totalTokens / 1000).toFixed(1)}k` : `${s.totalTokens}`;
+        const costStr = s.totalCostUsd > 0 ? ` ($${s.totalCostUsd.toFixed(4)})` : "";
+        lines.push(`     ${tokenStr} tokens${costStr}`);
+    }
+    // Platform
+    lines.push("");
+    lines.push(platformConnected
+        ? "Platform: connected (openalerts.dev)"
+        : "Platform: not connected (add apiKey for diagnosis)");
+    return lines.join("\n");
+}
+// ─── /alerts Command Output ──────────────────────────────────────────────────
+export function formatAlertsOutput(events) {
+    const alerts = events.filter((e) => e.type === "alert");
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const recent = alerts.filter((a) => a.ts >= cutoff);
+    if (recent.length === 0) {
+        return [
+            "Recent Alerts",
+            "",
+            "No alerts in the last 24h. All systems normal.",
+        ].join("\n");
+    }
+    const lines = [
+        `Recent Alerts (${recent.length} in 24h)`,
+        "",
+    ];
+    // Show most recent first, cap at 10
+    const shown = recent.slice(-10).reverse();
+    for (const alert of shown) {
+        const time = new Date(alert.ts).toLocaleTimeString([], {
+            hour: "2-digit",
+            minute: "2-digit",
+        });
+        lines.push(`[${alert.severity.toUpperCase()}] ${time} -- ${alert.title}`);
+        lines.push(`  ${alert.detail}`);
+        lines.push("");
+    }
+    if (recent.length > 10) {
+        lines.push(`Showing 10 of ${recent.length} alerts.`);
+    }
+    return lines.join("\n").trimEnd();
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function formatDuration(ms) {
+    if (ms < 0)
+        ms = 0;
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const hr = Math.floor(min / 60);
+    const remainMin = min % 60;
+    if (hr < 24)
+        return remainMin > 0 ? `${hr}h ${remainMin}m` : `${hr}h`;
+    const days = Math.floor(hr / 24);
+    const remainHr = hr % 24;
+    return remainHr > 0 ? `${days}d ${remainHr}h` : `${days}d`;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,11 @@
+export type { AlertChannel, AlertEvent, AlertRuleDefinition, AlertSeverity, AlertTarget, DiagnosticSnapshot, EvaluatorState, HeartbeatSnapshot, MonitorConfig, RuleContext, RuleOverride, OpenAlertsEvent, OpenAlertsEventType, OpenAlertsInitOptions, OpenAlertsLogger, StoredEvent, WindowEntry, } from "./types.js";
+export { DEFAULTS, LOG_FILENAME, STORE_DIR_NAME } from "./types.js";
+export { OpenAlertsEngine } from "./engine.js";
+export { OpenAlertsEventBus } from "./event-bus.js";
+export { AlertDispatcher } from "./alert-channel.js";
+export { createEvaluatorState, processEvent, processWatchdogTick, warmFromHistory, } from "./evaluator.js";
+export { ALL_RULES } from "./rules.js";
+export { appendEvent, pruneLog, readAllEvents, readRecentEvents, } from "./store.js";
+export { formatAlertMessage, formatAlertsOutput, formatHealthOutput, } from "./formatter.js";
+export { createPlatformSync, type PlatformSync } from "./platform.js";
+export { BoundedMap, type BoundedMapOptions, type BoundedMapStats, } from "./bounded-map.js";

package/dist/core/index.js

@@ -0,0 +1,21 @@
+// OpenAlerts core — engine, rules, evaluator, store
+// Constants
+export { DEFAULTS, LOG_FILENAME, STORE_DIR_NAME } from "./types.js";
+// Engine
+export { OpenAlertsEngine } from "./engine.js";
+// Event Bus
+export { OpenAlertsEventBus } from "./event-bus.js";
+// Alert Dispatcher
+export { AlertDispatcher } from "./alert-channel.js";
+// Evaluator
+export { createEvaluatorState, processEvent, processWatchdogTick, warmFromHistory, } from "./evaluator.js";
+// Rules
+export { ALL_RULES } from "./rules.js";
+// Store
+export { appendEvent, pruneLog, readAllEvents, readRecentEvents, } from "./store.js";
+// Formatter
+export { formatAlertMessage, formatAlertsOutput, formatHealthOutput, } from "./formatter.js";
+// Platform
+export { createPlatformSync } from "./platform.js";
+// Bounded Map
+export { BoundedMap, } from "./bounded-map.js";

package/dist/core/platform.d.ts

@@ -0,0 +1,17 @@
+import { type OpenAlertsLogger, type StoredEvent } from "./types.js";
+export type PlatformSync = {
+    enqueue: (event: StoredEvent) => void;
+    flush: () => Promise<void>;
+    stop: () => void;
+    isConnected: () => boolean;
+};
+/**
+ * Create a platform sync instance that batches events and pushes them
+ * to the OpenAlerts backend API. Only active when apiKey is provided.
+ */
+export declare function createPlatformSync(opts: {
+    apiKey: string;
+    baseUrl?: string;
+    logger: OpenAlertsLogger;
+    logPrefix?: string;
+}): PlatformSync;

package/dist/core/platform.js

@@ -0,0 +1,93 @@
+import { DEFAULTS } from "./types.js";
+/**
+ * Create a platform sync instance that batches events and pushes them
+ * to the OpenAlerts backend API. Only active when apiKey is provided.
+ */
+export function createPlatformSync(opts) {
+    const { apiKey, logger } = opts;
+    const baseUrl = opts.baseUrl?.replace(/\/+$/, "") ?? "https://api.openalerts.dev";
+    const prefix = opts.logPrefix ?? "openalerts";
+    let batch = [];
+    let flushTimer = null;
+    let disabled = false;
+    let connected = true;
+    // Start periodic flush
+    flushTimer = setInterval(() => {
+        void doFlush().catch(() => { });
+    }, DEFAULTS.platformFlushIntervalMs);
+    async function doFlush() {
+        if (disabled || batch.length === 0)
+            return;
+        const events = batch.splice(0, DEFAULTS.platformBatchSize);
+        const body = JSON.stringify({
+            events,
+            plugin_version: "0.1.0",
+            ts: Date.now(),
+        });
+        let lastErr;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const res = await fetch(`${baseUrl}/api/monitor/ingest`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${apiKey}`,
+                    },
+                    body,
+                    signal: AbortSignal.timeout(15_000),
+                });
+                if (res.ok) {
+                    connected = true;
+                    return; // Success
+                }
+                if (res.status === 401 || res.status === 403) {
+                    logger.warn(`${prefix}: invalid API key (${res.status}). Platform sync disabled. Check your key at app.openalerts.dev.`);
+                    disabled = true;
+                    connected = false;
+                    return;
+                }
+                lastErr = `HTTP ${res.status}`;
+            }
+            catch (err) {
+                lastErr = err;
+            }
+            // Wait before retry
+            if (attempt < 1) {
+                await new Promise((r) => setTimeout(r, 5000));
+            }
+        }
+        // Failed after retries — put events back and log
+        batch.unshift(...events);
+        // Cap batch to prevent unbounded growth
+        if (batch.length > DEFAULTS.platformBatchSize * 2) {
+            batch = batch.slice(-DEFAULTS.platformBatchSize);
+        }
+        connected = false;
+        logger.warn(`${prefix}: platform sync failed: ${String(lastErr)}`);
+    }
+    return {
+        enqueue(event) {
+            if (disabled)
+                return;
+            batch.push(event);
+            // Auto-flush if batch full
+            if (batch.length >= DEFAULTS.platformBatchSize) {
+                void doFlush().catch(() => { });
+            }
+        },
+        async flush() {
+            await doFlush();
+        },
+        stop() {
+            if (flushTimer) {
+                clearInterval(flushTimer);
+                flushTimer = null;
+            }
+            // Final flush attempt (best-effort, don't await in stop)
+            void doFlush().catch(() => { });
+        },
+        isConnected() {
+            return connected && !disabled;
+        },
+    };
+}

package/dist/core/rules.d.ts

@@ -0,0 +1,2 @@
+import { type AlertRuleDefinition } from "./types.js";
+export declare const ALL_RULES: AlertRuleDefinition[];