@steadwing/openalerts 0.2.3 → 0.2.5

package/dist/plugin/dashboard-routes.js

@@ -2,10 +2,42 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { DEFAULTS } from "../core/index.js";
 import { getDashboardHtml } from "./dashboard-html.js";
-// ─── SSE connection tracking ─────────────────────────────────────────────────
 const sseConnections = new Set();
-/** Close all active SSE connections. Call on engine stop. */
+const monitorListeners = new Set();
+const monitorConnections = new Set();
+// Ring buffer — last 150 agent monitor events for history replay
+const agentMonitorBuffer = [];
+const AGENT_MONITOR_BUF_SIZE = 150;
+export function emitAgentMonitorEvent(event) {
+    // Store in ring buffer
+    agentMonitorBuffer.push(event);
+    if (agentMonitorBuffer.length > AGENT_MONITOR_BUF_SIZE)
+        agentMonitorBuffer.shift();
+    for (const fn of monitorListeners) {
+        try {
+            fn(event);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ── Gateway event recorder ──────────────────────────────────────────────────
+const recentGatewayEvents = [];
+export function recordGatewayEvent(eventName, payload) {
+    recentGatewayEvents.unshift({ eventName, payload, ts: Date.now() });
+    while (recentGatewayEvents.length > 10) {
+        recentGatewayEvents.pop();
+    }
+}
 export function closeDashboardConnections() {
+    for (const conn of monitorConnections) {
+        clearInterval(conn.heartbeat);
+        try {
+            conn.res.end();
+        }
+        catch { /* ignore */ }
+    }
+    monitorConnections.clear();
+    monitorListeners.clear();
     for (const conn of sseConnections) {
         clearInterval(conn.heartbeat);
         clearInterval(conn.logTailer);
@@ -27,6 +59,8 @@ const RULE_IDS = [
     "heartbeat-fail",
     "queue-depth",
     "high-error-rate",
+    "cost-hourly-spike",
+    "cost-daily-budget",
     "tool-errors",
     "gateway-down",
 ];
@@ -195,7 +229,7 @@ function createLogTailer(res) {
     }, 2000);
 }
 // ─── HTTP Handler ────────────────────────────────────────────────────────────
-export function createDashboardHandler(getEngine) {
+export function createDashboardHandler(getEngine, getCollections) {
     return async (req, res) => {
         const url = req.url ?? "";
         if (!url.startsWith("/openalerts"))
@@ -307,6 +341,27 @@ export function createDashboardHandler(getEngine) {
             res.end(body);
             return true;
         }
+        // ── GET /openalerts/collections → Sessions, actions, execs from CollectionManager ────
+        if (url === "/openalerts/collections" && req.method === "GET") {
+            const collections = getCollections();
+            if (!collections) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Collections not available" }));
+                return true;
+            }
+            // getActiveSessions filters out stale idle sessions (>2h inactive) from filesystem hydration
+            const sessions = collections.getActiveSessions();
+            const actions = collections.getActions();
+            const execs = collections.getExecs();
+            const stats = collections.getStats();
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Cache-Control": "no-cache",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.end(JSON.stringify({ sessions, actions, execs, stats }));
+            return true;
+        }
         // ── GET /openalerts/logs → OpenClaw log entries (for Logs tab) ────
         if (url.startsWith("/openalerts/logs") && req.method === "GET") {
             const urlObj = new URL(url, "http://localhost");
@@ -328,6 +383,59 @@ export function createDashboardHandler(getEngine) {
             }));
             return true;
         }
+        // ── GET /openalerts/agent-monitor/stream → Live agent activity SSE ────
+        // Receives events from plugin hooks (before_agent_start, agent_end, after_tool_call, message_received)
+        if (url === "/openalerts/agent-monitor/stream" && req.method === "GET") {
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.flushHeaders();
+            res.write(`:ok\n\n`);
+            // Replay buffered events so client sees full current session history
+            if (agentMonitorBuffer.length > 0) {
+                try {
+                    res.write(`event: history\ndata: ${JSON.stringify(agentMonitorBuffer)}\n\n`);
+                }
+                catch { /* closed before flush */ }
+            }
+            const listener = (event) => {
+                try {
+                    res.write(`event: ${event.type}\ndata: ${JSON.stringify(event.data)}\n\n`);
+                }
+                catch { /* closed */ }
+            };
+            monitorListeners.add(listener);
+            const heartbeat = setInterval(() => {
+                try {
+                    res.write(`:heartbeat\n\n`);
+                }
+                catch { /* closed */ }
+            }, 15_000);
+            const conn = { res, heartbeat };
+            monitorConnections.add(conn);
+            req.on("close", () => {
+                clearInterval(heartbeat);
+                monitorListeners.delete(listener);
+                monitorConnections.delete(conn);
+            });
+            return true;
+        }
+        // ── GET /openalerts/test/events → Last 10 gateway events ────
+        if (url === "/openalerts/test/events" && req.method === "GET") {
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Cache-Control": "no-cache",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.end(JSON.stringify({
+                count: recentGatewayEvents.length,
+                events: recentGatewayEvents,
+            }));
+            return true;
+        }
         // Unknown /openalerts sub-route
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");

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,200 @@
+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;
+            // Gateway sends 'connect.challenge' event first
+        });
+        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: "cli",
+                    displayName: "OpenAlerts Monitor",
+                    version: "0.1.0",
+                    platform: process.platform,
+                    mode: "cli",
+                },
+                role: "operator",
+                scopes: ["operator.read"],
+                caps: [],
+                commands: [],
+                permissions: {},
+                locale: "en-US",
+                userAgent: "openalerts-monitor/0.1.0",
+                auth: this.config.token ? { token: this.config.token } : undefined,
+            },
+        };
+        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);
+            // Handle challenge-response auth
+            if (frame.type === "event" && frame.event === "connect.challenge") {
+                this.sendConnectHandshake();
+                return;
+            }
+            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/openclaw.plugin.json

@@ -14,6 +14,26 @@
 			"quiet": { "type": "boolean" },
 			"rules": {
 				"type": "object",
+				"properties": {
+					"cost-hourly-spike": {
+						"type": "object",
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"threshold": { "type": "number", "minimum": 0 },
+							"cooldownMinutes": { "type": "number", "minimum": 1 }
+						},
+						"additionalProperties": false
+					},
+					"cost-daily-budget": {
+						"type": "object",
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"threshold": { "type": "number", "minimum": 0 },
+							"cooldownMinutes": { "type": "number", "minimum": 1 }
+						},
+						"additionalProperties": false
+					}
+				},
 				"additionalProperties": {
 					"type": "object",
 					"properties": {
@@ -52,6 +72,16 @@
 		"quiet": {
 			"label": "Quiet Mode",
 			"help": "Log alerts to file only — no messages sent to your channels."
+		},
+		"rules.cost-hourly-spike.threshold": {
+			"label": "Hourly Cost Threshold (USD)",
+			"help": "Alert when total LLM spend in the last 60 minutes exceeds this amount. Default: 5.0.",
+			"advanced": true
+		},
+		"rules.cost-daily-budget.threshold": {
+			"label": "Daily Budget Threshold (USD)",
+			"help": "Alert when total LLM spend in the last 24 hours exceeds this amount. Default: 20.0.",
+			"advanced": true
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steadwing/openalerts",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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"
   },