@steadwing/openalerts 0.2.3 → 0.2.4

package/README.md

@@ -9,6 +9,7 @@
   <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>
+  <a href="https://discord.gg/4rUP86tSXn"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat" alt="Discord"></a>
 </p>
 
 <p align="center">
@@ -28,6 +29,7 @@ OpenAlerts watches your agent in real-time and alerts you the moment something g
 ## Quickstart
 
 > Currently supports OpenClaw. More framework adapters coming soon.
+> This project is under revamp for the next few hours
 
 ### 1. Install
 
@@ -43,17 +45,17 @@ Otherwise, set it explicitly in `openclaw.json`:
 
 ```jsonc
 {
-  "plugins": {
-    "entries": {
-      "openalerts": {
-        "enabled": true,
-        "config": {
-          "alertChannel": "telegram",  // telegram | discord | slack | whatsapp | signal
-          "alertTo": "YOUR_CHAT_ID"
-        }
-      }
-    }
-  }
+	"plugins": {
+		"entries": {
+			"openalerts": {
+				"enabled": true,
+				"config": {
+					"alertChannel": "telegram", // telegram | discord | slack | whatsapp | signal
+					"alertTo": "YOUR_CHAT_ID",
+				},
+			},
+		},
+	},
 }
 ```
 
@@ -65,11 +67,14 @@ Otherwise, set it explicitly in `openclaw.json`:
 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.
 
+## Demo
+
+https://github.com/user-attachments/assets/0b6ed26e-1eb0-47b2-ae4f-947516f024b4
+
 ## Dashboard
 
 A real-time web dashboard is embedded in the gateway at:
@@ -86,18 +91,19 @@ http://127.0.0.1:18789/openalerts
 
 Eight rules run against every event in real-time. All thresholds and cooldowns are configurable.
 
-| 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 |
+| 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        |
 
 Every rule also accepts:
+
 - **`enabled`** — `false` to disable the rule (default: `true`)
 - **`cooldownMinutes`** — minutes before the same rule can fire again (default: `15`)
 
@@ -105,21 +111,21 @@ To tune rules, add a `rules` object in your plugin config:
 
 ```jsonc
 {
-  "plugins": {
-    "entries": {
-      "openalerts": {
-        "config": {
-          "cooldownMinutes": 10,
-          "rules": {
-            "llm-errors": { "threshold": 5 },
-            "infra-errors": { "cooldownMinutes": 30 },
-            "high-error-rate": { "enabled": false },
-            "gateway-down": { "threshold": 60000 }
-          }
-        }
-      }
-    }
-  }
+	"plugins": {
+		"entries": {
+			"openalerts": {
+				"config": {
+					"cooldownMinutes": 10,
+					"rules": {
+						"llm-errors": { "threshold": 5 },
+						"infra-errors": { "cooldownMinutes": 30 },
+						"high-error-rate": { "enabled": false },
+						"gateway-down": { "threshold": 60000 },
+					},
+				},
+			},
+		},
+	},
 }
 ```
 
@@ -131,15 +137,15 @@ OpenAlerts can optionally use your configured LLM to enrich alerts with a human-
 
 ```jsonc
 {
-  "plugins": {
-    "entries": {
-      "openalerts": {
-        "config": {
-          "llmEnriched": true
-        }
-      }
-    }
-  }
+	"plugins": {
+		"entries": {
+			"openalerts": {
+				"config": {
+					"llmEnriched": true,
+				},
+			},
+		},
+	},
 }
 ```
 
@@ -161,11 +167,11 @@ Action: Update your API key in ~/.openclaw/.env with a valid key from platform.o
 
 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 |
+| 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                             |
 
 ## Roadmap
 

package/dist/plugin/gateway-client.d.ts

@@ -0,0 +1,39 @@
+import EventEmitter from "eventemitter3";
+interface GatewayClientConfig {
+    url: string;
+    token: string;
+    reconnectInterval: number;
+    maxRetries: number;
+}
+/**
+ * WebSocket client for OpenClaw Gateway
+ * - Connects to ws://127.0.0.1:18789
+ * - Handles JSON-RPC requests/responses
+ * - Emits events: agent, health, cron, chat
+ * - Auto-reconnects on disconnect
+ */
+export declare class GatewayClient extends EventEmitter {
+    private ws;
+    private config;
+    private pending;
+    private backoffMs;
+    private closed;
+    private connectTimer;
+    private ready;
+    constructor(config?: Partial<GatewayClientConfig>);
+    start(): void;
+    stop(): void;
+    isReady(): boolean;
+    private doConnect;
+    private sendConnectHandshake;
+    private handleMessage;
+    /**
+     * Send RPC request to gateway
+     * @example
+     * const cost = await client.request("usage.cost", { period: "day" });
+     * const sessions = await client.request("sessions.list");
+     */
+    request<T = unknown>(method: string, params?: unknown): Promise<T>;
+    private scheduleReconnect;
+}
+export {};

