@appkit/llamacpp-cli 1.4.1 → 1.6.0

package/src/types/history-types.ts

@@ -0,0 +1,39 @@
+// Historical monitoring data types
+
+export interface HistorySnapshot {
+  timestamp: number; // Unix timestamp in milliseconds
+  server: {
+    healthy: boolean;
+    uptime?: string;
+    activeSlots: number;
+    idleSlots: number;
+    totalSlots: number;
+    avgPromptSpeed?: number;       // Tokens per second
+    avgGenerateSpeed?: number;     // Tokens per second
+    processMemory?: number;        // Bytes (RSS)
+    processCpuUsage?: number;      // Percentage (0-100+) from ps
+  };
+  system?: {
+    gpuUsage?: number;             // Percentage (0-100)
+    cpuUsage?: number;             // Percentage (0-100)
+    aneUsage?: number;             // Percentage (0-100)
+    temperature?: number;          // Celsius
+    memoryUsed: number;            // Bytes
+    memoryTotal: number;           // Bytes
+  };
+}
+
+export interface HistoryData {
+  serverId: string;
+  snapshots: HistorySnapshot[];
+}
+
+export type TimeWindow = '1h' | '6h' | '24h';
+
+export const TIME_WINDOW_HOURS: Record<TimeWindow, number> = {
+  '1h': 1,
+  '6h': 6,
+  '24h': 24,
+};
+
+export const TIME_WINDOWS: TimeWindow[] = ['1h', '6h', '24h'];

package/src/types/monitor-types.ts

@@ -0,0 +1,162 @@
+import { ServerConfig } from './server-config.js';
+
+// llama.cpp API response types
+
+export interface HealthResponse {
+  status: string;
+  error?: string;
+}
+
+export interface PropsResponse {
+  default_generation_settings: {
+    n_ctx: number;
+    n_predict: number;
+    model: string;
+    seed: number;
+    temperature: number;
+    top_k: number;
+    top_p: number;
+    min_p: number;
+    n_keep: number;
+    stream: boolean;
+  };
+  total_slots: number;
+  model_loaded: boolean;
+  model_path: string;
+  model_alias?: string;
+}
+
+export interface SlotInfo {
+  id: number;
+  state: 'idle' | 'processing';
+  task_id?: number;
+  prompt?: string;
+  n_prompt_tokens?: number;
+  n_decoded?: number;
+  n_ctx: number;
+  truncated?: boolean;
+  stopped_eos?: boolean;
+  stopped_word?: boolean;
+  stopped_limit?: boolean;
+  stopping_word?: string;
+  tokens_predicted?: number;
+  tokens_evaluated?: number;
+  generation_settings?: {
+    n_ctx: number;
+    n_predict: number;
+    seed: number;
+    temperature: number;
+    top_k: number;
+    top_p: number;
+  };
+  prompt_tokens_processed?: number;
+  t_prompt_processing?: number;  // Time in ms
+  t_token_generation?: number;     // Time in ms
+  timings?: {
+    prompt_n: number;
+    prompt_ms: number;
+    prompt_per_token_ms: number;
+    prompt_per_second: number;
+    predicted_n: number;
+    predicted_ms: number;
+    predicted_per_token_ms: number;
+    predicted_per_second: number;
+  };
+}
+
+export interface SlotsResponse {
+  slots: SlotInfo[];
+}
+
+// System metrics types
+
+export interface SystemMetrics {
+  // GPU/CPU/ANE (from macmon if available)
+  gpuUsage?: number;          // Percentage (0-100)
+  cpuUsage?: number;          // Percentage (0-100)
+  cpuCores?: number;          // Number of cores
+  aneUsage?: number;          // Apple Neural Engine percentage (0-100)
+  temperature?: number;        // GPU temperature in Celsius
+
+  // Memory (from vm_stat or macmon)
+  memoryUsed: number;         // Bytes
+  memoryTotal: number;        // Bytes
+  swapUsed?: number;          // Bytes
+  processMemory?: number;     // Bytes (specific to llama-server process)
+
+  // Metadata
+  timestamp: number;
+  source: 'macmon' | 'vm_stat' | 'none';
+  warnings?: string[];        // e.g., "macmon not available, showing memory only"
+}
+
+// Aggregated metrics for TUI display
+
+export interface ServerMetrics {
+  // Server identification
+  server: ServerConfig;
+
+  // Health status
+  healthy: boolean;
+  uptime?: string;            // Human-readable (e.g., "2h 34m 12s")
+  error?: string;
+
+  // Model information
+  modelLoaded: boolean;
+  modelName: string;
+  contextSize: number;
+  totalSlots: number;
+
+  // Request metrics
+  activeSlots: number;
+  idleSlots: number;
+  slots: SlotInfo[];
+
+  // Performance metrics (derived from slots)
+  avgPromptSpeed?: number;    // Tokens per second
+  avgGenerateSpeed?: number;  // Tokens per second
+  requestsPerMinute?: number; // Estimated from slot activity
+  avgLatency?: number;        // Milliseconds
+
+  // Cache metrics (if available from /metrics endpoint)
+  cacheHitRate?: number;      // Percentage
+
+  // Process metrics
+  processMemory?: number;     // Bytes (actual RSS from top command)
+  processCpuUsage?: number;   // Percentage (0-100+) from ps command
+
+  // Timestamp
+  timestamp: number;
+  stale: boolean;             // True if data is from last successful fetch
+}
+
+export interface MonitorData {
+  server: ServerMetrics;
+  system?: SystemMetrics;
+  lastUpdated: Date;
+  updateInterval: number;     // Milliseconds
+  consecutiveFailures: number;
+}
+
+// Error and loading states
+
+export interface ErrorState {
+  error: string;
+  canRetry: boolean;
+  suggestions?: string[];
+}
+
+export interface LoadingState {
+  message: string;
+  progress?: number;          // 0-100 if determinate
+}
+
+// Collection result (for graceful degradation)
+
+export interface CollectionResult<T> {
+  success: boolean;
+  data: T | null;
+  error?: string;
+  warnings?: string[];
+  stale?: boolean;
+}

