agentvault 1.0.0 → 1.0.2

package/dist/src/metrics/metrics.js

@@ -0,0 +1,129 @@
+/**
+ * Metrics Module
+ *
+ * Stores and retrieves canister metrics (cycles, memory, messages, etc.)
+ * in JSONL format: ~/.agentvault/metrics/<canister-id>/YYYY-MM-DD.jsonl
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const AGENTVAULT_DIR = path.join(os.homedir(), '.agentvault');
+const METRICS_DIR = path.join(AGENTVAULT_DIR, 'metrics');
+function getMetricsDir(canisterId) {
+    const dir = path.join(METRICS_DIR, canisterId);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function getMetricsFile(canisterId, date) {
+    const metricsDir = getMetricsDir(canisterId);
+    const dateStr = date.toISOString().split('T')[0];
+    return path.join(metricsDir, `${dateStr}.jsonl`);
+}
+export function storeMetrics(canisterId, metrics) {
+    const now = new Date();
+    const metricsFile = getMetricsFile(canisterId, now);
+    for (const [metric, value] of Object.entries(metrics)) {
+        const line = JSON.stringify({
+            timestamp: now.toISOString(),
+            metric,
+            value,
+        });
+        fs.appendFileSync(metricsFile, `${line}\n`);
+    }
+}
+export function getTimeSeries(canisterId, metric, from, to) {
+    const dataPoints = [];
+    const currentDate = new Date(from);
+    while (currentDate <= to) {
+        const metricsFile = getMetricsFile(canisterId, currentDate);
+        if (fs.existsSync(metricsFile)) {
+            const lines = fs.readFileSync(metricsFile, 'utf8').trim().split('\n');
+            for (const line of lines) {
+                if (line) {
+                    const parsed = JSON.parse(line);
+                    if (parsed.metric === metric) {
+                        const timestamp = new Date(parsed.timestamp);
+                        if (timestamp >= from && timestamp <= to) {
+                            dataPoints.push({ timestamp, value: parsed.value });
+                        }
+                    }
+                }
+            }
+        }
+        currentDate.setDate(currentDate.getDate() + 1);
+    }
+    dataPoints.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    return { metric, dataPoints };
+}
+export function getSummary(canisterId, days = 7) {
+    const now = new Date();
+    const from = new Date(now);
+    from.setDate(now.getDate() - days);
+    const metricValues = {};
+    const metricCurrent = {};
+    for (const metric of ['cycles_balance', 'memory_heap', 'message_count', 'request_count', 'error_count']) {
+        const series = getTimeSeries(canisterId, metric, from, now);
+        if (series.dataPoints.length > 0) {
+            metricValues[metric] = series.dataPoints.map(dp => dp.value);
+            const lastPoint = series.dataPoints[series.dataPoints.length - 1];
+            if (lastPoint) {
+                metricCurrent[metric] = lastPoint.value;
+            }
+        }
+    }
+    const summary = {
+        canisterId,
+        metrics: {},
+        period: { start: from, end: now },
+    };
+    for (const [metric, values] of Object.entries(metricValues)) {
+        if (values) {
+            const currentValue = metricCurrent[metric];
+            if (currentValue !== undefined) {
+                const min = Math.min(...values);
+                const max = Math.max(...values);
+                const avg = values.reduce((a, b) => a + b, 0) / values.length;
+                summary.metrics[metric] = {
+                    current: currentValue,
+                    min,
+                    max,
+                    avg,
+                };
+            }
+        }
+    }
+    return summary;
+}
+export function pruneOldData(canisterId, retentionDays) {
+    const metricsDir = getMetricsDir(canisterId);
+    if (!fs.existsSync(metricsDir))
+        return;
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - retentionDays);
+    const files = fs.readdirSync(metricsDir);
+    for (const file of files) {
+        if (file.endsWith('.jsonl')) {
+            const dateStr = file.replace('.jsonl', '');
+            const fileDate = new Date(dateStr);
+            if (fileDate < cutoff) {
+                fs.unlinkSync(path.join(metricsDir, file));
+            }
+        }
+    }
+}
+export function startCollector(canisterId, config = {}) {
+    const { interval = 60000, retentionDays = 7 } = config;
+    const collect = async () => {
+        try {
+            pruneOldData(canisterId, retentionDays);
+        }
+        catch (error) {
+            console.error(`Failed to collect metrics for ${canisterId}:`, error);
+        }
+    };
+    collect();
+    return setInterval(collect, interval);
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/monitoring/alerting.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Alerting
+ *
+ * Generates, stores, and retrieves monitoring alerts for canisters.
+ * Tracks cycle depletion, memory issues, and performance degradation.
+ */
+import type { MonitoringAlert, CanisterStatusInfo, HealthThresholds } from './types.js';
+/**
+ * Load alerts from storage.
+ *
+ * @param canisterId - Canister ID
+ * @returns Stored alerts array
+ */
+export declare function loadAlerts(canisterId: string): MonitoringAlert[];
+/**
+ * Save alerts to storage.
+ *
+ * @param canisterId - Canister ID
+ * @param alerts - Alerts to store
+ */
+export declare function saveAlerts(canisterId: string, alerts: MonitoringAlert[]): void;
+/**
+ * Append a new alert to storage.
+ *
+ * @param canisterId - Canister ID
+ * @param alert - Alert to add
+ */
+export declare function appendAlert(canisterId: string, alert: MonitoringAlert): void;
+/**
+ * Clear alerts for a canister.
+ *
+ * @param canisterId - Canister ID
+ */
+export declare function clearAlerts(canisterId: string): void;
+/**
+ * Generate health alerts for a canister based on its current status.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @returns Array of alerts
+ */
+export declare function generateHealthAlerts(statusInfo: CanisterStatusInfo, thresholds?: HealthThresholds): MonitoringAlert[];
+/**
+ * Get recent alerts for a canister.
+ *
+ * @param canisterId - Canister ID
+ * @param limit - Maximum number of alerts to return (default: 10)
+ * @returns Recent alerts (newest first)
+ */
+export declare function getRecentAlerts(canisterId: string, limit?: number): MonitoringAlert[];
+//# sourceMappingURL=alerting.d.ts.map

