@steadwing/openalerts 0.2.1 → 0.2.3

package/README.md

@@ -14,7 +14,7 @@
 <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="#llm-enriched-alerts">LLM Enrichment</a> &middot;
   <a href="#dashboard">Dashboard</a> &middot;
   <a href="#commands">Commands</a>
 </p>
@@ -37,7 +37,9 @@ openclaw plugins install @steadwing/openalerts
 
 ### 2. Configure
 
-Add to your `openclaw.json`:
+If you already have a channel paired with OpenClaw (e.g. Telegram via `openclaw pair`), **no config is needed** — OpenAlerts auto-detects where to send alerts.
+
+Otherwise, set it explicitly in `openclaw.json`:
 
 ```jsonc
 {
@@ -55,69 +57,105 @@ Add to your `openclaw.json`:
 }
 ```
 
+**Auto-detection priority:** explicit config > static `allowFrom` in channel config > pairing store.
+
 ### 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
+## 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
 
-Seven rules run against every event in real-time:
+## Alert Rules
 
-| 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 |
+Eight rules run against every event in real-time. All thresholds and cooldowns are configurable.
 
-All thresholds and cooldowns are [configurable per-rule](#configuration).
+| Rule | Watches for | Severity | Threshold (default) |
+|---|---|---|---|
+| `llm-errors` | LLM/agent failures in 1 min window | ERROR | `1` error |
+| `infra-errors` | Infrastructure errors in 1 min window | ERROR | `1` error |
+| `gateway-down` | No heartbeat received | CRITICAL | `30000` ms (30s) |
+| `session-stuck` | Session idle too long | WARN | `120000` ms (2 min) |
+| `high-error-rate` | Message failure rate over last 20 | ERROR | `50`% |
+| `queue-depth` | Queued items piling up | WARN | `10` items |
+| `tool-errors` | Tool failures in 1 min window | WARN | `1` error |
+| `heartbeat-fail` | Consecutive heartbeat failures | ERROR | `3` failures |
 
-## Configuration
+Every rule also accepts:
+- **`enabled`** — `false` to disable the rule (default: `true`)
+- **`cooldownMinutes`** — minutes before the same rule can fire again (default: `15`)
 
-Full config reference under `plugins.entries.openalerts.config`:
+To tune rules, add a `rules` object in your plugin 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
+  "plugins": {
+    "entries": {
+      "openalerts": {
+        "config": {
+          "cooldownMinutes": 10,
+          "rules": {
+            "llm-errors": { "threshold": 5 },
+            "infra-errors": { "cooldownMinutes": 30 },
+            "high-error-rate": { "enabled": false },
+            "gateway-down": { "threshold": 60000 }
+          }
+        }
+      }
     }
   }
 }
 ```
 
-## Dashboard
+Set `"quiet": true` at the config level for log-only mode (no messages sent).
 
-A real-time web dashboard is embedded in the gateway at:
+## LLM-Enriched Alerts
 
+OpenAlerts can optionally use your configured LLM to enrich alerts with a human-friendly summary and an actionable suggestion. **This feature is disabled by default** — opt in by setting `"llmEnriched": true` in your plugin config:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "openalerts": {
+        "config": {
+          "llmEnriched": true
+        }
+      }
+    }
+  }
+}
 ```
-http://127.0.0.1:18789/openalerts
+
+When enabled, alerts include an LLM-generated summary and action:
+
 ```
+1 agent error(s) on unknown in the last minute. Last: 401 Incorrect API key...
 
-- **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
+Summary: Your OpenAI API key is invalid or expired — the agent cannot make LLM calls.
+Action: Update your API key in ~/.openclaw/.env with a valid key from platform.openai.com/api-keys
+```
+
+- **Model**: reads from `agents.defaults.model.primary` in your `openclaw.json` (e.g. `"openai/gpt-4o-mini"`)
+- **API key**: reads from the corresponding environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GROQ_API_KEY`, etc.)
+- **Supported providers**: OpenAI, Anthropic, Groq, Together, DeepSeek (and any OpenAI-compatible API)
+- **Graceful fallback**: if the LLM call fails or times out (10s), the original alert is sent unchanged
 
 ## Commands
 
@@ -129,17 +167,10 @@ Zero-token chat commands available in any connected channel:
 | `/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