package/src/types/server-config.ts

@@ -22,6 +22,7 @@ export interface ServerConfig {
   createdAt: string;       // ISO timestamp
   lastStarted?: string;    // ISO timestamp
   lastStopped?: string;    // ISO timestamp
+  metalMemoryMB?: number;  // Metal (GPU) memory allocated in MB (parsed from logs)
 
   // launchctl metadata
   plistPath: string;       // Full path to plist file

package/src/utils/downsample-utils.ts

@@ -0,0 +1,128 @@
+/**
+ * Downsampling utilities for time-series chart data
+ * Uses time-aligned buckets to ensure stable charts as new data arrives
+ */
+
+export interface TimeSeriesPoint {
+  timestamp: number;
+  value: number;
+}
+
+type AggregationMethod = 'max' | 'mean';
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+/**
+ * Core bucketing logic shared by all downsampling functions.
+ * Uses ABSOLUTE bucket boundaries that never shift, ensuring chart stability.
+ */
+function createTimeBuckets(
+  data: TimeSeriesPoint[],
+  targetPoints: number,
+  startTime: number,
+  endTime: number
+): number[][] {
+  const timeRange = endTime - startTime;
+  const bucketDuration = Math.ceil(timeRange / targetPoints);
+  const alignedStart = Math.floor(startTime / bucketDuration) * bucketDuration;
+  const buckets: number[][] = Array.from({ length: targetPoints }, () => []);
+
+  for (const point of data) {
+    if (point.timestamp < startTime || point.timestamp > endTime) continue;
+    const bucketIndex = Math.floor((point.timestamp - alignedStart) / bucketDuration);
+    if (bucketIndex >= 0 && bucketIndex < targetPoints) {
+      buckets[bucketIndex].push(point.value);
+    }
+  }
+
+  return buckets;
+}
+
+/**
+ * Aggregate bucket values using the specified method.
+ */
+function aggregateBuckets(buckets: number[][], method: AggregationMethod): number[] {
+  return buckets.map(bucket => {
+    const validValues = method === 'max'
+      ? bucket.filter(v => !isNaN(v) && v > 0)
+      : bucket.filter(v => !isNaN(v) && isFinite(v));
+
+    if (validValues.length === 0) return 0;
+
+    if (method === 'max') {
+      return Math.max(...validValues);
+    }
+    return validValues.reduce((sum, v) => sum + v, 0) / validValues.length;
+  });
+}
+
+/**
+ * Downsample using time-aligned bucket max - preserves peaks.
+ * Best for: GPU/CPU usage, token speeds where peaks matter.
+ */
+export function downsampleMaxTime(data: TimeSeriesPoint[], targetPoints: number): number[] {
+  if (data.length === 0) return [];
+  if (data.length <= targetPoints) return data.map(d => d.value);
+
+  const buckets = createTimeBuckets(
+    data,
+    targetPoints,
+    data[0].timestamp,
+    data[data.length - 1].timestamp
+  );
+  return aggregateBuckets(buckets, 'max');
+}
+
+/**
+ * Downsample using time-aligned bucket mean - preserves average trends.
+ * Best for: Memory usage where average is meaningful.
+ */
+export function downsampleMeanTime(data: TimeSeriesPoint[], targetPoints: number): number[] {
+  if (data.length === 0) return [];
+  if (data.length <= targetPoints) return data.map(d => d.value);
+
+  const buckets = createTimeBuckets(
+    data,
+    targetPoints,
+    data[0].timestamp,
+    data[data.length - 1].timestamp
+  );
+  return aggregateBuckets(buckets, 'mean');
+}
+
+/**
+ * Calculate downsampling ratio as a display string.
+ */
+export function getDownsampleRatio(originalCount: number, targetCount: number): string {
+  if (originalCount <= targetCount) return '1:1';
+  const ratio = Math.round(originalCount / targetCount);
+  return `${ratio}:1`;
+}
+
+/**
+ * Downsample with full hour coverage using max aggregation.
+ * Creates buckets for the entire hour (60 minutes), filling gaps with 0.
+ * Best for: Hour view where we want to show the full time range.
+ */
+export function downsampleMaxTimeWithFullHour(data: TimeSeriesPoint[], targetPoints: number): number[] {
+  if (data.length === 0) return Array(targetPoints).fill(0);
+
+  const now = Date.now();
+  const oneHourAgo = now - ONE_HOUR_MS;
+  const buckets = createTimeBuckets(data, targetPoints, oneHourAgo, now);
+  return aggregateBuckets(buckets, 'max');
+}
+
+/**
+ * Downsample with full hour coverage using mean aggregation.
+ * Creates buckets for the entire hour (60 minutes), filling gaps with 0.
+ * Best for: Hour view where we want to show the full time range.
+ */
+export function downsampleMeanTimeWithFullHour(data: TimeSeriesPoint[], targetPoints: number): number[] {
+  if (data.length === 0) return Array(targetPoints).fill(0);
+
+  const now = Date.now();
+  const oneHourAgo = now - ONE_HOUR_MS;
+  const buckets = createTimeBuckets(data, targetPoints, oneHourAgo, now);
+  return aggregateBuckets(buckets, 'mean');
+}

package/src/utils/file-utils.ts

@@ -104,3 +104,43 @@ export function expandHome(filePath: string): string {
   }
   return filePath;
 }