package/dist/plugin/gateway-client.js

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+import EventEmitter from "eventemitter3";
+/**
+ * WebSocket client for OpenClaw Gateway
+ * - Connects to ws://127.0.0.1:18789
+ * - Handles JSON-RPC requests/responses
+ * - Emits events: agent, health, cron, chat
+ * - Auto-reconnects on disconnect
+ */
+export class GatewayClient extends EventEmitter {
+    ws = null;
+    config;
+    pending = new Map();
+    backoffMs = 1000;
+    closed = false;
+    connectTimer = null;
+    ready = false;
+    constructor(config) {
+        super();
+        this.config = {
+            url: config?.url ?? "ws://127.0.0.1:18789",
+            token: config?.token ?? "",
+            reconnectInterval: config?.reconnectInterval ?? 1000,
+            maxRetries: config?.maxRetries ?? 60,
+        };
+    }
+    start() {
+        if (this.closed) {
+            return;
+        }
+        this.doConnect();
+    }
+    stop() {
+        this.closed = true;
+        if (this.connectTimer) {
+            clearTimeout(this.connectTimer);
+            this.connectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    isReady() {
+        return this.ready;
+    }
+    doConnect() {
+        if (this.closed || this.ws) {
+            return;
+        }
+        this.ws = new WebSocket(this.config.url, {
+            maxPayload: 25 * 1024 * 1024,
+        });
+        this.ws.on("open", () => {
+            this.backoffMs = 1000;
+            // Delay connect handshake slightly to allow gateway to send challenge
+            setTimeout(() => this.sendConnectHandshake(), 800);
+        });
+        this.ws.on("message", (data) => {
+            this.handleMessage(data.toString());
+        });
+        this.ws.on("error", (err) => {
+            this.emit("error", err);
+        });
+        this.ws.on("close", () => {
+            this.ws = null;
+            this.ready = false;
+            this.emit("disconnected");
+            if (!this.closed) {
+                this.scheduleReconnect();
+            }
+        });
+    }
+    sendConnectHandshake() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        const id = randomUUID();
+        const frame = {
+            type: "req",
+            id,
+            method: "connect",
+            params: {
+                minProtocol: 3,
+                maxProtocol: 3,
+                client: {
+                    id: "gateway-client",
+                    displayName: "OpenAlerts Monitor",
+                    version: "0.1.0",
+                    platform: process.platform,
+                    mode: "backend",
+                },
+                role: "operator",
+                scopes: ["operator.admin"],
+                auth: {
+                    token: this.config.token,
+                },
+            },
+        };
+        this.pending.set(id, {
+            resolve: (result) => {
+                this.ready = true;
+                this.emit("ready", result);
+            },
+            reject: (err) => {
+                this.emit("error", new Error(`Connect handshake failed: ${err.message}`));
+            },
+        });
+        this.ws.send(JSON.stringify(frame));
+    }
+    handleMessage(raw) {
+        try {
+            const frame = JSON.parse(raw);
+            if (frame.type === "res") {
+                const pending = this.pending.get(frame.id);
+                if (pending) {
+                    if (frame.error || frame.ok === false) {
+                        const errMsg = typeof frame.error === "string"
+                            ? frame.error
+                            : typeof frame.payload === "object" &&
+                                frame.payload &&
+                                "message" in frame.payload
+                                ? String(frame.payload.message)
+                                : JSON.stringify(frame.error ?? frame.payload);
+                        pending.reject(new Error(errMsg));
+                    }
+                    else {
+                        pending.resolve(frame.payload ?? frame.result);
+                    }
+                    this.pending.delete(frame.id);
+                }
+            }
+            else if (frame.type === "event") {
+                // Emit the event for subscribers: agent, health, cron, chat
+                this.emit(frame.event, frame.payload);
+            }
+        }
+        catch (err) {
+            this.emit("error", new Error(`Failed to parse frame: ${err}`));
+        }
+    }
+    /**
+     * Send RPC request to gateway
+     * @example
+     * const cost = await client.request("usage.cost", { period: "day" });
+     * const sessions = await client.request("sessions.list");
+     */
+    request(method, params) {
+        if (!this.ready || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new Error("Gateway not ready"));
+        }
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Request timeout: ${method}`));
+            }, 10000);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timeout);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    reject(err);
+                },
+            });
+            const frame = {
+                type: "req",
+                id,
+                method,
+                params,
+            };
+            if (!this.ws) {
+                this.pending.delete(id);
+                clearTimeout(timeout);
+                reject(new Error("WebSocket not connected"));
+                return;
+            }
+            this.ws.send(JSON.stringify(frame));
+        });
+    }
+    scheduleReconnect() {
+        if (this.connectTimer) {
+            clearTimeout(this.connectTimer);
+        }
+        this.connectTimer = setTimeout(() => {
+            this.backoffMs = Math.min(this.backoffMs * 2, 60000);
+            this.doConnect();
+        }, this.backoffMs);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steadwing/openalerts",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "OpenAlerts — An alerting layer for agentic frameworks",
   "author": "Steadwing",
@@ -21,10 +21,15 @@
     "publish": "npm publish",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "eventemitter3": "^5.0.1",
+    "ws": "^8.18.0"
+  },
   "peerDependencies": {
     "openclaw": "*"
   },
   "devDependencies": {
+    "@types/ws": "^8.5.13",
     "typescript": "^5.9.3"
   },
   "openclaw": {
@@ -36,7 +41,18 @@
   },
   "homepage": "https://github.com/steadwing/openalerts#readme",
   "bugs": "https://github.com/steadwing/openalerts/issues",
-  "keywords": ["openalerts", "openclaw", "monitoring", "alerting", "plugin"],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "alerting",
+    "monitoring",
+    "observability",
+    "llm-monitoring",
+    "agent-monitoring",
+    "ai-agents",
+    "real-time-alerts",
+    "error-tracking"
+  ],
   "engines": {
     "node": ">=18"
   },