agent-relay 1.1.0 → 1.2.3

package/dist/resiliency/memory-monitor.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent Memory Monitor
+ *
+ * Comprehensive memory monitoring for agent processes:
+ * - Detailed memory metrics (RSS, heap, external)
+ * - Memory trend analysis (growing/stable/shrinking)
+ * - High watermark tracking
+ * - Configurable thresholds for proactive alerting
+ * - Memory history for trend analysis
+ * - Crash prevention through memory pressure detection
+ */
+import { EventEmitter } from 'events';
+export interface MemorySnapshot {
+    timestamp: Date;
+    rssBytes: number;
+    heapUsedBytes: number;
+    heapTotalBytes: number;
+    externalBytes: number;
+    cpuPercent: number;
+}
+export interface AgentMemoryMetrics {
+    name: string;
+    pid: number;
+    current: MemorySnapshot;
+    highWatermark: number;
+    lowWatermark: number;
+    averageRss: number;
+    trend: 'growing' | 'stable' | 'shrinking' | 'unknown';
+    trendRatePerMinute: number;
+    alertLevel: 'normal' | 'warning' | 'critical' | 'oom_imminent';
+    lastAlertAt?: Date;
+    memoryHistory: MemorySnapshot[];
+    startedAt: Date;
+    uptimeMs: number;
+}
+export interface MemoryThresholds {
+    warningBytes: number;
+    criticalBytes: number;
+    oomImminentBytes: number;
+    trendGrowthRateWarning: number;
+    historyRetentionMinutes: number;
+    historyMaxSamples: number;
+}
+export interface MemoryMonitorConfig {
+    checkIntervalMs: number;
+    thresholds: MemoryThresholds;
+    enableTrendAnalysis: boolean;
+    enableProactiveAlerts: boolean;
+}
+export interface MemoryAlert {
+    type: 'warning' | 'critical' | 'oom_imminent' | 'trend_warning' | 'recovered';
+    agentName: string;
+    pid: number;
+    currentRss: number;
+    threshold: number;
+    message: string;
+    recommendation: string;
+    timestamp: Date;
+}
+export interface CrashMemoryContext {
+    agentName: string;
+    pid: number;
+    crashTime: Date;
+    lastKnownMemory: MemorySnapshot | null;
+    peakMemory: number;
+    averageMemory: number;
+    memoryTrend: string;
+    recentHistory: MemorySnapshot[];
+    likelyCause: 'oom' | 'memory_leak' | 'sudden_spike' | 'unknown';
+    analysisNotes: string[];
+}
+export declare class AgentMemoryMonitor extends EventEmitter {
+    private agents;
+    private pids;
+    private intervalId?;
+    private config;
+    private isRunning;
+    private alertCooldowns;
+    constructor(config?: Partial<MemoryMonitorConfig>);
+    /**
+     * Register an agent for memory monitoring
+     */
+    register(name: string, pid: number): void;
+    /**
+     * Update PID for an agent (after restart)
+     */
+    updatePid(name: string, newPid: number): void;
+    /**
+     * Unregister an agent
+     */
+    unregister(name: string): void;
+    /**
+     * Start memory monitoring
+     */
+    start(): void;
+    /**
+     * Stop memory monitoring
+     */
+    stop(): void;
+    /**
+     * Get memory metrics for all agents
+     */
+    getAll(): AgentMemoryMetrics[];
+    /**
+     * Get memory metrics for a specific agent
+     */
+    get(name: string): AgentMemoryMetrics | undefined;
+    /**
+     * Get crash context for an agent (for crash analysis)
+     */
+    getCrashContext(name: string): CrashMemoryContext;
+    /**
+     * Get system-wide memory summary
+     */
+    getSystemSummary(): {
+        totalAgents: number;
+        totalMemoryBytes: number;
+        agentsByAlertLevel: Record<string, number>;
+        topMemoryConsumers: Array<{
+            name: string;
+            rssBytes: number;
+        }>;
+        systemMemory: {
+            total: number;
+            free: number;
+            available: number;
+        };
+    };
+    /**
+     * Sample memory for all registered agents
+     */
+    private sampleAll;
+    /**
+     * Sample memory for a single agent
+     */
+    private sampleAgent;
+    /**
+     * Update metrics with new snapshot
+     */
+    private updateMetrics;
+    /**
+     * Analyze memory trend
+     */
+    private analyzeTrend;
+    /**
+     * Check and emit alerts
+     */
+    private checkAlerts;
+    /**
+     * Get memory for a process using ps
+     */
+    private getProcessMemory;
+    /**
+     * Get system memory info
+     */
+    private getSystemMemory;
+    /**
+     * Check if a process is alive
+     */
+    private isProcessAlive;
+    /**
+     * Structured logging
+     */
+    private log;
+}
+/**
+ * Format bytes for human-readable display
+ */
+declare function formatBytes(bytes: number): string;
+export { formatBytes };
+export declare function getMemoryMonitor(config?: Partial<MemoryMonitorConfig>): AgentMemoryMonitor;
+//# sourceMappingURL=memory-monitor.d.ts.map