+
+/**
+ * Parse Metal (GPU) memory allocation from llama-server stderr logs
+ * Looks for line: "load_tensors: Metal_Mapped model buffer size = 11120.23 MiB"
+ * Returns memory in MB, or null if not found
+ */
+export async function parseMetalMemoryFromLog(stderrPath: string): Promise<number | null> {
+  try {
+    // Check if log file exists
+    if (!(await fileExists(stderrPath))) {
+      return null;
+    }
+
+    // Open file for reading
+    const fileHandle = await fs.open(stderrPath, 'r');
+
+    try {
+      // Read first 256KB (Metal allocation happens early during model loading)
+      const buffer = Buffer.alloc(256 * 1024);
+      const { bytesRead } = await fileHandle.read(buffer, 0, buffer.length, 0);
+      const content = buffer.toString('utf-8', 0, bytesRead);
+      const lines = content.split('\n');
+
+      // Look for Metal_Mapped buffer size
+      for (const line of lines) {
+        const match = line.match(/Metal_Mapped model buffer size\s*=\s*([\d.]+)\s*MiB/);
+        if (match) {
+          const sizeInMB = parseFloat(match[1]);
+          return isNaN(sizeInMB) ? null : sizeInMB;
+        }
+      }
+
+      return null;
+    } finally {
+      await fileHandle.close();
+    }
+  } catch {
+    return null;
+  }
+}

package/src/utils/process-utils.ts

@@ -1,4 +1,4 @@
-import { exec } from 'child_process';
+import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 
 export const execAsync = promisify(exec);
