@steadwing/openalerts 0.1.0

package/dist/src/adapter.js

@@ -0,0 +1,458 @@
+// ─── Diagnostic Event Translation ───────────────────────────────────────────
+//
+// OpenClaw emits 12 diagnostic event types through onDiagnosticEvent():
+//   model.usage, webhook.received, webhook.processed, webhook.error,
+//   message.queued, message.processed, session.state, session.stuck,
+//   queue.lane.enqueue, queue.lane.dequeue, diagnostic.heartbeat,
+//   run.attempt (reserved, not yet emitted)
+//
+// Agent/tool/session lifecycle events come through plugin hooks (api.on()),
+// not diagnostic events. Those are handled separately in index.ts.
+// ────────────────────────────────────────────────────────────────────────────
+const DIAGNOSTIC_EVENT_MAP = {
+    // Infrastructure
+    "webhook.error": "infra.error",
+    "webhook.received": "custom", // inbound webhook arrival (informational)
+    "webhook.processed": "custom", // webhook fully handled (informational)
+    // LLM / Message processing
+    "message.processed": "llm.call",
+    "message.queued": "infra.queue_depth",
+    "model.usage": "llm.token_usage",
+    // Session
+    "session.stuck": "session.stuck",
+    "session.state": "custom", // state transitions (idle→processing→waiting)
+    // Heartbeat
+    "diagnostic.heartbeat": "infra.heartbeat",
+    heartbeat: "infra.heartbeat",
+    // Queue lanes
+    "queue.lane.enqueue": "infra.queue_depth",
+    "queue.lane.dequeue": "infra.queue_depth",
+    // Watchdog (internal, injected by engine timer)
+    "watchdog.tick": "watchdog.tick",
+    // Reserved (not yet emitted by OpenClaw)
+    "run.attempt": "agent.start",
+};
+/**
+ * Normalize OpenClaw outcome values to OpenAlertsEvent outcome.
+ * OpenClaw uses "completed"/"failed"/"success"/"error" inconsistently
+ * across different event types.
+ */
+function normalizeOutcome(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw) {
+        case "success":
+        case "completed":
+        case "ok":
+            return "success";
+        case "error":
+        case "failed":
+        case "failure":
+            return "error";
+        case "skipped":
+            return "skipped";
+        case "timeout":
+        case "timed_out":
+            return "timeout";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Translate an OpenClaw diagnostic event into a universal OpenAlertsEvent.
+ * Returns null for unmapped event types.
+ */
+export function translateOpenClawEvent(event) {
+    const type = DIAGNOSTIC_EVENT_MAP[event.type];
+    if (!type)
+        return null;
+    const base = {
+        type,
+        ts: typeof event.ts === "number" ? event.ts : Date.now(),
+        channel: event.channel,
+        sessionKey: event.sessionKey,
+        agentId: event.agentId,
+        durationMs: event.durationMs,
+        outcome: normalizeOutcome(event.outcome ?? event.status),
+        error: event.error,
+        ageMs: event.ageMs,
+        meta: { openclawEventType: event.type },
+    };
+    // ── Queue depth: from heartbeat, message.queued, or queue.lane events ────
+    if (typeof event.queued === "number") {
+        base.queueDepth = event.queued;
+    }
+    else if (typeof event.queueDepth === "number") {
+        base.queueDepth = event.queueDepth;
+    }
+    else if (typeof event.depth === "number") {
+        base.queueDepth = event.depth;
+    }
+    // ── model.usage: extract token counts and cost ───────────────────────────
+    if (event.type === "model.usage") {
+        const usage = event.usage;
+        if (usage) {
+            if (typeof usage.totalTokens === "number") {
+                base.tokenCount = usage.totalTokens;
+            }
+            else if (typeof usage.inputTokens === "number" ||
+                typeof usage.outputTokens === "number") {
+                base.tokenCount =
+                    (usage.inputTokens ?? 0) +
+                        (usage.outputTokens ?? 0);
+            }
+            if (typeof usage.costUsd === "number") {
+                base.costUsd = usage.costUsd;
+            }
+        }
+        if (typeof event.tokenCount === "number")
+            base.tokenCount = event.tokenCount;
+        if (typeof event.costUsd === "number")
+            base.costUsd = event.costUsd;
+        if (event.model)
+            base.meta.model = event.model;
+        if (event.provider)
+            base.meta.provider = event.provider;
+    }
+    // ── session.state: carry transition info ─────────────────────────────────
+    if (event.type === "session.state") {
+        if (event.state)
+            base.meta.sessionState = event.state;
+        if (event.previousState)
+            base.meta.previousState = event.previousState;
+        // Map terminal states to specific event types
+        const state = event.state;
+        if (state === "ended" || state === "closed") {
+            base.type = "session.end";
+        }
+        else if (state === "started" || state === "created") {
+            base.type = "session.start";
+        }
+    }
+    // ── queue.lane.*: extract lane info and wait time ────────────────────────
+    if (event.type === "queue.lane.enqueue" ||
+        event.type === "queue.lane.dequeue") {
+        if (typeof event.waitMs === "number")
+            base.durationMs = event.waitMs;
+        if (event.lane)
+            base.meta.lane = event.lane;
+    }
+    // ── webhook.*: preserve HTTP method and path ─────────────────────────────
+    if (event.type === "webhook.received" || event.type === "webhook.processed") {
+        if (event.method)
+            base.meta.method = event.method;
+        if (event.path)
+            base.meta.path = event.path;
+        base.outcome = base.outcome ?? "success";
+    }
+    // ── message.queued: ensure queue depth is set ────────────────────────────
+    if (event.type === "message.queued") {
+        base.outcome = base.outcome ?? "success";
+    }
+    return base;
+}
+// ─── Plugin Hook Event Translation ──────────────────────────────────────────
+//
+// Plugin hooks provide lifecycle events that diagnostic events don't cover:
+// tool calls, agent lifecycle, session lifecycle, gateway lifecycle.
+// These functions are called from index.ts where api.on() is wired.
+// ────────────────────────────────────────────────────────────────────────────
+/** Translate after_tool_call hook data into OpenAlertsEvent. */
+export function translateToolCallHook(data, context) {
+    return {
+        type: data.error ? "tool.error" : "tool.call",
+        ts: Date.now(),
+        sessionKey: context.sessionId,
+        agentId: context.agentId,
+        durationMs: data.durationMs,
+        outcome: data.error ? "error" : "success",
+        error: data.error,
+        meta: { toolName: data.toolName, source: "hook:after_tool_call" },
+    };
+}
+/** Translate before_agent_start hook data into OpenAlertsEvent. */
+export function translateAgentStartHook(data, context) {
+    return {
+        type: "agent.start",
+        ts: Date.now(),
+        sessionKey: context.sessionId,
+        agentId: context.agentId,
+        outcome: "success",
+        meta: { source: "hook:before_agent_start" },
+    };
+}
+/** Translate agent_end hook data into OpenAlertsEvent. */
+export function translateAgentEndHook(data, context) {
+    return {
+        type: data.success ? "agent.end" : "agent.error",
+        ts: Date.now(),
+        sessionKey: context.sessionId,
+        agentId: context.agentId,
+        durationMs: data.durationMs,
+        outcome: data.success ? "success" : "error",
+        error: data.error,
+        meta: {
+            messageCount: data.messages?.length ?? 0,
+            source: "hook:agent_end",
+        },
+    };
+}
+/** Translate session_start hook data into OpenAlertsEvent. */
+export function translateSessionStartHook(data) {
+    return {
+        type: "session.start",
+        ts: Date.now(),
+        sessionKey: data.sessionId,
+        outcome: "success",
+        meta: {
+            resumedFrom: data.resumedFrom,
+            source: "hook:session_start",
+        },
+    };
+}
+/** Translate session_end hook data into OpenAlertsEvent. */
+export function translateSessionEndHook(data) {
+    return {
+        type: "session.end",
+        ts: Date.now(),
+        sessionKey: data.sessionId,
+        durationMs: data.durationMs,
+        outcome: "success",
+        meta: { messageCount: data.messageCount, source: "hook:session_end" },
+    };
+}
+/** Translate message_sent hook data into OpenAlertsEvent (delivery tracking). */
+export function translateMessageSentHook(data, context) {
+    return {
+        type: data.success ? "custom" : "infra.error",
+        ts: Date.now(),
+        channel: context.channel,
+        sessionKey: context.sessionId,
+        outcome: data.success ? "success" : "error",
+        error: data.error,
+        meta: { to: data.to, source: "hook:message_sent" },
+    };
+}
+/** Translate gateway_start hook data into OpenAlertsEvent. */
+export function translateGatewayStartHook(data) {
+    return {
+        type: "infra.heartbeat",
+        ts: Date.now(),
+        outcome: "success",
+        meta: { port: data.port, source: "hook:gateway_start" },
+    };
+}
+/** Translate gateway_stop hook data into OpenAlertsEvent. */
+export function translateGatewayStopHook(data) {
+    return {
+        type: "infra.error",
+        ts: Date.now(),
+        outcome: "error",
+        error: data.reason ?? "Gateway stopped",
+        meta: { source: "hook:gateway_stop" },
+    };
+}
+/** Translate message_received hook data into OpenAlertsEvent (inbound tracking). */
+export function translateMessageReceivedHook(data, context) {
+    return {
+        type: "custom",
+        ts: data.timestamp ?? Date.now(),
+        channel: context.channelId,
+        outcome: "success",
+        meta: {
+            from: data.from,
+            accountId: context.accountId,
+            openclawHook: "message_received",
+            source: "hook:message_received",
+        },
+    };
+}
+/** Translate before_tool_call hook data into OpenAlertsEvent (tool start tracking). */
+export function translateBeforeToolCallHook(data, context) {
+    return {
+        type: "custom",
+        ts: Date.now(),
+        sessionKey: context.sessionId,
+        agentId: context.agentId,
+        outcome: "success",
+        meta: {
+            toolName: data.toolName,
+            openclawHook: "before_tool_call",
+            source: "hook:before_tool_call",
+        },
+    };
+}
+/** Translate before_compaction hook data into OpenAlertsEvent. */
+export function translateBeforeCompactionHook(data, context) {
+    return {
+        type: "custom",
+        ts: Date.now(),
+        sessionKey: context.sessionKey,
+        agentId: context.agentId,
+        outcome: "success",
+        meta: {
+            messageCount: data.messageCount,
+            tokenCount: data.tokenCount,
+            openclawHook: "before_compaction",
+            source: "hook:before_compaction",
+        },
+    };
+}
+/** Translate after_compaction hook data into OpenAlertsEvent. */
+export function translateAfterCompactionHook(data, context) {
+    return {
+        type: "custom",
+        ts: Date.now(),
+        sessionKey: context.sessionKey,
+        agentId: context.agentId,
+        outcome: "success",
+        meta: {
+            messageCount: data.messageCount,
+            tokenCount: data.tokenCount,
+            compactedCount: data.compactedCount,
+            openclawHook: "after_compaction",
+            source: "hook:after_compaction",
+        },
+    };
+}
+/** Translate message_sending hook data into OpenAlertsEvent (pre-send tracking). */
+export function translateMessageSendingHook(data, context) {
+    return {
+        type: "custom",
+        ts: Date.now(),
+        channel: context.channelId,
+        outcome: "success",
+        meta: {
+            to: data.to,
+            accountId: context.accountId,
+            openclawHook: "message_sending",
+            source: "hook:message_sending",
+        },
+    };
+}
+/** Translate tool_result_persist hook data into OpenAlertsEvent. */
+export function translateToolResultPersistHook(data, context) {
+    return {
+        type: "custom",
+        ts: Date.now(),
+        sessionKey: context.sessionKey,
+        agentId: context.agentId,
+        outcome: "success",
+        meta: {
+            toolName: data.toolName ?? context.toolName,
+            toolCallId: data.toolCallId,
+            isSynthetic: data.isSynthetic,
+            openclawHook: "tool_result_persist",
+            source: "hook:tool_result_persist",
+        },
+    };
+}
+// ─── OpenClaw Alert Channel ─────────────────────────────────────────────────
+/**
+ * AlertChannel that sends through OpenClaw's runtime channel API.
+ * Bridges the universal AlertChannel interface to OpenClaw's messaging system.
+ */
+export class OpenClawAlertChannel {
+    name;
+    api;
+    target;
+    constructor(api, target) {
+        this.api = api;
+        this.target = target;
+        this.name = `openclaw:${target.channel}`;
+    }
+    async send(alert, formatted) {
+        const runtime = this.api.runtime;
+        const channel = runtime.channel;
+        if (!channel)
+            return;
+        const opts = this.target.accountId
+            ? { accountId: this.target.accountId }
+            : {};
+        const channelMethods = {
+            telegram: "sendMessageTelegram",
+            discord: "sendMessageDiscord",
+            slack: "sendMessageSlack",
+            whatsapp: "sendMessageWhatsApp",
+            signal: "sendMessageSignal",
+        };
+        const methodName = channelMethods[this.target.channel];
+        if (!methodName)
+            return;
+        const channelMod = channel[this.target.channel];
+        const sendFn = channelMod?.[methodName];
+        if (sendFn) {
+            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) {
+    // 1. Explicit config
+    if (pluginConfig.alertChannel && pluginConfig.alertTo) {
+        return {
+            channel: pluginConfig.alertChannel,
+            to: pluginConfig.alertTo,
+            accountId: pluginConfig.alertAccountId,
+        };
+    }
+    const cfg = api.config;
+    // 2. Auto-detect from configured channels
+    const channelKeys = [
+        "telegram",
+        "discord",
+        "slack",
+        "whatsapp",
+        "signal",
+    ];
+    for (const channelKey of channelKeys) {
+        const channelConfig = cfg[channelKey];
+        if (!channelConfig || typeof channelConfig !== "object")
+            continue;
+        const target = extractFirstAllowFrom(channelKey, channelConfig);
+        if (target)
+            return target;
+    }
+    return null;
+}
+function extractFirstAllowFrom(channel, channelConfig) {
+    const directAllow = channelConfig.allowFrom;
+    if (Array.isArray(directAllow) && directAllow.length > 0) {
+        return { channel, to: String(directAllow[0]) };
+    }
+    for (const [key, value] of Object.entries(channelConfig)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const accountObj = value;
+        const allow = accountObj.allowFrom;
+        if (Array.isArray(allow) && allow.length > 0) {
+            return {
+                channel,
+                to: String(allow[0]),
+                accountId: key === "default" ? undefined : key,
+            };
+        }
+    }
+    return null;
+}
+// ─── Config Parsing ─────────────────────────────────────────────────────────
+export function parseConfig(raw) {
+    if (!raw)
+        return {};
+    return {
+        apiKey: typeof raw.apiKey === "string" ? raw.apiKey : undefined,
+        alertChannel: typeof raw.alertChannel === "string" ? raw.alertChannel : undefined,
+        alertTo: typeof raw.alertTo === "string" ? raw.alertTo : undefined,
+        alertAccountId: typeof raw.alertAccountId === "string" ? raw.alertAccountId : undefined,
+        cooldownMinutes: typeof raw.cooldownMinutes === "number" ? raw.cooldownMinutes : undefined,
+        maxLogSizeKb: typeof raw.maxLogSizeKb === "number" ? raw.maxLogSizeKb : undefined,
+        maxLogAgeDays: typeof raw.maxLogAgeDays === "number" ? raw.maxLogAgeDays : undefined,
+        quiet: typeof raw.quiet === "boolean" ? raw.quiet : undefined,
+        rules: raw.rules && typeof raw.rules === "object"
+            ? raw.rules
+            : undefined,
+    };
+}

package/dist/src/commands.d.ts

@@ -0,0 +1,18 @@
+import type { OpenAlertsEngine } from "@steadwing/openalerts-core";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+type PluginCommandDef = {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: Record<string, unknown>) => {
+        text: string;
+    } | Promise<{
+        text: string;
+    }>;
+};
+/** Called by service to wire commands to the live engine instance. */
+export declare function bindEngine(engine: OpenAlertsEngine, api: OpenClawPluginApi): void;
+/** Create /health, /alerts, and /dashboard command definitions. */
+export declare function createMonitorCommands(api: OpenClawPluginApi): PluginCommandDef[];
+export {};

package/dist/src/commands.js

@@ -0,0 +1,122 @@
+import { formatAlertsOutput, formatHealthOutput } from "@steadwing/openalerts-core";
+// Engine reference, set when service starts
+let _engine = null;
+let _api = null;
+/** Called by service to wire commands to the live engine instance. */
+export function bindEngine(engine, api) {
+    _engine = engine;
+    _api = api;
+}
+/** Create /health, /alerts, and /dashboard command definitions. */
+export function createMonitorCommands(api) {
+    return [
+        {
+            name: "health",
+            description: "Show system health and monitoring status",
+            acceptsArgs: false,
+            handler: () => handleHealth(),
+        },
+        {
+            name: "alerts",
+            description: "Show recent alerts from OpenAlerts Monitor",
+            acceptsArgs: false,
+            handler: () => handleAlerts(),
+        },
+        {
+            name: "dashboard",
+            description: "Get link to the real-time OpenAlerts monitoring dashboard",
+            acceptsArgs: false,
+            handler: () => handleDashboard(),
+        },
+        {
+            name: "test-alert",
+            description: "Send a test alert to verify alert delivery",
+            acceptsArgs: false,
+            handler: () => handleTestAlert(),
+        },
+    ];
+}
+function handleHealth() {
+    if (!_engine) {
+        return { text: "OpenAlerts not initialized yet. Wait for gateway startup." };
+    }
+    const channelActivity = getChannelActivity();
+    const recentEvents = _engine.getRecentEvents(50);
+    const oneHourAgo = Date.now() - 60 * 60 * 1000;
+    const activeAlerts = recentEvents.filter((e) => e.type === "alert" && e.ts >= oneHourAgo);
+    return {
+        text: formatHealthOutput({
+            state: _engine.state,
+            channelActivity,
+            activeAlerts,
+            platformConnected: _engine.platformConnected,
+        }),
+    };
+}
+function handleAlerts() {
+    if (!_engine) {
+        return { text: "OpenAlerts not initialized yet." };
+    }
+    const events = _engine.getRecentEvents(100);
+    return { text: formatAlertsOutput(events) };
+}
+function handleDashboard() {
+    if (!_engine) {
+        return { text: "OpenAlerts not initialized yet. Wait for gateway startup." };
+    }
+    return {
+        text: "OpenAlerts Dashboard: http://127.0.0.1:18789/openalerts\n\nOpen in your browser to see real-time events, alerts, and rule status.",
+    };
+}
+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" },
+    });
+    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.",
+    };
+}
+function getChannelActivity() {
+    if (!_api)
+        return [];
+    const result = [];
+    const channels = ["telegram", "discord", "slack", "whatsapp", "signal"];
+    for (const ch of channels) {
+        try {
+            const runtime = _api.runtime;
+            const channelMod = runtime.channel;
+            const activity = channelMod?.activity;
+            const get = activity?.get;
+            if (get) {
+                const entry = get({ channel: ch });
+                if (entry.inboundAt) {
+                    result.push({ channel: ch, lastInbound: entry.inboundAt });
+                }
+            }
+        }
+        catch {
+            // Channel not configured
+        }
+    }
+    return result;
+}

package/dist/src/dashboard-html.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OpenAlerts real-time monitoring dashboard.
+ * Tabs: Activity (unified event + log timeline), System Logs, Health.
+ * Activity shows both OpenAlerts engine events AND OpenClaw internal logs
+ * grouped by sessionId for a complete picture of what's happening.
+ */
+export declare function getDashboardHtml(): string;