-```
+## Roadmap
 
-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.
+- [ ] [nanobot](https://github.com/HKUDS/nanobot) adapter
+- [ ] [OpenManus](https://github.com/FoundationAgents/OpenManus) adapter
 
 ## Development
 

package/dist/core/engine.d.ts

@@ -13,11 +13,14 @@ export declare class OpenAlertsEngine {
     private stateDir;
     private dispatcher;
     private platform;
+    private enricher;
     private logger;
     private logPrefix;
     private watchdogTimer;
     private pruneTimer;
     private running;
+    private eventRing;
+    private static readonly RING_MAX;
     constructor(options: OpenAlertsInitOptions);
     /** Start the engine: warm from history, start timers. */
     start(): void;
@@ -30,12 +33,16 @@ export declare class OpenAlertsEngine {
         readonly name: string;
         send(alert: AlertEvent, formatted: string): Promise<void> | void;
     }): void;
+    /** Fire a test alert to verify delivery. */
+    sendTestAlert(): 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[];
+    /** Get recent full events from the in-memory ring buffer (for dashboard history). */
+    getRecentLiveEvents(limit?: number): OpenAlertsEvent[];
     private handleEvent;
     private fireAlert;
 }

package/dist/core/engine.js

@@ -17,14 +17,18 @@ export class OpenAlertsEngine {
     stateDir;
     dispatcher;
     platform = null;
+    enricher;
     logger;
     logPrefix;
     watchdogTimer = null;
     pruneTimer = null;
     running = false;
+    eventRing = [];
+    static RING_MAX = 500;
     constructor(options) {
         this.config = options.config;
         this.stateDir = options.stateDir;
+        this.enricher = options.enricher ?? null;
         this.logger = options.logger ?? console;
         this.logPrefix = options.logPrefix ?? "openalerts";
         this.bus = new OpenAlertsEventBus();
@@ -64,7 +68,9 @@ export class OpenAlertsEngine {
         this.watchdogTimer = setInterval(() => {
             const alerts = processWatchdogTick(this.state, this.config);
             for (const alert of alerts) {
-                this.fireAlert(alert);
+                void this.fireAlert(alert).catch((err) => {
+                    this.logger.error(`${this.logPrefix}: watchdog alert failed: ${String(err)}`);
+                });
             }
         }, DEFAULTS.watchdogIntervalMs);
         // Prune timer (cleans old log entries every 6h)
@@ -82,7 +88,7 @@ export class OpenAlertsEngine {
         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`);
