@steadwing/openalerts 0.2.1 → 0.2.3

package/dist/core/rules.js

@@ -32,7 +32,7 @@ function isRuleEnabled(ctx, ruleId) {
 const infraErrors = {
     id: "infra-errors",
     defaultCooldownMs: 15 * 60 * 1000,
-    defaultThreshold: 3,
+    defaultThreshold: 1,
     evaluate(event, ctx) {
         if (event.type !== "infra.error")
             return null;
@@ -40,8 +40,8 @@ const infraErrors = {
             return null;
         const channel = event.channel ?? "unknown";
         pushWindow(ctx, "infra-errors", { ts: ctx.now });
-        const threshold = getRuleThreshold(ctx, "infra-errors", 3);
-        const windowMs = 5 * 60 * 1000; // 5 minutes
+        const threshold = getRuleThreshold(ctx, "infra-errors", 1);
+        const windowMs = 60 * 1000; // 1 minute
         const count = countInWindow(ctx, "infra-errors", windowMs);
         if (count < threshold)
             return null;
@@ -52,7 +52,7 @@ const infraErrors = {
             ruleId: "infra-errors",
             severity: "error",
             title: "Infrastructure errors spike",
-            detail: `${count} infra errors on ${channel} in the last 5 minutes.`,
+            detail: `${count} infra error(s) on ${channel} in the last minute.${event.error ? ` Last: ${event.error}` : ""}`,
             ts: ctx.now,
             fingerprint,
         };
@@ -62,32 +62,37 @@ const infraErrors = {
 const llmErrors = {
     id: "llm-errors",
     defaultCooldownMs: 15 * 60 * 1000,
-    defaultThreshold: 3,
+    defaultThreshold: 1,
     evaluate(event, ctx) {
-        if (event.type !== "llm.call")
+        // Trigger on LLM call/error events AND agent errors (agent failing before/during LLM call)
+        if (event.type !== "llm.call" && event.type !== "llm.error" && event.type !== "agent.error")
             return null;
         if (!isRuleEnabled(ctx, "llm-errors"))
             return null;
-        // Track all LLM calls for stats
-        ctx.state.stats.messagesProcessed++;
-        if (event.outcome !== "error")
-            return null;
-        ctx.state.stats.messageErrors++;
+        // Stats are tracked in the evaluator (independent of rule state).
+        // Only proceed for actual errors:
+        if (event.type === "llm.call") {
+            // Only explicit error/timeout outcomes trigger alerting; undefined = OK
+            if (event.outcome !== "error" && event.outcome !== "timeout")
+                return null;
+        }
+        // llm.error and agent.error are always errors — no outcome check needed
         const channel = event.channel ?? "unknown";
         pushWindow(ctx, "llm-errors", { ts: ctx.now });
-        const threshold = getRuleThreshold(ctx, "llm-errors", 3);
-        const windowMs = 5 * 60 * 1000;
+        const threshold = getRuleThreshold(ctx, "llm-errors", 1);
+        const windowMs = 60 * 1000; // 1 minute
         const count = countInWindow(ctx, "llm-errors", windowMs);
         if (count < threshold)
             return null;
         const fingerprint = `llm-errors:${channel}`;
+        const label = event.type === "agent.error" ? "agent error(s)" : "LLM error(s)";
         return {
             type: "alert",
             id: makeAlertId("llm-errors", fingerprint, ctx.now),
             ruleId: "llm-errors",
             severity: "error",
             title: "LLM call errors",
-            detail: `${count} LLM errors on ${channel} in the last 5 minutes.`,
+            detail: `${count} ${label} on ${channel} in the last minute.${event.error ? ` Last: ${event.error}` : ""}`,
             ts: ctx.now,
             fingerprint,
         };
@@ -103,7 +108,7 @@ const sessionStuck = {
             return null;
         if (!isRuleEnabled(ctx, "session-stuck"))
             return null;
-        ctx.state.stats.stuckSessions++;
+        // Stats tracked in evaluator (independent of rule state)
         const ageMs = event.ageMs ?? 0;
         const threshold = getRuleThreshold(ctx, "session-stuck", 120_000);
         if (ageMs < threshold)
@@ -153,10 +158,8 @@ const heartbeatFail = {
                 fingerprint,
             };
         }
-        // Reset on success
-        if (event.outcome === "success") {
-            ctx.state.consecutives.set(counterKey, 0);
-        }
+        // Reset on any non-error (success, undefined, etc.)
+        ctx.state.consecutives.set(counterKey, 0);
         return null;
     },
 };
@@ -169,12 +172,12 @@ const queueDepth = {
         // Fire on heartbeat (which carries queue depth) and dedicated queue_depth events
         if (event.type !== "infra.heartbeat" && event.type !== "infra.queue_depth")
             return null;
-        if (!isRuleEnabled(ctx, "queue-depth"))
-            return null;
-        // Update last heartbeat timestamp (used by gateway-down rule)
+        // Always update heartbeat timestamp regardless of rule state (gateway-down depends on it)
         if (event.type === "infra.heartbeat") {
             ctx.state.lastHeartbeatTs = ctx.now;
         }
+        if (!isRuleEnabled(ctx, "queue-depth"))
+            return null;
         const queued = event.queueDepth ?? 0;
         const threshold = getRuleThreshold(ctx, "queue-depth", 10);
         if (queued < threshold)
@@ -198,11 +201,15 @@ const highErrorRate = {
     defaultCooldownMs: 30 * 60 * 1000,
     defaultThreshold: 50, // percent
     evaluate(event, ctx) {
-        if (event.type !== "llm.call")
+        if (event.type !== "llm.call" && event.type !== "llm.error" && event.type !== "agent.error")
             return null;
         if (!isRuleEnabled(ctx, "high-error-rate"))
             return null;
-        const isError = event.outcome === "error";
+        // agent.error and llm.error are always errors; llm.call checks outcome (timeout counts as error)
+        const isError = event.type === "agent.error" ||
+            event.type === "llm.error" ||
+            event.outcome === "error" ||
+            event.outcome === "timeout";
         pushWindow(ctx, "msg-outcomes", { ts: ctx.now, value: isError ? 1 : 0 });
         const window = ctx.state.windows.get("msg-outcomes");
         if (!window || window.length < 20)
@@ -227,11 +234,41 @@ const highErrorRate = {
         };
     },
 };
+// ─── Rule: tool-errors ───────────────────────────────────────────────────
+const toolErrors = {
+    id: "tool-errors",
+    defaultCooldownMs: 15 * 60 * 1000,
+    defaultThreshold: 1, // 1 tool error in 1 minute
+    evaluate(event, ctx) {
+        if (event.type !== "tool.error")
+            return null;
+        if (!isRuleEnabled(ctx, "tool-errors"))
+            return null;
+        pushWindow(ctx, "tool-errors", { ts: ctx.now });
+        const threshold = getRuleThreshold(ctx, "tool-errors", 1);
+        const windowMs = 60 * 1000; // 1 minute
+        const count = countInWindow(ctx, "tool-errors", windowMs);
+        if (count < threshold)
+            return null;
+        const toolName = event.meta?.toolName ?? "unknown";
+        const fingerprint = `tool-errors:${toolName}`;
+        return {
+            type: "alert",
+            id: makeAlertId("tool-errors", fingerprint, ctx.now),
+            ruleId: "tool-errors",
+            severity: "warn",
+            title: "Tool errors spike",
+            detail: `${count} tool error(s) in the last minute.${event.error ? ` Last: ${event.error}` : ""}`,
+            ts: ctx.now,
+            fingerprint,
+        };
+    },
+};
 // ─── Rule: gateway-down ──────────────────────────────────────────────────────
 const gatewayDown = {
     id: "gateway-down",
     defaultCooldownMs: 60 * 60 * 1000,
-    defaultThreshold: 90_000, // 90 seconds
+    defaultThreshold: 30_000, // 30 seconds
     evaluate(event, ctx) {
         // This rule is called by the watchdog timer, not by events directly.
         if (event.type !== "watchdog.tick")
@@ -270,5 +307,6 @@ export const ALL_RULES = [
     heartbeatFail,
     queueDepth,
     highErrorRate,
+    toolErrors,
     gatewayDown,
 ];

package/dist/core/types.d.ts

@@ -51,6 +51,8 @@ export type AlertTarget = {
     to: string;
     accountId?: string;
 };
+/** Enriches an alert with LLM-generated summary/action. Returns enriched alert or null to skip. */
+export type AlertEnricher = (alert: AlertEvent) => Promise<AlertEvent | null>;
 export type RuleOverride = {
     enabled?: boolean;
     threshold?: number;
@@ -65,6 +67,7 @@ export type MonitorConfig = {
     maxLogSizeKb?: number;
     maxLogAgeDays?: number;
     quiet?: boolean;
+    llmEnriched?: boolean;
     rules?: Record<string, RuleOverride>;
 };
 export type OpenAlertsInitOptions = {
@@ -80,6 +83,8 @@ export type OpenAlertsInitOptions = {
     logPrefix?: string;
     /** Diagnosis hint shown in critical alerts (e.g., 'Run "openclaw doctor"') */
     diagnosisHint?: string;
+    /** Optional LLM enricher — adds smart summaries to alerts before dispatch */
+    enricher?: AlertEnricher;
 };
 export type OpenAlertsLogger = {
     info: (msg: string) => void;
@@ -148,5 +153,5 @@ export declare const DEFAULTS: {
     readonly pruneIntervalMs: number;
     readonly platformFlushIntervalMs: number;
     readonly platformBatchSize: 100;
-    readonly gatewayDownThresholdMs: 90000;
+    readonly gatewayDownThresholdMs: 30000;
 };

package/dist/core/types.js

@@ -13,5 +13,5 @@ export const DEFAULTS = {
     pruneIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
     platformFlushIntervalMs: 5 * 60 * 1000, // 5 minutes
     platformBatchSize: 100,
-    gatewayDownThresholdMs: 90_000, // 90 seconds
+    gatewayDownThresholdMs: 30_000, // 30 seconds
 };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { OpenAlertsEngine } from "./core/index.js";
 import { onDiagnosticEvent, registerLogTransport } from "openclaw/plugin-sdk";
 import { createLogBridge } from "./plugin/log-bridge.js";
-import { OpenClawAlertChannel, parseConfig, resolveAlertTarget, translateOpenClawEvent, translateToolCallHook, translateAgentStartHook, translateAgentEndHook, translateSessionStartHook, translateSessionEndHook, translateMessageSentHook, translateMessageReceivedHook, translateBeforeToolCallHook, translateBeforeCompactionHook, translateAfterCompactionHook, translateMessageSendingHook, translateToolResultPersistHook, translateGatewayStartHook, translateGatewayStopHook, } from "./plugin/adapter.js";
+import { OpenClawAlertChannel, createOpenClawEnricher, parseConfig, resolveAlertTarget, translateOpenClawEvent, translateToolCallHook, translateAgentStartHook, translateAgentEndHook, translateSessionStartHook, translateSessionEndHook, translateMessageSentHook, translateMessageReceivedHook, translateBeforeToolCallHook, translateBeforeCompactionHook, translateAfterCompactionHook, translateMessageSendingHook, translateToolResultPersistHook, translateGatewayStartHook, translateGatewayStopHook, } from "./plugin/adapter.js";
 import { bindEngine, createMonitorCommands } from "./plugin/commands.js";
 import { createDashboardHandler, closeDashboardConnections, } from "./plugin/dashboard-routes.js";
 const PLUGIN_ID = "openalerts";
@@ -13,12 +13,16 @@ let logBridgeCleanup = null;
 function createMonitorService(api) {
     return {
         id: PLUGIN_ID,
-        start(ctx) {
+        async start(ctx) {
             const logger = ctx.logger;
             const config = parseConfig(api.pluginConfig);
             // Resolve alert target + create OpenClaw alert channel
-            const target = resolveAlertTarget(api, config);
+            const target = await resolveAlertTarget(api, config);
             const channels = target ? [new OpenClawAlertChannel(api, target)] : [];
+            // Create LLM enricher if enabled (default: false)
+            const enricher = config.llmEnriched === true
+                ? createOpenClawEnricher(api, logger)
+                : null;
             // Create and start the universal engine
             engine = new OpenAlertsEngine({
                 stateDir: ctx.stateDir,
@@ -27,6 +31,7 @@ function createMonitorService(api) {
                 logger,
                 logPrefix: LOG_PREFIX,
                 diagnosisHint: 'Run "openclaw doctor" to diagnose.',
+                enricher: enricher ?? undefined,
             });
             engine.start();
             // Wire commands to engine
@@ -169,7 +174,7 @@ function createMonitorService(api) {
             const targetDesc = target
                 ? `alerting to ${target.channel}:${target.to}`
                 : "log-only (no alert channel detected)";
-            logger.info(`${LOG_PREFIX}: started, ${targetDesc}, log-bridge active, 7 rules active`);
+            logger.info(`${LOG_PREFIX}: started, ${targetDesc}, log-bridge active, 8 rules active`);
         },
         stop() {
             closeDashboardConnections();

package/dist/plugin/adapter.d.ts

@@ -1,4 +1,4 @@
-import type { AlertChannel, AlertEvent, AlertTarget, MonitorConfig, OpenAlertsEvent } from "../core/index.js";
+import type { AlertChannel, AlertEnricher, AlertEvent, AlertTarget, MonitorConfig, OpenAlertsEvent } from "../core/index.js";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 /**
  * Translate an OpenClaw diagnostic event into a universal OpenAlertsEvent.
@@ -128,11 +128,23 @@ export declare class OpenClawAlertChannel implements AlertChannel {
     readonly name: string;
     private api;
     private target;
+    private warnedMissing;
     constructor(api: OpenClawPluginApi, target: AlertTarget);
     send(alert: AlertEvent, formatted: string): Promise<void>;
 }
 /**
  * Resolve the alert target from plugin config or by auto-detecting from OpenClaw config.
  */
-export declare function resolveAlertTarget(api: OpenClawPluginApi, pluginConfig: MonitorConfig): AlertTarget | null;
+export declare function resolveAlertTarget(api: OpenClawPluginApi, pluginConfig: MonitorConfig): Promise<AlertTarget | null>;
 export declare function parseConfig(raw: Record<string, unknown> | undefined): MonitorConfig;
+/**
+ * Create an AlertEnricher from the OpenClaw plugin API.
+ * Reads the model from api.config.agents.defaults.model.primary (e.g. "openai/gpt-5-nano")
+ * and resolves the API key from process.env.
+ * Returns null if no model is configured or enricher can't be created.
+ */
+export declare function createOpenClawEnricher(api: OpenClawPluginApi, logger?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}): AlertEnricher | null;

package/dist/plugin/adapter.js

@@ -1,3 +1,7 @@
+import { createLlmEnricher, resolveApiKeyEnvVar } from "../core/llm-enrichment.js";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
 // ─── Diagnostic Event Translation ───────────────────────────────────────────
 //
 // OpenClaw emits 12 diagnostic event types through onDiagnosticEvent():
@@ -230,7 +234,7 @@ export function translateMessageSentHook(data, context) {
         sessionKey: context.sessionId,
         outcome: data.success ? "success" : "error",
         error: data.error,
-        meta: { to: data.to, source: "hook:message_sent" },
+        meta: { to: data.to, content: data.content, source: "hook:message_sent" },
     };
 }
 /** Translate gateway_start hook data into OpenAlertsEvent. */
@@ -261,6 +265,7 @@ export function translateMessageReceivedHook(data, context) {
         outcome: "success",
         meta: {
             from: data.from,
+            content: data.content,
             accountId: context.accountId,
             openclawHook: "message_received",
             source: "hook:message_received",
@@ -310,6 +315,7 @@ export function translateAfterCompactionHook(data, context) {
             messageCount: data.messageCount,
             tokenCount: data.tokenCount,
             compactedCount: data.compactedCount,
+            compaction: true,
             openclawHook: "after_compaction",
             source: "hook:after_compaction",
         },
@@ -324,6 +330,7 @@ export function translateMessageSendingHook(data, context) {
         outcome: "success",
         meta: {
             to: data.to,
+            content: data.content,
             accountId: context.accountId,
             openclawHook: "message_sending",
             source: "hook:message_sending",
@@ -356,6 +363,7 @@ export class OpenClawAlertChannel {
     name;
     api;
     target;
+    warnedMissing = false;
     constructor(api, target) {
         this.api = api;
         this.target = target;
@@ -364,8 +372,13 @@ export class OpenClawAlertChannel {
     async send(alert, formatted) {
         const runtime = this.api.runtime;
         const channel = runtime.channel;
-        if (!channel)
+        if (!channel) {
+            if (!this.warnedMissing) {
+                this.warnedMissing = true;
+                throw new Error(`runtime.channel not available — alert dropped`);
+            }
             return;
+        }
         const opts = this.target.accountId
             ? { accountId: this.target.accountId }
             : {};
@@ -377,20 +390,22 @@ export class OpenClawAlertChannel {
             signal: "sendMessageSignal",
         };
         const methodName = channelMethods[this.target.channel];
-        if (!methodName)
-            return;
+        if (!methodName) {
+            throw new Error(`unsupported channel "${this.target.channel}" — no send method mapped`);
+        }
         const channelMod = channel[this.target.channel];
         const sendFn = channelMod?.[methodName];
-        if (sendFn) {
-            await sendFn(this.target.to, formatted, opts);
+        if (!sendFn) {
+            throw new Error(`${this.target.channel}.${methodName} not found on runtime — alert dropped`);
         }
+        await sendFn(this.target.to, formatted, opts);
     }
 }
 // ─── Alert Target Resolution ────────────────────────────────────────────────
 /**
  * Resolve the alert target from plugin config or by auto-detecting from OpenClaw config.
  */
-export function resolveAlertTarget(api, pluginConfig) {
+export async function resolveAlertTarget(api, pluginConfig) {
     // 1. Explicit config
     if (pluginConfig.alertChannel && pluginConfig.alertTo) {
         return {
@@ -400,7 +415,8 @@ export function resolveAlertTarget(api, pluginConfig) {
         };
     }
     const cfg = api.config;
-    // 2. Auto-detect from configured channels
+    const channelsCfg = cfg.channels ??
+        {};
     const channelKeys = [
         "telegram",
         "discord",
@@ -408,14 +424,33 @@ export function resolveAlertTarget(api, pluginConfig) {
         "whatsapp",
         "signal",
     ];
+    // 2. Auto-detect from static allowFrom in channel config
     for (const channelKey of channelKeys) {
-        const channelConfig = cfg[channelKey];
+        const channelConfig = channelsCfg[channelKey];
         if (!channelConfig || typeof channelConfig !== "object")
             continue;
         const target = extractFirstAllowFrom(channelKey, channelConfig);
         if (target)
             return target;
     }
+    // 3. Auto-detect from pairing store (runtime-paired users)
+    // The store lives at ~/.openclaw/credentials/<channel>-allowFrom.json
+    const credDir = join(process.env.OPENCLAW_HOME ?? join(homedir(), ".openclaw"), "credentials");
+    for (const channelKey of channelKeys) {
+        const channelConfig = channelsCfg[channelKey];
+        if (!channelConfig || typeof channelConfig !== "object")
+            continue;
+        try {
+            const raw = await readFile(join(credDir, `${channelKey}-allowFrom.json`), "utf-8");
+            const data = JSON.parse(raw);
+            if (Array.isArray(data.allowFrom) && data.allowFrom.length > 0) {
+                return { channel: channelKey, to: String(data.allowFrom[0]) };
+            }
+        }
+        catch {
+            // File doesn't exist or isn't valid — skip this channel
+        }
+    }
     return null;
 }
 function extractFirstAllowFrom(channel, channelConfig) {
@@ -451,8 +486,45 @@ export function parseConfig(raw) {
         maxLogSizeKb: typeof raw.maxLogSizeKb === "number" ? raw.maxLogSizeKb : undefined,
         maxLogAgeDays: typeof raw.maxLogAgeDays === "number" ? raw.maxLogAgeDays : undefined,
         quiet: typeof raw.quiet === "boolean" ? raw.quiet : undefined,
+        llmEnriched: typeof raw.llmEnriched === "boolean" ? raw.llmEnriched : undefined,
         rules: raw.rules && typeof raw.rules === "object"
             ? raw.rules
             : undefined,
     };
 }
+// ─── LLM Enricher Factory ───────────────────────────────────────────────────
+/**
+ * Create an AlertEnricher from the OpenClaw plugin API.
+ * Reads the model from api.config.agents.defaults.model.primary (e.g. "openai/gpt-5-nano")
+ * and resolves the API key from process.env.
+ * Returns null if no model is configured or enricher can't be created.
+ */
+export function createOpenClawEnricher(api, logger) {
+    try {
+        const cfg = api.config;
+        const agents = cfg.agents;
+        const defaults = agents?.defaults;
+        const model = defaults?.model;
+        const primary = model?.primary;
+        if (typeof primary !== "string" || !primary.includes("/")) {
+            logger?.warn("openalerts: llm-enrichment skipped — no model configured at agents.defaults.model.primary");
+            return null;
+        }
+        // Resolve API key here (in adapter) to keep env access separate from network calls
+        const envVar = resolveApiKeyEnvVar(primary);
+        if (!envVar) {
+            logger?.warn("openalerts: llm-enrichment skipped — unknown provider");
+            return null;
+        }
+        const apiKey = process.env[envVar];
+        if (!apiKey) {
+            logger?.warn(`openalerts: llm-enrichment skipped — ${envVar} not set in environment`);
+            return null;
+        }
+        return createLlmEnricher({ modelString: primary, apiKey, logger });
+    }
+    catch (err) {
+        logger?.warn(`openalerts: llm-enrichment setup failed: ${String(err)}`);
+        return null;
+    }
+}

package/dist/plugin/commands.js

@@ -29,7 +29,7 @@ export function createMonitorCommands(api) {
             handler: () => handleDashboard(),
         },
         {
-            name: "test-alert",
+            name: "test_alert",
             description: "Send a test alert to verify alert delivery",
             acceptsArgs: false,
             handler: () => handleTestAlert(),
@@ -72,26 +72,7 @@ function handleTestAlert() {
     if (!_engine) {
         return { text: "OpenAlerts not initialized yet. Wait for gateway startup." };
     }
-    // Ingest a synthetic infra.error to trigger the infra-errors rule evaluation.
-    // This won't fire an actual alert unless the threshold (3 errors) is reached,
-    // so we fire a one-off test alert directly through the engine.
-    const testEvent = {
-        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`,
-    };
-    // Ingest as a custom event so it appears in the dashboard
-    _engine.ingest({
-        type: "custom",
-        ts: Date.now(),
-        outcome: "success",
-        meta: { openclawLog: "test_alert", source: "command:test-alert" },
-    });
+    _engine.sendTestAlert();
     return {
         text: "Test alert sent. Check your alert channel (Telegram/Discord/etc) for delivery confirmation.\n\nIf you don't receive it, check /health for channel status.",
     };