@steadwing/openalerts 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,155 @@
+<p align="center">
+  <h1 align="center">OpenAlerts</h1>
+  <p align="center">
+    An alerting layer for agentic frameworks.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@steadwing/openalerts"><img src="https://img.shields.io/npm/v/@steadwing/openalerts?style=flat&color=blue" alt="npm"></a>
+  <a href="https://github.com/steadwing/openalerts/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"></a>
+  <a href="https://github.com/steadwing/openalerts/stargazers"><img src="https://img.shields.io/github/stars/steadwing/openalerts?style=flat" alt="GitHub stars"></a>
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> &middot;
+  <a href="#alert-rules">Alert Rules</a> &middot;
+  <a href="#configuration">Configuration</a> &middot;
+  <a href="#dashboard">Dashboard</a> &middot;
+  <a href="#commands">Commands</a>
+</p>
+
+---
+
+AI agents fail silently. LLM errors, stuck sessions, gateway outages — nobody knows until a user complains.
+
+OpenAlerts watches your agent in real-time and alerts you the moment something goes wrong. A framework-agnostic core with adapter plugins — starting with [OpenClaw](https://github.com/openclaw/openclaw).
+
+## Quickstart
+
+> Currently supports OpenClaw. More framework adapters coming soon.
+
+### 1. Install
+
+```bash
+openclaw plugins install @steadwing/openalerts
+```
+
+### 2. Configure
+
+Add to your `openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "openalerts": {
+        "enabled": true,
+        "config": {
+          "alertChannel": "telegram",  // telegram | discord | slack | whatsapp | signal
+          "alertTo": "YOUR_CHAT_ID"
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Restart & verify
+
+```bash
+openclaw gateway stop && openclaw gateway run
+```
+
+Send `/health` to your bot. You should get a live status report back — zero LLM tokens consumed.
+
+That's it. OpenAlerts is now watching your agent.
+
+## Alert Rules
+
+Seven rules run against every event in real-time:
+
+| Rule | Watches for | Severity |
+|---|---|---|
+| **llm-errors** | 3+ LLM failures in 5 minutes | ERROR |
+| **infra-errors** | 3+ infrastructure errors in 5 minutes | ERROR |
+| **gateway-down** | No heartbeat for 90+ seconds | CRITICAL |
+| **session-stuck** | Session idle for 120+ seconds | WARN |
+| **high-error-rate** | 50%+ of last 20 messages failed | ERROR |
+| **queue-depth** | 10+ items queued | WARN |
+| **heartbeat-fail** | 3 consecutive heartbeat failures | ERROR |
+
+All thresholds and cooldowns are [configurable per-rule](#configuration).
+
+## Configuration
+
+Full config reference under `plugins.entries.openalerts.config`:
+
+```jsonc
+{
+  "alertChannel": "telegram",       // telegram | discord | slack | whatsapp | signal
+  "alertTo": "YOUR_CHAT_ID",        // chat/user ID on that channel
+  "cooldownMinutes": 15,            // minutes between repeated alerts (default: 15)
+  "quiet": false,                   // true = log only, no messages sent
+
+  "rules": {
+    "gateway-down": {
+      "threshold": 120000            // override: 2 min instead of 90s
+    },
+    "high-error-rate": {
+      "enabled": false               // disable a rule entirely
+    },
+    "llm-errors": {
+      "threshold": 5,                // require 5 errors instead of 3
+      "cooldownMinutes": 30          // longer cooldown for this rule
+    }
+  }
+}
+```
+
+## Dashboard
+
+A real-time web dashboard is embedded in the gateway at:
+
+```
+http://127.0.0.1:18789/openalerts
+```
+
+- **Activity** — Live event timeline with session flows, tool calls, LLM usage
+- **System Logs** — Filtered, structured logs with search
+- **Health** — Rule status, alert history, system stats
+
+## Commands
+
+Zero-token chat commands available in any connected channel:
+
+| Command | What it does |
+|---|---|
+| `/health` | System health snapshot — uptime, active alerts, stats |
+| `/alerts` | Recent alert history with severity and timestamps |
+| `/dashboard` | Returns the dashboard URL |
+
+## Architecture
+
+```
+src/core/          Framework-agnostic engine, zero dependencies
+                   Rules engine, evaluator, event bus, state store, formatter
+
+src/plugin/        OpenClaw adapter plugin
+                   Event translation, alert routing, dashboard, chat commands
+```
+
+Everything ships as a single `@steadwing/openalerts` package. The core is completely framework-agnostic — adding monitoring for a new framework only requires writing an adapter.
+
+## Development
+
+```bash
+npm install        # install dependencies
+npm run build      # compile TypeScript
+npm run typecheck  # type-check without emitting
+npm run clean      # remove dist/
+```
+
+## License
+
+Apache-2.0

package/dist/core/alert-channel.d.ts

@@ -0,0 +1,23 @@
+import type { AlertChannel, AlertEvent, OpenAlertsLogger } from "./types.js";
+/**
+ * Dispatches alerts to all registered channels.
+ * Fire-and-forget: individual channel failures don't block others.
+ */
+export declare class AlertDispatcher {
+    private channels;
+    private logger;
+    private diagnosisHint?;
+    constructor(opts: {
+        channels?: AlertChannel[];
+        logger?: OpenAlertsLogger;
+        diagnosisHint?: string;
+    });
+    /** Add a channel at runtime. */
+    addChannel(channel: AlertChannel): void;
+    /** Send an alert to all registered channels. */
+    dispatch(alert: AlertEvent): Promise<void>;
+    /** Whether any channels are registered. */
+    get hasChannels(): boolean;
+    /** Number of registered channels. */
+    get channelCount(): number;
+}

package/dist/core/alert-channel.js

@@ -0,0 +1,44 @@
+import { formatAlertMessage } from "./formatter.js";
+/**
+ * Dispatches alerts to all registered channels.
+ * Fire-and-forget: individual channel failures don't block others.
+ */
+export class AlertDispatcher {
+    channels = [];
+    logger;
+    diagnosisHint;
+    constructor(opts) {
+        this.channels = opts.channels ?? [];
+        this.logger = opts.logger ?? console;
+        this.diagnosisHint = opts.diagnosisHint;
+    }
+    /** Add a channel at runtime. */
+    addChannel(channel) {
+        this.channels.push(channel);
+    }
+    /** Send an alert to all registered channels. */
+    async dispatch(alert) {
+        if (this.channels.length === 0)
+            return;
+        const formatted = formatAlertMessage(alert, {
+            diagnosisHint: this.diagnosisHint,
+        });
+        const results = this.channels.map(async (ch) => {
+            try {
+                await ch.send(alert, formatted);
+            }
+            catch (err) {
+                this.logger.error(`[openalerts] alert channel "${ch.name}" failed: ${String(err)}`);
+            }
+        });
+        await Promise.allSettled(results);
+    }
+    /** Whether any channels are registered. */
+    get hasChannels() {
+        return this.channels.length > 0;
+    }
+    /** Number of registered channels. */
+    get channelCount() {
+        return this.channels.length;
+    }
+}

package/dist/core/bounded-map.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded Map with LRU Eviction
+ *
+ * Prevents memory leaks by automatically pruning oldest entries when size limit is reached.
+ * Uses LRU (Least Recently Used) eviction strategy.
+ */
+export type BoundedMapOptions = {
+    /** Maximum number of entries */
+    maxSize: number;
+    /** Optional callback when entries are evicted */
+    onEvict?: (key: string, value: unknown) => void;
+    /** Optional TTL in ms for entries */
+    ttlMs?: number;
+};
+export type BoundedMapStats = {
+    size: number;
+    maxSize: number;
+    evictionCount: number;
+    hitCount: number;
+    missCount: number;
+};
+export declare class BoundedMap<K extends string, V> {
+    private readonly options;
+    private map;
+    private evictionCount;
+    private hitCount;
+    private missCount;
+    constructor(options: BoundedMapOptions);
+    /** Set a value */
+    set(key: K, value: V): this;
+    /** Get a value */
+    get(key: K): V | undefined;
+    /** Check if key exists */
+    has(key: K): boolean;
+    /** Delete a key */
+    delete(key: K): boolean;
+    /** Clear all entries */
+    clear(): void;
+    /** Get current size */
+    get size(): number;
+    /** Get all keys */
+    keys(): IterableIterator<K>;
+    /** Get all values */
+    values(): IterableIterator<V>;
+    /** Get all entries */
+    entries(): IterableIterator<[K, V]>;
+    /** Get stats */
+    getStats(): BoundedMapStats;
+    /** Evict oldest (least recently used) entry */
+    private evictOldest;
+}

package/dist/core/bounded-map.js

@@ -0,0 +1,128 @@
+/**
+ * Bounded Map with LRU Eviction
+ *
+ * Prevents memory leaks by automatically pruning oldest entries when size limit is reached.
+ * Uses LRU (Least Recently Used) eviction strategy.
+ */
+export class BoundedMap {
+    options;
+    map = new Map();
+    evictionCount = 0;
+    hitCount = 0;
+    missCount = 0;
+    constructor(options) {
+        this.options = options;
+        if (options.maxSize <= 0) {
+            throw new Error("maxSize must be positive");
+        }
+    }
+    /** Set a value */
+    set(key, value) {
+        const now = Date.now();
+        // If key exists, update it
+        if (this.map.has(key)) {
+            this.map.set(key, { value, accessTs: now, createTs: this.map.get(key).createTs });
+            return this;
+        }
+        // If at capacity, evict oldest entry
+        if (this.map.size >= this.options.maxSize) {
+            this.evictOldest();
+        }
+        this.map.set(key, { value, accessTs: now, createTs: now });
+        return this;
+    }
+    /** Get a value */
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry) {
+            this.missCount++;
+            return undefined;
+        }
+        // Check TTL if configured
+        if (this.options.ttlMs) {
+            const age = Date.now() - entry.createTs;
+            if (age > this.options.ttlMs) {
+                this.delete(key);
+                this.missCount++;
+                return undefined;
+            }
+        }
+        // Update access time (LRU)
+        entry.accessTs = Date.now();
+        this.hitCount++;
+        return entry.value;
+    }
+    /** Check if key exists */
+    has(key) {
+        if (!this.map.has(key))
+            return false;
+        // Check TTL if configured
+        if (this.options.ttlMs) {
+            const entry = this.map.get(key);
+            const age = Date.now() - entry.createTs;
+            if (age > this.options.ttlMs) {
+                this.delete(key);
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Delete a key */
+    delete(key) {
+        const entry = this.map.get(key);
+        if (entry) {
+            this.options.onEvict?.(key, entry.value);
+        }
+        return this.map.delete(key);
+    }
+    /** Clear all entries */
+    clear() {
+        if (this.options.onEvict) {
+            for (const [key, entry] of this.map) {
+                this.options.onEvict(key, entry.value);
+            }
+        }
+        this.map.clear();
+    }
+    /** Get current size */
+    get size() {
+        return this.map.size;
+    }
+    /** Get all keys */
+    keys() {
+        return this.map.keys();
+    }
+    /** Get all values */
+    values() {
+        return Array.from(this.map.values()).map(e => e.value).values();
+    }
+    /** Get all entries */
+    entries() {
+        return Array.from(this.map.entries()).map(([k, e]) => [k, e.value]).values();
+    }
+    /** Get stats */
+    getStats() {
+        return {
+            size: this.map.size,
+            maxSize: this.options.maxSize,
+            evictionCount: this.evictionCount,
+            hitCount: this.hitCount,
+            missCount: this.missCount,
+        };
+    }
+    /** Evict oldest (least recently used) entry */
+    evictOldest() {
+        let oldestKey;
+        let oldestTs = Infinity;
+        for (const [key, entry] of this.map) {
+            if (entry.accessTs < oldestTs) {
+                oldestTs = entry.accessTs;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.delete(oldestKey);
+            this.evictionCount++;
+        }
+    }
+}

package/dist/core/engine.d.ts

@@ -0,0 +1,41 @@
+import { OpenAlertsEventBus } from "./event-bus.js";
+import { type AlertEvent, type EvaluatorState, type OpenAlertsEvent, type OpenAlertsInitOptions, type StoredEvent } from "./types.js";
+/**
+ * OpenAlertsEngine — central orchestrator for monitoring and alerting.
+ *
+ * Framework-agnostic. Adapters (OpenClaw, Nanobot, LangChain, etc.)
+ * translate their events into OpenAlertsEvent and feed them to `ingest()`.
+ */
+export declare class OpenAlertsEngine {
+    readonly bus: OpenAlertsEventBus;
+    readonly state: EvaluatorState;
+    private config;
+    private stateDir;
+    private dispatcher;
+    private platform;
+    private logger;
+    private logPrefix;
+    private watchdogTimer;
+    private pruneTimer;
+    private running;
+    constructor(options: OpenAlertsInitOptions);
+    /** Start the engine: warm from history, start timers. */
+    start(): void;
+    /** Ingest a universal event. Can be called directly or via the event bus. */
+    ingest(event: OpenAlertsEvent): void;
+    /** Stop the engine: clear timers, flush platform, clear bus. */
+    stop(): void;
+    /** Add a channel at runtime (e.g., after detecting available transports). */
+    addChannel(channel: {
+        readonly name: string;
+        send(alert: AlertEvent, formatted: string): Promise<void> | void;
+    }): void;
+    /** Whether the platform sync is connected. */
+    get platformConnected(): boolean;
+    /** Whether the engine is running. */
+    get isRunning(): boolean;
+    /** Read recent stored events (for /alerts command). */
+    getRecentEvents(limit?: number): StoredEvent[];
+    private handleEvent;
+    private fireAlert;
+}

package/dist/core/engine.js

@@ -0,0 +1,167 @@
+import { AlertDispatcher } from "./alert-channel.js";
+import { OpenAlertsEventBus } from "./event-bus.js";
+import { createEvaluatorState, processEvent, processWatchdogTick, warmFromHistory } from "./evaluator.js";
+import { createPlatformSync } from "./platform.js";
+import { appendEvent, pruneLog, readAllEvents, readRecentEvents } from "./store.js";
+import { DEFAULTS, } from "./types.js";
+/**
+ * OpenAlertsEngine — central orchestrator for monitoring and alerting.
+ *
+ * Framework-agnostic. Adapters (OpenClaw, Nanobot, LangChain, etc.)
+ * translate their events into OpenAlertsEvent and feed them to `ingest()`.
+ */
+export class OpenAlertsEngine {
+    bus;
+    state;
+    config;
+    stateDir;
+    dispatcher;
+    platform = null;
+    logger;
+    logPrefix;
+    watchdogTimer = null;
+    pruneTimer = null;
+    running = false;
+    constructor(options) {
+        this.config = options.config;
+        this.stateDir = options.stateDir;
+        this.logger = options.logger ?? console;
+        this.logPrefix = options.logPrefix ?? "openalerts";
+        this.bus = new OpenAlertsEventBus();
+        this.state = createEvaluatorState();
+        this.dispatcher = new AlertDispatcher({
+            channels: options.channels,
+            logger: this.logger,
+            diagnosisHint: options.diagnosisHint,
+        });
+        // Wire up: bus events → evaluator → dispatcher
+        this.bus.on((event) => this.handleEvent(event));
+    }
+    /** Start the engine: warm from history, start timers. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Warm from persisted events
+        try {
+            const history = readAllEvents(this.stateDir);
+            warmFromHistory(this.state, history);
+            this.logger.info(`${this.logPrefix}: warmed from ${history.length} persisted events`);
+        }
+        catch (err) {
+            this.logger.warn(`${this.logPrefix}: warm-start failed: ${String(err)}`);
+        }
+        // Start platform sync if apiKey present
+        if (this.config.apiKey) {
+            this.platform = createPlatformSync({
+                apiKey: this.config.apiKey,
+                logger: this.logger,
+                logPrefix: this.logPrefix,
+            });
+            this.logger.info(`${this.logPrefix}: platform sync enabled`);
+        }
+        // Watchdog timer (checks for gateway-down every 30s)
+        this.watchdogTimer = setInterval(() => {
+            const alerts = processWatchdogTick(this.state, this.config);
+            for (const alert of alerts) {
+                this.fireAlert(alert);
+            }
+        }, DEFAULTS.watchdogIntervalMs);
+        // Prune timer (cleans old log entries every 6h)
+        this.pruneTimer = setInterval(() => {
+            try {
+                pruneLog(this.stateDir, {
+                    maxAgeMs: (this.config.maxLogAgeDays ?? DEFAULTS.maxLogAgeDays) * 24 * 60 * 60 * 1000,
+                    maxSizeKb: this.config.maxLogSizeKb ?? DEFAULTS.maxLogSizeKb,
+                });
+            }
+            catch (err) {
+                this.logger.warn(`${this.logPrefix}: prune failed: ${String(err)}`);
+            }
+        }, DEFAULTS.pruneIntervalMs);
+        const channelNames = this.dispatcher.hasChannels
+            ? `${this.dispatcher.channelCount} channel(s)`
+            : "log-only (no alert channels)";
+        this.logger.info(`${this.logPrefix}: started, ${channelNames}, 7 rules active`);
+    }
+    /** Ingest a universal event. Can be called directly or via the event bus. */
+    ingest(event) {
+        this.bus.emit(event);
+    }
+    /** Stop the engine: clear timers, flush platform, clear bus. */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.watchdogTimer) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+        this.platform?.stop();
+        this.bus.clear();
+        this.logger.info(`${this.logPrefix}: stopped`);
+    }
+    /** Add a channel at runtime (e.g., after detecting available transports). */
+    addChannel(channel) {
+        this.dispatcher.addChannel(channel);
+    }
+    /** Whether the platform sync is connected. */
+    get platformConnected() {
+        return this.platform?.isConnected() ?? false;
+    }
+    /** Whether the engine is running. */
+    get isRunning() {
+        return this.running;
+    }
+    /** Read recent stored events (for /alerts command). */
+    getRecentEvents(limit = 100) {
+        return readRecentEvents(this.stateDir, limit);
+    }
+    // ─── Internal ──────────────────────────────────────────────────────────────
+    handleEvent(event) {
+        // Persist as diagnostic snapshot
+        const snapshot = {
+            type: "diagnostic",
+            eventType: event.type,
+            ts: event.ts,
+            summary: `${event.type}${event.outcome ? `:${event.outcome}` : ""}`,
+            channel: event.channel,
+            sessionKey: event.sessionKey,
+        };
+        try {
+            appendEvent(this.stateDir, snapshot);
+        }
+        catch (err) {
+            this.logger.warn(`${this.logPrefix}: failed to persist event: ${String(err)}`);
+        }
+        // Run through evaluator
+        const alerts = processEvent(this.state, this.config, event);
+        for (const alert of alerts) {
+            this.fireAlert(alert);
+        }
+        // Forward to platform
+        this.platform?.enqueue(snapshot);
+    }
+    fireAlert(alert) {
+        // Persist alert
+        try {
+            appendEvent(this.stateDir, alert);
+        }
+        catch (err) {
+            this.logger.warn(`${this.logPrefix}: failed to persist alert: ${String(err)}`);
+        }
+        // Forward to platform
+        this.platform?.enqueue(alert);
+        // Dispatch to channels (unless quiet mode)
+        if (!this.config.quiet) {
+            void this.dispatcher.dispatch(alert).catch((err) => {
+                this.logger.error(`${this.logPrefix}: alert dispatch failed: ${String(err)}`);
+            });
+        }
+        this.logger.info(`${this.logPrefix}: [${alert.severity}] ${alert.title}`);
+    }
+}

package/dist/core/evaluator.d.ts

@@ -0,0 +1,18 @@
+import { type AlertEvent, type EvaluatorState, type MonitorConfig, type OpenAlertsEvent, type StoredEvent } from "./types.js";
+/** Create a fresh evaluator state. */
+export declare function createEvaluatorState(): EvaluatorState;
+/**
+ * Warm the evaluator state from persisted events.
+ * Replays recent events to rebuild windows/counters without re-firing alerts.
+ */
+export declare function warmFromHistory(state: EvaluatorState, events: StoredEvent[]): void;
+/**
+ * Process a single event through all rules.
+ * Returns alerts that should be fired (already filtered by cooldown + hourly cap).
+ */
+export declare function processEvent(state: EvaluatorState, config: MonitorConfig, event: OpenAlertsEvent): AlertEvent[];
+/**
+ * Run the watchdog tick — checks for gateway-down condition.
+ * Called every 30 seconds by the engine timer.
+ */
+export declare function processWatchdogTick(state: EvaluatorState, config: MonitorConfig): AlertEvent[];