+        this.logger.info(`${this.logPrefix}: started, ${channelNames}, 8 rules active`);
     }
     /** Ingest a universal event. Can be called directly or via the event bus. */
     ingest(event) {
@@ -109,6 +115,21 @@ export class OpenAlertsEngine {
     addChannel(channel) {
         this.dispatcher.addChannel(channel);
     }
+    /** Fire a test alert to verify delivery. */
+    sendTestAlert() {
+        void this.fireAlert({
+            type: "alert",
+            id: `test:manual:${Date.now()}`,
+            ruleId: "test",
+            severity: "info",
+            title: "Test alert — delivery verified",
+            detail: "This is a test alert from /test_alert. If you see this, alert delivery is working.",
+            ts: Date.now(),
+            fingerprint: "test:manual",
+        }).catch((err) => {
+            this.logger.error(`${this.logPrefix}: test alert failed: ${String(err)}`);
+        });
+    }
     /** Whether the platform sync is connected. */
     get platformConnected() {
         return this.platform?.isConnected() ?? false;
@@ -121,8 +142,17 @@ export class OpenAlertsEngine {
     getRecentEvents(limit = 100) {
         return readRecentEvents(this.stateDir, limit);
     }
+    /** Get recent full events from the in-memory ring buffer (for dashboard history). */
+    getRecentLiveEvents(limit = 200) {
+        return this.eventRing.slice(-limit);
+    }
     // ─── Internal ──────────────────────────────────────────────────────────────
     handleEvent(event) {
+        // Add to in-memory ring buffer
+        this.eventRing.push(event);
+        if (this.eventRing.length > OpenAlertsEngine.RING_MAX) {
+            this.eventRing = this.eventRing.slice(-OpenAlertsEngine.RING_MAX);
+        }
         // Persist as diagnostic snapshot
         const snapshot = {
             type: "diagnostic",
@@ -141,13 +171,15 @@ export class OpenAlertsEngine {
         // Run through evaluator
         const alerts = processEvent(this.state, this.config, event);
         for (const alert of alerts) {
-            this.fireAlert(alert);
+            void this.fireAlert(alert).catch((err) => {
+                this.logger.error(`${this.logPrefix}: alert fire failed: ${String(err)}`);
+            });
         }
         // Forward to platform
         this.platform?.enqueue(snapshot);
     }
-    fireAlert(alert) {
-        // Persist alert
+    async fireAlert(alert) {
+        // Persist alert (original, before enrichment)
         try {
             appendEvent(this.stateDir, alert);
         }
@@ -156,9 +188,21 @@ export class OpenAlertsEngine {
         }
         // Forward to platform
         this.platform?.enqueue(alert);
+        // Enrich with LLM if enricher is available
+        let enriched = alert;
+        if (this.enricher) {
+            try {
+                const result = await this.enricher(alert);
+                if (result)
+                    enriched = result;
+            }
+            catch (err) {
+                this.logger.warn(`${this.logPrefix}: llm enrichment failed, using original: ${String(err)}`);
+            }
+        }
         // Dispatch to channels (unless quiet mode)
         if (!this.config.quiet) {
-            void this.dispatcher.dispatch(alert).catch((err) => {
+            void this.dispatcher.dispatch(enriched).catch((err) => {
                 this.logger.error(`${this.logPrefix}: alert dispatch failed: ${String(err)}`);
             });
         }

package/dist/core/evaluator.js

@@ -65,7 +65,7 @@ export function processEvent(state, config, event) {
         state.stats.totalCostUsd = 0;
         state.stats.lastResetTs = now;
     }
-    // Track event types in stats
+    // Track event types in stats (independent of rule enabled state)
     if (event.type === "infra.error") {
         state.stats.webhookErrors++;
     }
@@ -83,6 +83,16 @@ export function processEvent(state, config, event) {
     if (event.type === "session.start") {
         state.stats.sessionsStarted++;
     }
+    if (event.type === "session.stuck") {
+        state.stats.stuckSessions++;
+    }
+    if (event.type === "llm.call" || event.type === "llm.error" || event.type === "agent.error") {
+        state.stats.messagesProcessed++;
+        if (event.type === "llm.error" || event.type === "agent.error" ||
+            event.outcome === "error" || event.outcome === "timeout") {
+            state.stats.messageErrors++;
+        }
+    }
     if (event.type === "llm.token_usage") {
         if (typeof event.tokenCount === "number")
             state.stats.totalTokens += event.tokenCount;
@@ -103,7 +113,14 @@ export function processEvent(state, config, event) {
     const ctx = { state, config, now };
     const fired = [];
     for (const rule of ALL_RULES) {
-        const alert = rule.evaluate(event, ctx);
+        let alert;
+        try {
+            alert = rule.evaluate(event, ctx);
+        }
+        catch {
+            // One broken rule must never block the rest
+            continue;
+        }
         if (!alert)
             continue;
         // Check cooldown

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-export type { AlertChannel, AlertEvent, AlertRuleDefinition, AlertSeverity, AlertTarget, DiagnosticSnapshot, EvaluatorState, HeartbeatSnapshot, MonitorConfig, RuleContext, RuleOverride, OpenAlertsEvent, OpenAlertsEventType, OpenAlertsInitOptions, OpenAlertsLogger, StoredEvent, WindowEntry, } from "./types.js";
+export type { AlertChannel, AlertEnricher, 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";
@@ -6,6 +6,7 @@ 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 { createLlmEnricher, type LlmEnricherOptions } from "./llm-enrichment.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

@@ -13,6 +13,8 @@ export { createEvaluatorState, processEvent, processWatchdogTick, warmFromHistor
 export { ALL_RULES } from "./rules.js";
 // Store
 export { appendEvent, pruneLog, readAllEvents, readRecentEvents, } from "./store.js";
+// LLM Enrichment
+export { createLlmEnricher } from "./llm-enrichment.js";
 // Formatter
 export { formatAlertMessage, formatAlertsOutput, formatHealthOutput, } from "./formatter.js";
 // Platform

package/dist/core/llm-enrichment.d.ts

@@ -0,0 +1,21 @@
+import type { AlertEnricher, OpenAlertsLogger } from "./types.js";
+export type LlmEnricherOptions = {
+    /** Model string from config, e.g. "openai/gpt-5-nano" */
+    modelString: string;
+    /** Pre-resolved API key (caller reads from env to avoid env+fetch in same file) */
+    apiKey: string;
+    /** Logger for debug/warn messages */
+    logger?: OpenAlertsLogger;
+    /** Timeout in ms (default: 10000) */
+    timeoutMs?: number;
+};
+/**
+ * Resolve the environment variable name for a given model string's provider.
+ * Returns null if the model string is invalid or the provider is unknown.
+ */
+export declare function resolveApiKeyEnvVar(modelString: string): string | null;
+/**
+ * Create an AlertEnricher that calls an LLM to add a summary + action to alerts.
+ * Returns null if provider can't be resolved.
+ */
+export declare function createLlmEnricher(opts: LlmEnricherOptions): AlertEnricher | null;

package/dist/core/llm-enrichment.js

@@ -0,0 +1,180 @@
+const PROVIDER_MAP = {
+    openai: {
+        type: "openai-compatible",
+        baseUrl: "https://api.openai.com/v1",
+        apiKeyEnvVar: "OPENAI_API_KEY",
+    },
+    groq: {
+        type: "openai-compatible",
+        baseUrl: "https://api.groq.com/openai/v1",
+        apiKeyEnvVar: "GROQ_API_KEY",
+    },
+    together: {
+        type: "openai-compatible",
+        baseUrl: "https://api.together.xyz/v1",
+        apiKeyEnvVar: "TOGETHER_API_KEY",
+    },
+    deepseek: {
+        type: "openai-compatible",
+        baseUrl: "https://api.deepseek.com/v1",
+        apiKeyEnvVar: "DEEPSEEK_API_KEY",
+    },
+    anthropic: {
+        type: "anthropic",
+        baseUrl: "https://api.anthropic.com/v1",
+        apiKeyEnvVar: "ANTHROPIC_API_KEY",
+    },
+};
+// ─── Prompt ─────────────────────────────────────────────────────────────────
+function buildPrompt(alert) {
+    return `You are a concise DevOps alert analyst. Given this monitoring alert, provide:
+1. A brief human-friendly summary (1 sentence, plain language)
+2. One actionable suggestion to resolve it
+
+Alert:
+- Rule: ${alert.ruleId}
+- Severity: ${alert.severity}
+- Title: ${alert.title}
+- Detail: ${alert.detail}
+
+Reply in exactly this format (2 lines only):
+Summary: <your summary>
+Action: <your suggestion>`;
+}
+// ─── Response Parsing ───────────────────────────────────────────────────────
+function parseEnrichment(text) {
+    const lines = text.trim().split("\n");
+    let summary = "";
+    let action = "";
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.toLowerCase().startsWith("summary:")) {
+            summary = trimmed.slice("summary:".length).trim();
+        }
+        else if (trimmed.toLowerCase().startsWith("action:")) {
+            action = trimmed.slice("action:".length).trim();
+        }
+    }
+    if (!summary && !action)
+        return null;
+    return { summary, action };
+}
+// ─── HTTP Calls ─────────────────────────────────────────────────────────────
+async function callOpenAICompatible(baseUrl, apiKey, model, prompt, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                messages: [{ role: "user", content: prompt }],
+                max_tokens: 200,
+                temperature: 0.3,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.choices?.[0]?.message?.content ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function callAnthropic(baseUrl, apiKey, model, prompt, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${baseUrl}/messages`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 200,
+                messages: [{ role: "user", content: prompt }],
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const textBlock = data.content?.find((b) => b.type === "text");
+        return textBlock?.text ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Resolve the environment variable name for a given model string's provider.
+ * Returns null if the model string is invalid or the provider is unknown.
+ */
+export function resolveApiKeyEnvVar(modelString) {
+    const slashIdx = modelString.indexOf("/");
+    if (slashIdx < 1)
+        return null;
+    const providerKey = modelString.slice(0, slashIdx).toLowerCase();
+    return PROVIDER_MAP[providerKey]?.apiKeyEnvVar ?? null;
+}
+/**
+ * Create an AlertEnricher that calls an LLM to add a summary + action to alerts.
+ * Returns null if provider can't be resolved.
+ */
+export function createLlmEnricher(opts) {
+    const { modelString, apiKey, logger, timeoutMs = 10_000 } = opts;
+    // Parse "provider/model-name" format
+    const slashIdx = modelString.indexOf("/");
+    if (slashIdx < 1) {
+        logger?.warn(`openalerts: llm-enrichment skipped — invalid model string "${modelString}"`);
+        return null;
+    }
+    const providerKey = modelString.slice(0, slashIdx).toLowerCase();
+    const model = modelString.slice(slashIdx + 1);
+    const providerConfig = PROVIDER_MAP[providerKey];
+    if (!providerConfig) {
+        logger?.warn(`openalerts: llm-enrichment skipped — unknown provider "${providerKey}"`);
+        return null;
+    }
+    logger?.info(`openalerts: llm-enrichment enabled (${providerKey}/${model})`);
+    return async (alert) => {
+        const prompt = buildPrompt(alert);
+        let responseText = null;
+        if (providerConfig.type === "anthropic") {
+            responseText = await callAnthropic(providerConfig.baseUrl, apiKey, model, prompt, timeoutMs);
+        }
+        else {
+            responseText = await callOpenAICompatible(providerConfig.baseUrl, apiKey, model, prompt, timeoutMs);
+        }
+        if (!responseText)
+            return null;
+        const parsed = parseEnrichment(responseText);
+        if (!parsed)
+            return null;
+        // Append enrichment to the original detail
+        let enrichedDetail = alert.detail;
+        if (parsed.summary) {
+            enrichedDetail += `\n\nSummary: ${parsed.summary}`;
+        }
+        if (parsed.action) {
+            enrichedDetail += `\nAction: ${parsed.action}`;
+        }
+        return { ...alert, detail: enrichedDetail };
+    };
+}