@@ -60,39 +60,257 @@ export async function isPortInUse(port: number): Promise<boolean> {
 }
 
 /**
- * Get memory usage for a process in bytes
- * Uses 'top' on macOS which includes GPU/Metal memory (more accurate for llama-server)
+ * Spawn a streaming command, read one line, and kill it
+ * Useful for commands like 'macmon pipe' that stream indefinitely
+ * Ensures the process is killed to prevent leaks
+ */
+export async function spawnAndReadOneLine(
+  command: string,
+  args: string[],
+  timeoutMs: number = 2000
+): Promise<string | null> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      detached: false, // Keep in same process group for easier cleanup
+    });
+
+    let resolved = false;
+    let output = '';
+
+    const cleanup = () => {
+      try {
+        // Try SIGKILL immediately (SIGTERM may not work for macmon)
+        child.kill('SIGKILL');
+      } catch {
+        // Process might already be dead
+      }
+    };
+
+    // Set timeout to kill process if it doesn't produce output
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(null);
+      }
+    }, timeoutMs);
+
+    // Read stdout line by line
+    child.stdout?.on('data', (data) => {
+      if (resolved) return;
+
+      output += data.toString();
+
+      // Check if we have a complete line
+      const newlineIndex = output.indexOf('\n');
+      if (newlineIndex !== -1) {
+        const line = output.substring(0, newlineIndex).trim();
+
+        if (line.length > 0) {
+          resolved = true;
+          clearTimeout(timeout);
+          cleanup();
+          resolve(line);
+        }
+      }
+    });
+
+    // Handle process errors
+    child.on('error', () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve(null);
+      }
+    });
+
+    // Handle process exit
+    child.on('exit', () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+
+        // Return partial output if we have any
+        const line = output.trim();
+        resolve(line.length > 0 ? line : null);
+      }
+    });
+  });
+}
+
+// Process memory cache to prevent spawning too many 'top' processes
+// Cache per PID with 3-second TTL
+const processMemoryCache = new Map<number, { value: number | null; timestamp: number }>();
+const PROCESS_MEMORY_CACHE_TTL = 3000; // 3 seconds
+
+/**
+ * Batch get memory usage for multiple processes in one top call
+ * Much more efficient than calling getProcessMemory() multiple times
+ * Returns Map<pid, bytes> for all requested PIDs
+ */
+export async function getBatchProcessMemory(pids: number[]): Promise<Map<number, number | null>> {
+  const result = new Map<number, number | null>();
+  const now = Date.now();
+
+  // Check cache and collect PIDs that need fetching
+  const pidsToFetch: number[] = [];
+  for (const pid of pids) {
+    const cached = processMemoryCache.get(pid);
+    if (cached && (now - cached.timestamp) < PROCESS_MEMORY_CACHE_TTL) {
+      result.set(pid, cached.value);
+    } else {
+      pidsToFetch.push(pid);
+    }
+  }
+
+  // If all PIDs were cached, return early
+  if (pidsToFetch.length === 0) {
+    return result;
+  }
+
+  try {
+    // Build top command with all PIDs: top -l 1 -pid X -pid Y -pid Z -stats pid,mem
+    const pidArgs = pidsToFetch.map(pid => `-pid ${pid}`).join(' ');
+    const output = await execCommand(`top -l 1 ${pidArgs} -stats pid,mem 2>/dev/null`);
+
+    // Parse output: each line is "PID  MEM" (e.g., "1438  299M")
+    const lines = output.split('\n');
+    for (const line of lines) {
+      const match = line.trim().match(/^(\d+)\s+([\d.]+)([KMGT])\s*$/);
+      if (!match) continue;
+
+      const pid = parseInt(match[1], 10);
+      const value = parseFloat(match[2]);
+      const unit = match[3];
+
+      // Convert to bytes
+      const multipliers: { [key: string]: number } = {
+        K: 1024,
+        M: 1024 * 1024,
+        G: 1024 * 1024 * 1024,
+        T: 1024 * 1024 * 1024 * 1024,
+      };
+
+      const bytes = Math.round(value * multipliers[unit]);
+
+      // Cache and store result
+      processMemoryCache.set(pid, { value: bytes, timestamp: now });
+      result.set(pid, bytes);
+    }
+
+    // For any PIDs that weren't in the output, cache null
+    for (const pid of pidsToFetch) {
+      if (!result.has(pid)) {
+        processMemoryCache.set(pid, { value: null, timestamp: now });
+        result.set(pid, null);
+      }
+    }
+
+    return result;
+  } catch {
+    // On error, cache null for all requested PIDs
+    for (const pid of pidsToFetch) {
+      processMemoryCache.set(pid, { value: null, timestamp: now });
+      result.set(pid, null);
+    }
+    return result;
+  }
+}
+
+/**
+ * Get memory usage for a single process in bytes
+ * Uses 'top' on macOS which reports CPU memory only (NOT GPU/Metal memory)
  * Returns null if process not found or error occurs
+ * Caches results for 3 seconds to prevent spawning too many top processes
+ *
+ * Note: For llama-server processes with GPU offloading, use ServerConfig.metalMemoryMB
+ * to get GPU memory allocation (parsed from logs during server startup)
+ *
+ * Note: For multiple PIDs, use getBatchProcessMemory() instead - much more efficient
  */
 export async function getProcessMemory(pid: number): Promise<number | null> {
-  try {
-    // Use top with -l 1 (one sample) to get memory stats
-    // MEM column shows resident memory including GPU memory on macOS
-    const output = await execCommand(`top -l 1 -pid ${pid} -stats mem`);
+  const result = await getBatchProcessMemory([pid]);
+  return result.get(pid) ?? null;
+}
+
+// Process CPU cache to prevent spawning too many 'ps' processes
+// Cache per PID with 3-second TTL
+const processCpuCache = new Map<number, { value: number | null; timestamp: number }>();
+const PROCESS_CPU_CACHE_TTL = 3000; // 3 seconds
+
+/**
+ * Batch get CPU usage for multiple processes in one ps call
+ * Much more efficient than calling getProcessCpu() multiple times
+ * Returns Map<pid, percentage> for all requested PIDs
+ */
+export async function getBatchProcessCpu(pids: number[]): Promise<Map<number, number | null>> {
+  const result = new Map<number, number | null>();
+  const now = Date.now();
 
-    // Get the last non-empty line which contains the memory value
-    const lines = output.split('\n').filter((line) => line.trim().length > 0);
-    if (lines.length === 0) return null;
+  // Check cache and collect PIDs that need fetching
+  const pidsToFetch: number[] = [];
+  for (const pid of pids) {
+    const cached = processCpuCache.get(pid);
+    if (cached && (now - cached.timestamp) < PROCESS_CPU_CACHE_TTL) {
+      result.set(pid, cached.value);
+    } else {
+      pidsToFetch.push(pid);
+    }
+  }
 
-    const memStr = lines[lines.length - 1].trim();
+  // If all PIDs were cached, return early
+  if (pidsToFetch.length === 0) {
+    return result;
+  }
 
-    // Parse memory string (e.g., "10.5G", "512M", "1024K", "10G")
-    const match = memStr.match(/^([\d.]+)([KMGT])$/);
-    if (!match) return null;
+  try {
+    // Build ps command with all PIDs: ps -p X,Y,Z -o pid=,%cpu=
+    const pidList = pidsToFetch.join(',');
+    const output = await execCommand(`ps -p ${pidList} -o pid=,%cpu= 2>/dev/null`);
 
-    const value = parseFloat(match[1]);
-    const unit = match[2];
+    // Parse output: each line is "PID  %CPU" (e.g., "1438  45.2")
+    const lines = output.split('\n');
+    for (const line of lines) {
+      const match = line.trim().match(/^(\d+)\s+([\d.]+)\s*$/);
+      if (!match) continue;
 
-    // Convert to bytes
-    const multipliers: { [key: string]: number } = {
-      K: 1024,
-      M: 1024 * 1024,
-      G: 1024 * 1024 * 1024,
-      T: 1024 * 1024 * 1024 * 1024,
-    };
+      const pid = parseInt(match[1], 10);
+      const cpuPercent = parseFloat(match[2]);
+
+      // Cache and store result
+      processCpuCache.set(pid, { value: cpuPercent, timestamp: now });
+      result.set(pid, cpuPercent);
+    }
 
-    return Math.round(value * multipliers[unit]);
+    // For any PIDs that weren't in the output, cache null (process not running)
+    for (const pid of pidsToFetch) {
+      if (!result.has(pid)) {
+        processCpuCache.set(pid, { value: null, timestamp: now });
+        result.set(pid, null);
+      }
+    }
+
+    return result;
   } catch {
-    return null;
+    // On error, cache null for all requested PIDs
+    for (const pid of pidsToFetch) {
+      processCpuCache.set(pid, { value: null, timestamp: now });
+      result.set(pid, null);
+    }
+    return result;
   }
 }
+
+/**
+ * Get CPU usage for a single process as percentage (0-100+)
+ * Uses 'ps -o %cpu' on macOS
+ * Returns null if process not found or error occurs
+ * Caches results for 3 seconds to prevent spawning too many ps processes
+ *
+ * Note: For multiple PIDs, use getBatchProcessCpu() instead - much more efficient
+ */
+export async function getProcessCpu(pid: number): Promise<number | null> {
+  const result = await getBatchProcessCpu([pid]);
+  return result.get(pid) ?? null;
+}