agentvault 1.0.0

package/src/metrics/metrics.ts

@@ -0,0 +1,186 @@
+/**
+ * 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';
+
+export type MetricName = 'cycles_balance' | 'memory_heap' | 'message_count' | 'request_count' | 'error_count';
+
+export interface MetricDataPoint {
+  timestamp: Date;
+  value: number;
+}
+
+export interface MetricTimeSeries {
+  metric: MetricName;
+  dataPoints: MetricDataPoint[];
+}
+
+export interface MetricsSummary {
+  canisterId: string;
+  metrics: Record<MetricName, {
+    current: number;
+    min: number;
+    max: number;
+    avg: number;
+    delta?: number;
+  }>;
+  period: { start: Date; end: Date };
+}
+
+export interface CollectorConfig {
+  interval?: number;
+  retentionDays?: number;
+}
+
+const AGENTVAULT_DIR = path.join(os.homedir(), '.agentvault');
+const METRICS_DIR = path.join(AGENTVAULT_DIR, 'metrics');
+
+function getMetricsDir(canisterId: string): string {
+  const dir = path.join(METRICS_DIR, canisterId);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function getMetricsFile(canisterId: string, date: Date): string {
+  const metricsDir = getMetricsDir(canisterId);
+  const dateStr = date.toISOString().split('T')[0];
+  return path.join(metricsDir, `${dateStr}.jsonl`);
+}
+
+export function storeMetrics(canisterId: string, metrics: Record<MetricName, number>): void {
+  const now = new Date();
+  const metricsFile = getMetricsFile(canisterId, now);
+  
+  for (const [metric, value] of Object.entries(metrics) as [MetricName, number][]) {
+    const line = JSON.stringify({
+      timestamp: now.toISOString(),
+      metric,
+      value,
+    });
+    fs.appendFileSync(metricsFile, `${line}\n`);
+  }
+}
+
+export function getTimeSeries(
+  canisterId: string,
+  metric: MetricName,
+  from: Date,
+  to: Date,
+): MetricTimeSeries {
+  const dataPoints: MetricDataPoint[] = [];
+  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: string, days: number = 7): MetricsSummary {
+  const now = new Date();
+  const from = new Date(now);
+  from.setDate(now.getDate() - days);
+  
+  const metricValues: Partial<Record<MetricName, number[]>> = {};
+  const metricCurrent: Partial<Record<MetricName, number>> = {};
+  
+  for (const metric of ['cycles_balance', 'memory_heap', 'message_count', 'request_count', 'error_count'] as MetricName[]) {
+    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: MetricsSummary = {
+    canisterId,
+    metrics: {} as Record<MetricName, { current: number; min: number; max: number; avg: number; delta?: number }>,
+    period: { start: from, end: now },
+  };
+  
+  for (const [metric, values] of Object.entries(metricValues)) {
+    if (values) {
+      const currentValue = metricCurrent[metric as MetricName];
+      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 as MetricName] = {
+          current: currentValue,
+          min,
+          max,
+          avg,
+        };
+      }
+    }
+  }
+  
+  return summary;
+}
+
+export function pruneOldData(canisterId: string, retentionDays: number): void {
+  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: string,
+  config: CollectorConfig = {},
+): NodeJS.Timeout {
+  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);
+}

package/src/monitoring/alerting.ts

@@ -0,0 +1,190 @@
+/**
+ * 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';
+import type {
+  MonitoringAlert,
+  CanisterStatusInfo,
+  HealthThresholds,
+} from './types.js';
+
+/**
+ * Default alert storage path
+ */
+const ALERTS_DIR = path.join(process.env.HOME || process.cwd(), '.agentvault', 'alerts');
+
+/**
+ * Alert storage file path
+ */
+const getAlertFilePath = (canisterId: string) =>
+  path.join(ALERTS_DIR, `${canisterId}.json`);
+
+/**
+ * Load alerts from storage.
+ *
+ * @param canisterId - Canister ID
+ * @returns Stored alerts array
+ */
+export function loadAlerts(canisterId: string): MonitoringAlert[] {
+  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: string, alerts: MonitoringAlert[]): void {
+  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: string, alert: MonitoringAlert): void {
+  const alerts = loadAlerts(canisterId);
+  alerts.push(alert);
+  saveAlerts(canisterId, alerts);
+}
+
+/**
+ * Clear alerts for a canister.
+ *
+ * @param canisterId - Canister ID
+ */
+export function clearAlerts(canisterId: string): void {
+  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: CanisterStatusInfo,
+  thresholds: HealthThresholds = {},
+): MonitoringAlert[] {
+  const alerts: MonitoringAlert[] = [];
+
+  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: string,
+  limit: number = 10,
+): MonitoringAlert[] {
+  const alerts = loadAlerts(canisterId);
+  return alerts.slice(-limit);
+}

package/src/monitoring/health.ts

@@ -0,0 +1,197 @@
+/**
+ * Health Monitoring
+ *
+ * Performs health checks on canisters and determines overall health status
+ * based on resource usage thresholds.
+ */
+
+import { getCanisterInfo } from './info.js';
+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 function determineHealthStatus(
+  statusInfo: CanisterStatusInfo,
+  thresholds: HealthThresholds = {},
+): CanisterHealthStatus {
+  // 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: CanisterStatusInfo,
+  thresholds: HealthThresholds = {},
+  currentHealth: CanisterHealthStatus = 'healthy',
+): MonitoringAlert[] {
+  const alerts: MonitoringAlert[] = [];
+
+  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: bigint): string {
+  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: string,
+  options?: Partial<MonitoringOptions>,
+): Promise<CanisterStatusInfo> {
+  const monitoringOptions: 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: string[],
+  options?: Partial<MonitoringOptions>,
+): Promise<CanisterStatusInfo[]> {
+  const results = await Promise.all(
+    canisterIds.map((id) => getCanisterInfo(id, { canister: id, ...options }))
+  );
+
+  return results.map((statusInfo) => ({
+    ...statusInfo,
+    health: determineHealthStatus(statusInfo, options?.thresholds ?? {}),
+  }));
+}

package/src/monitoring/index.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+
+// Types
+export type {
+  CanisterHealthStatus,
+  CanisterStatusInfo,
+  HealthThresholds,
+  MonitoringOptions,
+  MonitoringAlert,
+  AlertSeverity,
+  ResourceUsageSnapshot,
+} from './types.js';