@steadwing/openalerts 0.2.6 → 0.2.8

package/dist/plugin/dashboard-routes.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenAlertsEngine } from "../core/index.js";
+type HttpHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean;
+type AgentMonitorEvent = {
+    type: string;
+    data: unknown;
+};
+export declare function emitAgentMonitorEvent(event: AgentMonitorEvent): void;
+export declare function recordGatewayEvent(eventName: string, payload: unknown): void;
+export declare function closeDashboardConnections(): void;
+export declare function createDashboardHandler(getEngine: () => OpenAlertsEngine | null, getCollections: () => unknown): HttpHandler;
+export {};

package/dist/plugin/dashboard-routes.js

@@ -0,0 +1,444 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULTS } from "../core/index.js";
+import { getDashboardHtml } from "./dashboard-html.js";
+const sseConnections = new Set();
+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);
+        conn.unsub();
+        try {
+            conn.res.end();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+    sseConnections.clear();
+}
+// ─── Rule status helper ──────────────────────────────────────────────────────
+const RULE_IDS = [
+    "infra-errors",
+    "llm-errors",
+    "session-stuck",
+    "heartbeat-fail",
+    "queue-depth",
+    "high-error-rate",
+    "cost-hourly-spike",
+    "cost-daily-budget",
+    "tool-errors",
+    "gateway-down",
+];
+function getRuleStatuses(engine) {
+    const state = engine.state;
+    const now = Date.now();
+    const cooldownWindow = 15 * 60 * 1000;
+    return RULE_IDS.map((id) => {
+        // For gateway-down, reflect current condition: if heartbeats have resumed,
+        // show OK even if the rule fired recently.
+        if (id === "gateway-down") {
+            const silenceMs = state.lastHeartbeatTs > 0
+                ? now - state.lastHeartbeatTs
+                : 0;
+            const isCurrentlyDown = state.lastHeartbeatTs > 0 &&
+                silenceMs >= DEFAULTS.gatewayDownThresholdMs;
+            return { id, status: isCurrentlyDown ? "fired" : "ok" };
+        }
+        // Cooldown keys are fingerprints like "llm-errors:unknown", not bare rule IDs.
+        // Check if ANY cooldown key starting with this rule ID has fired recently.
+        let fired = false;
+        for (const [key, ts] of state.cooldowns) {
+            if (key === id || key.startsWith(id + ":")) {
+                if (ts > now - cooldownWindow) {
+                    fired = true;
+                    break;
+                }
+            }
+        }
+        return { id, status: fired ? "fired" : "ok" };
+    });
+}
+// ─── OpenClaw log file ──────────────────────────────────────────────────────
+function getOpenClawLogDir() {
+    // Use platform-appropriate default: C:\tmp\openclaw on Windows, /tmp/openclaw elsewhere
+    if (process.platform === "win32") {
+        return join("C:", "tmp", "openclaw");
+    }
+    return join("/tmp", "openclaw");
+}
+function getOpenClawLogPath() {
+    const d = new Date();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return join(getOpenClawLogDir(), `openclaw-${y}-${m}-${day}.log`);
+}
+/** Parse key=value pairs from a log message string. */
+function parseLogKVs(msg) {
+    const kvs = {};
+    // Match key=value or key="quoted value"
+    const re = /(\w+)=(?:"([^"]*)"|(\S+))/g;
+    let m;
+    while ((m = re.exec(msg)) !== null) {
+        kvs[m[1]] = m[2] ?? m[3];
+    }
+    return kvs;
+}
+function parseLogLine(line) {
+    try {
+        const obj = JSON.parse(line);
+        const ts = obj.time || obj._meta?.date || "";
+        const tsMs = ts ? new Date(ts).getTime() : 0;
+        let subsystem = "";
+        try {
+            const nameObj = JSON.parse(obj["0"] || "{}");
+            subsystem = nameObj.subsystem || "";
+        }
+        catch {
+            subsystem = obj["0"] || "";
+        }
+        const message = obj["1"] || "";
+        const extra = parseLogKVs(message);
+        return {
+            ts,
+            tsMs,
+            level: obj._meta?.logLevelName || "DEBUG",
+            subsystem,
+            message,
+            sessionId: extra.sessionId,
+            runId: extra.runId,
+            durationMs: extra.durationMs ? parseInt(extra.durationMs, 10) : undefined,
+            filePath: obj._meta?.path?.fileNameWithLine,
+            method: obj._meta?.path?.method,
+            hostname: obj._meta?.hostname,
+            extra,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readOpenClawLogs(maxEntries, afterTs) {
+    const logPath = getOpenClawLogPath();
+    if (!existsSync(logPath))
+        return { entries: [], truncated: false, subsystems: [] };
+    try {
+        const content = readFileSync(logPath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        const entries = [];
+        const subsystemSet = new Set();
+        for (const line of lines) {
+            const parsed = parseLogLine(line);
+            if (!parsed)
+                continue;
+            if (afterTs && parsed.ts <= afterTs)
+                continue;
+            entries.push(parsed);
+            subsystemSet.add(parsed.subsystem);
+        }
+        const truncated = maxEntries > 0 && entries.length > maxEntries;
+        const sliced = maxEntries > 0 ? entries.slice(-maxEntries) : entries;
+        const subsystems = Array.from(subsystemSet).sort();
+        return { entries: sliced, truncated, subsystems };
+    }
+    catch {
+        return { entries: [], truncated: false, subsystems: [] };
+    }
+}
+/**
+ * Create a log tailer for an SSE connection.
+ * Polls the log file every 2 seconds, sends new lines as `event: oclog`.
+ */
+function createLogTailer(res) {
+    let lastLineCount = 0;
+    let lastPath = "";
+    // Initialize: count existing lines so we only send new ones
+    try {
+        const path = getOpenClawLogPath();
+        if (existsSync(path)) {
+            const content = readFileSync(path, "utf-8");
+            lastLineCount = content.trim().split("\n").length;
+            lastPath = path;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return setInterval(() => {
+        try {
+            const path = getOpenClawLogPath();
+            if (!existsSync(path))
+                return;
+            // If date changed (new log file), reset counter
+            if (path !== lastPath) {
+                lastLineCount = 0;
+                lastPath = path;
+            }
+            const content = readFileSync(path, "utf-8");
+            const lines = content.trim().split("\n");
+            if (lines.length <= lastLineCount)
+                return;
+            // Send only new lines
+            const newLines = lines.slice(lastLineCount);
+            lastLineCount = lines.length;
+            for (const line of newLines) {
+                const parsed = parseLogLine(line);
+                if (!parsed)
+                    continue;
+                res.write(`event: oclog\ndata: ${JSON.stringify(parsed)}\n\n`);
+            }
+        }
+        catch {
+            /* ignore read errors */
+        }
+    }, 2000);
+}
+// ─── HTTP Handler ────────────────────────────────────────────────────────────
+export function createDashboardHandler(getEngine, getCollections) {
+    return async (req, res) => {
+        const url = req.url ?? "";
+        if (!url.startsWith("/openalerts"))
+            return false;
+        const engine = getEngine();
+        // ── GET /openalerts → Dashboard HTML ──────────────────────
+        if ((url === "/openalerts" || url === "/openalerts/") &&
+            req.method === "GET") {
+            if (!engine) {
+                res.writeHead(503, { "Content-Type": "text/plain" });
+                res.end("OpenAlerts engine not running.");
+                return true;
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-cache",
+            });
+            res.end(getDashboardHtml());
+            return true;
+        }
+        // ── GET /openalerts/events → SSE stream (engine events + log tailing) ──
+        if (url === "/openalerts/events" && req.method === "GET") {
+            if (!engine) {
+                res.writeHead(503, { "Content-Type": "text/plain" });
+                res.end("Engine not running.");
+                return true;
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.flushHeaders();
+            // Send initial connection event so the browser knows the stream is live
+            res.write(`:ok\n\n`);
+            // Send current state snapshot as initial event
+            const state = engine.state;
+            res.write(`event: state\ndata: ${JSON.stringify({
+                uptimeMs: Date.now() - state.startedAt,
+                stats: state.stats,
+                rules: getRuleStatuses(engine),
+            })}\n\n`);
+            // Send event history so dashboard survives refreshes
+            const history = engine.getRecentLiveEvents(200);
+            if (history.length > 0) {
+                res.write(`event: history\ndata: ${JSON.stringify(history)}\n\n`);
+            }
+            // Subscribe to engine events
+            const unsub = engine.bus.on((event) => {
+                try {
+                    res.write(`event: openalerts\ndata: ${JSON.stringify(event)}\n\n`);
+                }
+                catch {
+                    /* closed */
+                }
+            });
+            // Start log file tailer — streams OpenClaw internal logs as `event: oclog`
+            const logTailer = createLogTailer(res);
+            // Heartbeat every 15s
+            const heartbeat = setInterval(() => {
+                try {
+                    res.write(":heartbeat\n\n");
+                }
+                catch {
+                    /* closed */
+                }
+            }, 15_000);
+            const conn = { res, unsub, heartbeat, logTailer };
+            sseConnections.add(conn);
+            req.on("close", () => {
+                clearInterval(heartbeat);
+                clearInterval(logTailer);
+                unsub();
+                sseConnections.delete(conn);
+            });
+            return true;
+        }
+        // ── GET /openalerts/state → JSON snapshot ─────────────────
+        if (url === "/openalerts/state" && req.method === "GET") {
+            if (!engine) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Engine not running" }));
+                return true;
+            }
+            const state = engine.state;
+            const recentAlerts = engine
+                .getRecentEvents(50)
+                .filter((e) => e.type === "alert");
+            const body = JSON.stringify({
+                uptimeMs: Date.now() - state.startedAt,
+                startedAt: state.startedAt,
+                lastHeartbeatTs: state.lastHeartbeatTs,
+                hourlyAlerts: state.hourlyAlerts,
+                stuckSessions: state.stats.stuckSessions,
+                lastResetTs: state.stats.lastResetTs,
+                stats: state.stats,
+                busListeners: engine.bus.size,
+                platformConnected: engine.platformConnected,
+                recentAlerts: recentAlerts.slice(0, 20),
+                rules: getRuleStatuses(engine),
+                cooldowns: Object.fromEntries(state.cooldowns),
+            });
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Cache-Control": "no-cache",
+                "Access-Control-Allow-Origin": "*",
+            });
+            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");
+            const rawLimit = urlObj.searchParams.get("limit") || "200";
+            // limit=0 means "no limit" — return all log entries
+            const limit = rawLimit === "0" ? 0 : Math.min(parseInt(rawLimit, 10), 50000);
+            const afterTs = urlObj.searchParams.get("after") || undefined;
+            const result = readOpenClawLogs(limit, afterTs);
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Cache-Control": "no-cache",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.end(JSON.stringify({
+                entries: result.entries,
+                truncated: result.truncated,
+                subsystems: result.subsystems,
+                logFile: getOpenClawLogPath(),
+            }));
+            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");
+        return true;
+    };
+}

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);
+    }
+}