@steadwing/openalerts 0.2.4 → 0.2.6

package/dist/plugin/adapter.js

@@ -1,530 +0,0 @@
-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():
-//   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, content: data.content, 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,
-            content: data.content,
-            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,
-            compaction: true,
-            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,
-            content: data.content,
-            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;
-    warnedMissing = false;
-    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) {
-            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 }
-            : {};
-        const channelMethods = {
-            telegram: "sendMessageTelegram",
-            discord: "sendMessageDiscord",
-            slack: "sendMessageSlack",
-            whatsapp: "sendMessageWhatsApp",
-            signal: "sendMessageSignal",
-        };
-        const methodName = channelMethods[this.target.channel];
-        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) {
-            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 async 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;
-    const channelsCfg = cfg.channels ??
-        {};
-    const channelKeys = [
-        "telegram",
-        "discord",
-        "slack",
-        "whatsapp",
-        "signal",
-    ];
-    // 2. Auto-detect from static allowFrom in channel config
-    for (const channelKey of channelKeys) {
-        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) {
-    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,
-        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.d.ts

@@ -1,18 +0,0 @@
-import type { OpenAlertsEngine } from "../core/index.js";
-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/plugin/commands.js

@@ -1,103 +0,0 @@
-import { formatAlertsOutput, formatHealthOutput } from "../core/index.js";
-// 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." };
-    }
-    _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.",
-    };
-}
-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/plugin/dashboard-html.d.ts

@@ -1,7 +0,0 @@
-/**
- * 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;