agentvault 1.0.1 → 1.0.5

package/src/metrics/metrics.ts

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

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

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

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