package/dist/src/monitoring/alerting.js

@@ -0,0 +1,169 @@
+/**
+ * Alerting
+ *
+ * Generates, stores, and retrieves monitoring alerts for canisters.
+ * Tracks cycle depletion, memory issues, and performance degradation.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Default alert storage path
+ */
+const ALERTS_DIR = path.join(process.env.HOME || process.cwd(), '.agentvault', 'alerts');
+/**
+ * Alert storage file path
+ */
+const getAlertFilePath = (canisterId) => path.join(ALERTS_DIR, `${canisterId}.json`);
+/**
+ * Load alerts from storage.
+ *
+ * @param canisterId - Canister ID
+ * @returns Stored alerts array
+ */
+export function loadAlerts(canisterId) {
+    const alertFile = getAlertFilePath(canisterId);
+    if (!fs.existsSync(alertFile)) {
+        return [];
+    }
+    try {
+        const content = fs.readFileSync(alertFile, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Save alerts to storage.
+ *
+ * @param canisterId - Canister ID
+ * @param alerts - Alerts to store
+ */
+export function saveAlerts(canisterId, alerts) {
+    const alertFile = getAlertFilePath(canisterId);
+    const content = JSON.stringify(alerts, null, 2);
+    fs.mkdirSync(path.dirname(alertFile), { recursive: true });
+    fs.writeFileSync(alertFile, content, 'utf-8');
+}
+/**
+ * Append a new alert to storage.
+ *
+ * @param canisterId - Canister ID
+ * @param alert - Alert to add
+ */
+export function appendAlert(canisterId, alert) {
+    const alerts = loadAlerts(canisterId);
+    alerts.push(alert);
+    saveAlerts(canisterId, alerts);
+}
+/**
+ * Clear alerts for a canister.
+ *
+ * @param canisterId - Canister ID
+ */
+export function clearAlerts(canisterId) {
+    const alertFile = getAlertFilePath(canisterId);
+    if (fs.existsSync(alertFile)) {
+        fs.unlinkSync(alertFile);
+    }
+}
+/**
+ * Generate health alerts for a canister based on its current status.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @returns Array of alerts
+ */
+export function generateHealthAlerts(statusInfo, thresholds = {}) {
+    const alerts = [];
+    const cycles = statusInfo.cycles;
+    if (cycles !== undefined) {
+        if (thresholds.cyclesCritical !== undefined && cycles < thresholds.cyclesCritical) {
+            alerts.push({
+                severity: 'critical',
+                message: `Cycle balance critically low: ${cycles.toString()}`,
+                canisterId: statusInfo.canisterId,
+                metric: 'cycles',
+                value: cycles.toString(),
+                threshold: thresholds.cyclesCritical.toString(),
+                timestamp: new Date(),
+            });
+        }
+        else if (thresholds.cyclesWarning !== undefined && cycles < thresholds.cyclesWarning) {
+            alerts.push({
+                severity: 'warning',
+                message: `Cycle balance low: ${cycles.toString()}`,
+                canisterId: statusInfo.canisterId,
+                metric: 'cycles',
+                value: cycles.toString(),
+                threshold: thresholds.cyclesWarning.toString(),
+                timestamp: new Date(),
+            });
+        }
+    }
+    const memoryBytes = statusInfo.memorySize;
+    if (memoryBytes !== undefined) {
+        const memoryMB = Number(memoryBytes) / (1024 * 1024);
+        // IC canisters have ~4GB max memory (4096 MB)
+        const maxMemoryMB = 4096;
+        const criticalThresholdMB = maxMemoryMB * ((thresholds.memoryCriticalPercent ?? 0) / 100);
+        const warningThresholdMB = maxMemoryMB * ((thresholds.memoryWarningPercent ?? 0) / 100);
+        if (thresholds.memoryCriticalPercent !== undefined && memoryMB > criticalThresholdMB) {
+            alerts.push({
+                severity: 'critical',
+                message: `Memory usage critically high: ${memoryMB.toFixed(2)} MB`,
+                canisterId: statusInfo.canisterId,
+                metric: 'memory',
+                value: `${memoryMB.toFixed(2)} MB`,
+                threshold: `${thresholds.memoryCriticalPercent}%`,
+                timestamp: new Date(),
+            });
+        }
+        else if (thresholds.memoryWarningPercent !== undefined && memoryMB > warningThresholdMB) {
+            alerts.push({
+                severity: 'warning',
+                message: `Memory usage high: ${memoryMB.toFixed(2)} MB`,
+                canisterId: statusInfo.canisterId,
+                metric: 'memory',
+                value: `${memoryMB.toFixed(2)} MB`,
+                threshold: `${thresholds.memoryWarningPercent}%`,
+                timestamp: new Date(),
+            });
+        }
+    }
+    if (statusInfo.status === 'stopped') {
+        alerts.push({
+            severity: 'critical',
+            message: 'Canister is stopped',
+            canisterId: statusInfo.canisterId,
+            metric: 'status',
+            value: statusInfo.status,
+            threshold: 'healthy',
+            timestamp: new Date(),
+        });
+    }
+    else if (statusInfo.status === 'stopping') {
+        alerts.push({
+            severity: 'warning',
+            message: 'Canister is stopping',
+            canisterId: statusInfo.canisterId,
+            metric: 'status',
+            value: statusInfo.status,
+            threshold: 'healthy',
+            timestamp: new Date(),
+        });
+    }
+    return alerts;
+}
+/**
+ * Get recent alerts for a canister.
+ *
+ * @param canisterId - Canister ID
+ * @param limit - Maximum number of alerts to return (default: 10)
+ * @returns Recent alerts (newest first)
+ */
+export function getRecentAlerts(canisterId, limit = 10) {
+    const alerts = loadAlerts(canisterId);
+    return alerts.slice(-limit);
+}
+//# sourceMappingURL=alerting.js.map

package/dist/src/monitoring/health.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Health Monitoring
+ *
+ * Performs health checks on canisters and determines overall health status
+ * based on resource usage thresholds.
+ */
+import type { CanisterHealthStatus, CanisterStatusInfo, HealthThresholds, MonitoringOptions, MonitoringAlert } from './types.js';
+/**
+ * Determine health status based on resource metrics.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @returns Health status
+ */
+export declare function determineHealthStatus(statusInfo: CanisterStatusInfo, thresholds?: HealthThresholds): CanisterHealthStatus;
+/**
+ * Generate alerts based on health status.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @param currentHealth - Current health status
+ * @returns Generated alerts
+ */
+export declare function generateHealthAlerts(statusInfo: CanisterStatusInfo, thresholds?: HealthThresholds, currentHealth?: CanisterHealthStatus): MonitoringAlert[];
+/**
+ * Perform a one-time health check.
+ *
+ * @param options - Monitoring options
+ * @returns Canister status with health status
+ */
+export declare function checkHealth(canisterId: string, options?: Partial<MonitoringOptions>): Promise<CanisterStatusInfo>;
+/**
+ * Check multiple canisters' health status.
+ *
+ * @param canisterIds - Array of canister IDs to check
+ * @param options - Monitoring options applied to all
+ * @returns Array of canister status info
+ */
+export declare function checkMultipleHealth(canisterIds: string[], options?: Partial<MonitoringOptions>): Promise<CanisterStatusInfo[]>;
+//# sourceMappingURL=health.d.ts.map

package/dist/src/monitoring/health.js

@@ -0,0 +1,164 @@
+/**
+ * Health Monitoring
+ *
+ * Performs health checks on canisters and determines overall health status
+ * based on resource usage thresholds.
+ */
+import { getCanisterInfo } from './info.js';
+/**
+ * Determine health status based on resource metrics.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @returns Health status
+ */
+export function determineHealthStatus(statusInfo, thresholds = {}) {
+    // Check cycles
+    const cycles = statusInfo.cycles;
+    if (cycles !== undefined) {
+        if (thresholds.cyclesCritical && cycles < thresholds.cyclesCritical) {
+            return 'critical';
+        }
+        else if (thresholds.cyclesWarning && cycles < thresholds.cyclesWarning) {
+            return 'warning';
+        }
+    }
+    // Check memory
+    const memoryBytes = statusInfo.memorySize;
+    if (memoryBytes !== undefined) {
+        const memoryMB = Number(memoryBytes) / (1024 * 1024);
+        // IC canisters have ~4GB max memory (4096 MB)
+        const maxMemoryMB = 4096;
+        const criticalThresholdMB = maxMemoryMB * ((thresholds.memoryCriticalPercent ?? 0) / 100);
+        const warningThresholdMB = maxMemoryMB * ((thresholds.memoryWarningPercent ?? 0) / 100);
+        if (thresholds.memoryCriticalPercent && memoryMB > criticalThresholdMB) {
+            return 'critical';
+        }
+        else if (thresholds.memoryWarningPercent && memoryMB > warningThresholdMB) {
+            return 'warning';
+        }
+    }
+    // Check canister status
+    const status = statusInfo.status?.toLowerCase() ?? '';
+    if (status === 'stopped') {
+        return 'critical';
+    }
+    else if (status === 'stopping') {
+        return 'warning';
+    }
+    return 'healthy';
+}
+/**
+ * Generate alerts based on health status.
+ *
+ * @param statusInfo - Canister status information
+ * @param thresholds - Health check thresholds
+ * @param currentHealth - Current health status
+ * @returns Generated alerts
+ */
+export function generateHealthAlerts(statusInfo, thresholds = {}, currentHealth = 'healthy') {
+    const alerts = [];
+    const cycles = statusInfo.cycles;
+    if (cycles !== undefined && thresholds.cyclesCritical !== undefined) {
+        if (cycles < thresholds.cyclesCritical) {
+            alerts.push({
+                severity: 'critical',
+                message: `Cycle balance critically low: ${formatCycles(cycles)}`,
+                canisterId: statusInfo.canisterId,
+                metric: 'cycles',
+                value: formatCycles(cycles),
+                threshold: formatCycles(thresholds.cyclesCritical),
+                timestamp: new Date(),
+            });
+        }
+        else if (thresholds.cyclesWarning !== undefined && cycles < thresholds.cyclesWarning) {
+            alerts.push({
+                severity: 'warning',
+                message: `Cycle balance low: ${formatCycles(cycles)}`,
+                canisterId: statusInfo.canisterId,
+                metric: 'cycles',
+                value: formatCycles(cycles),
+                threshold: formatCycles(thresholds.cyclesWarning),
+                timestamp: new Date(),
+            });
+        }
+    }
+    const memoryBytes = statusInfo.memorySize;
+    if (memoryBytes !== undefined) {
+        const memoryMB = Number(memoryBytes) / (1024 * 1024);
+        if (thresholds.memoryCriticalPercent !== undefined && memoryMB > 1024 * thresholds.memoryCriticalPercent) {
+            alerts.push({
+                severity: 'critical',
+                message: `Memory usage critically high: ${memoryMB.toFixed(2)} MB`,
+                canisterId: statusInfo.canisterId,
+                metric: 'memory',
+                value: `${memoryMB.toFixed(2)} MB`,
+                threshold: `${thresholds.memoryCriticalPercent}%`,
+                timestamp: new Date(),
+            });
+        }
+        else if (thresholds.memoryWarningPercent !== undefined && memoryMB > 1024 * thresholds.memoryWarningPercent) {
+            alerts.push({
+                severity: 'warning',
+                message: `Memory usage high: ${memoryMB.toFixed(2)} MB`,
+                canisterId: statusInfo.canisterId,
+                metric: 'memory',
+                value: `${memoryMB.toFixed(2)} MB`,
+                threshold: `${thresholds.memoryWarningPercent}%`,
+                timestamp: new Date(),
+            });
+        }
+    }
+    if (currentHealth !== 'healthy') {
+        alerts.push({
+            severity: 'warning',
+            message: `Canister status: ${statusInfo.status}`,
+            canisterId: statusInfo.canisterId,
+            metric: 'status',
+            value: statusInfo.status,
+            threshold: 'healthy',
+            timestamp: new Date(),
+        });
+    }
+    return alerts;
+}
+/**
+ * Format cycles bigint to human-readable string.
+ */
+function formatCycles(cycles) {
+    if (cycles >= BigInt(1_000_000_000_000)) {
+        const value = Number(cycles) / 1_000_000_000_000;
+        return `${value.toFixed(2)} T`;
+    }
+    return cycles.toString();
+}
+/**
+ * Perform a one-time health check.
+ *
+ * @param options - Monitoring options
+ * @returns Canister status with health status
+ */
+export async function checkHealth(canisterId, options) {
+    const monitoringOptions = { canister: canisterId, ...options };
+    const statusInfo = await getCanisterInfo(canisterId, monitoringOptions);
+    const health = determineHealthStatus(statusInfo, options?.thresholds ?? {});
+    return {
+        ...statusInfo,
+        health,
+    };
+}
+/**
+ * Check multiple canisters' health status.
+ *
+ * @param canisterIds - Array of canister IDs to check
+ * @param options - Monitoring options applied to all
+ * @returns Array of canister status info
+ */
+export async function checkMultipleHealth(canisterIds, options) {
+    const results = await Promise.all(canisterIds.map((id) => getCanisterInfo(id, { canister: id, ...options })));
+    return results.map((statusInfo) => ({
+        ...statusInfo,
+        health: determineHealthStatus(statusInfo, options?.thresholds ?? {}),
+    }));
+}
+//# sourceMappingURL=health.js.map

package/dist/src/monitoring/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Monitoring Module
+ *
+ * Provides canister health monitoring and alerting capabilities.
+ */
+export { determineHealthStatus, generateHealthAlerts, checkHealth, checkMultipleHealth, } from './health.js';
+export { getCanisterInfo, } from './info.js';
+export { loadAlerts, saveAlerts, appendAlert, clearAlerts, getRecentAlerts, } from './alerting.js';
+export type { CanisterHealthStatus, CanisterStatusInfo, HealthThresholds, MonitoringOptions, MonitoringAlert, AlertSeverity, ResourceUsageSnapshot, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/monitoring/index.js

@@ -0,0 +1,12 @@
+/**
+ * Monitoring Module
+ *
+ * Provides canister health monitoring and alerting capabilities.
+ */
+// Health
+export { determineHealthStatus, generateHealthAlerts, checkHealth, checkMultipleHealth, } from './health.js';
+// Info
+export { getCanisterInfo, } from './info.js';
+// Alerting
+export { loadAlerts, saveAlerts, appendAlert, clearAlerts, getRecentAlerts, } from './alerting.js';
+//# sourceMappingURL=index.js.map

package/dist/src/monitoring/info.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Canister Information
+ *
+ * Queries canister status and metrics using icp-cli.
+ */
+import type { CanisterStatusInfo, MonitoringOptions } from './types.js';
+/**
+ * Get detailed canister information.
+ *
+ * @param canisterId - Canister ID to query
+ * @param options - Monitoring options
+ * @returns Canister status information
+ */
+export declare function getCanisterInfo(canisterId: string, _options: MonitoringOptions): Promise<CanisterStatusInfo>;
+//# sourceMappingURL=info.d.ts.map