lightman-agent 1.0.0

package/src/lib/types.ts

@@ -0,0 +1,176 @@
+// --- Agent Configuration ---
+export interface AgentConfig {
+  serverUrl: string;
+  deviceSlug: string;
+  healthIntervalMs: number;
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+  logFile: string;
+  identityFile: string;
+  /** When false, agent runs in kiosk-only mode — no local server/display processes. Default: true */
+  localServices: boolean;
+  kiosk?: KioskConfig;
+  screenshot?: ScreenshotConfig;
+  powerSchedule?: PowerScheduleConfig;
+  /** Port for the local hardware event WebSocket server (default: 3402) */
+  localEventsPort?: number;
+}
+
+// --- Device Identity (persisted locally) ---
+export interface Identity {
+  deviceId: string;
+  apiKey: string;
+}
+
+// --- WebSocket Messages ---
+export interface WsMessage {
+  type: string;
+  payload?: Record<string, unknown>;
+  timestamp: number;
+}
+
+// --- Health Report ---
+export interface HealthReport {
+  cpuUsage: number;
+  memTotal: number;
+  memUsed: number;
+  memPercent: number;
+  diskTotal: number;
+  diskUsed: number;
+  diskPercent: number;
+  cpuTemp: number | null;
+  uptime: number;
+  agentVersion: string;
+  // RPi-specific fields (optional, only present on Raspberry Pi)
+  gpuTemp?: number | null;
+  throttled?: number | null;
+  sdCardReadOnly?: boolean;
+  // Network info (optional)
+  network?: {
+    interface: string;
+    ip: string;
+    mac: string;
+    serverLatencyMs: number | null;
+  };
+}
+
+// --- Command Execution ---
+export interface CommandRequest {
+  id: string;
+  command: string;
+  args?: Record<string, unknown>;
+  timeout?: number;
+}
+
+export interface CommandResult {
+  id: string;
+  command: string;
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: string;
+  durationMs: number;
+}
+
+// --- Kiosk Configuration ---
+export interface KioskConfig {
+  browserPath: string;
+  defaultUrl: string;
+  extraArgs: string[];
+  pollIntervalMs: number;
+  maxCrashesInWindow: number;
+  crashWindowMs: number;
+  /** Shell replacement mode: Chrome is launched by the Windows shell (lightman-shell.bat),
+   *  not by the agent. Agent only manages URL changes and monitors Chrome via process list. */
+  shellMode?: boolean;
+}
+
+// --- Multi-Screen Configuration ---
+
+/** Mapping of a physical screen to a URL (stored in device config, pushed from admin) */
+export interface ScreenMapping {
+  /** Hardware display ID, e.g. "\\\\.\\DISPLAY1" or "HDMI-1" */
+  hardwareId: string;
+  /** URL to open on this screen */
+  url: string;
+  /** Optional label for admin display */
+  label?: string;
+}
+
+// --- Kiosk Status ---
+export interface KioskStatus {
+  running: boolean;
+  pid: number | null;
+  url: string | null;
+  crashCount: number;
+  crashLoopDetected: boolean;
+  uptimeMs: number | null;
+}
+
+/** Status for multi-screen kiosk */
+export interface MultiScreenKioskStatus {
+  screens: SingleScreenStatus[];
+}
+
+export interface SingleScreenStatus {
+  hardwareId: string;
+  url: string | null;
+  running: boolean;
+  pid: number | null;
+  uptimeMs: number | null;
+}
+
+// --- Screenshot Configuration ---
+export interface ScreenshotConfig {
+  captureCommand: string;
+  quality: number;
+  uploadEndpoint: string;
+}
+
+// --- Command Handler Function ---
+export type CommandHandler = (
+  args?: Record<string, unknown>
+) => Promise<Record<string, unknown> | void>;
+
+// --- Log Forwarding ---
+export interface LogEntry {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  source: string;
+}
+
+// --- Power Schedule ---
+export interface PowerScheduleConfig {
+  /** Cron expression for shutdown (e.g., "0 19 * * *" = 7 PM daily) */
+  shutdownCron?: string;
+  /** Cron expression for startup prep — agent uses this only for logging; actual wake is via WOL */
+  startupCron?: string;
+  /** Timezone for cron expressions (e.g., "Asia/Kolkata"). Defaults to system timezone. */
+  timezone?: string;
+  /** Seconds before shutdown to warn via WebSocket (default: 60) */
+  shutdownWarningSeconds?: number;
+}
+
+// --- Watchdog & Self-Healing ---
+export interface WatchdogConfig {
+  checkIntervalMs: number;
+  kioskCrashCooldownMs: number;
+  highMemoryThresholdMb: number;
+  highMemoryCooldownMs: number;
+  highDiskThresholdPercent: number;
+  highDiskCooldownMs: number;
+  wsDisconnectedThresholdMs: number;
+  wsDisconnectedCooldownMs: number;
+}
+
+export interface CrashReport {
+  process: string;
+  exitCode: number | null;
+  signal: string | null;
+  timestamp: string;
+  system: {
+    memPercent: number;
+    diskPercent: number;
+    cpuUsage: number;
+    uptime: number;
+  };
+}

package/src/services/commands.ts

@@ -0,0 +1,107 @@
+import type {
+  CommandRequest,
+  CommandResult,
+  CommandHandler,
+  WsMessage,
+} from '../lib/types.js';
+import type { WsClient } from './websocket.js';
+import type { Logger } from '../lib/logger.js';
+
+export class CommandExecutor {
+  private registry = new Map<string, CommandHandler>();
+  private wsClient: WsClient;
+  private logger: Logger;
+
+  constructor(wsClient: WsClient, logger: Logger) {
+    this.wsClient = wsClient;
+    this.logger = logger;
+  }
+
+  register(command: string, handler: CommandHandler): void {
+    this.registry.set(command, handler);
+    this.logger.debug(`Command registered: ${command}`);
+  }
+
+  getRegisteredCommands(): string[] {
+    return Array.from(this.registry.keys());
+  }
+
+  /**
+   * Handle an incoming command message from the server.
+   * Lifecycle: validate → ack → execute → result
+   */
+  async handleCommand(msg: WsMessage): Promise<void> {
+    const request = msg.payload as unknown as CommandRequest;
+
+    if (!request || !request.id || !request.command) {
+      this.logger.warn('Invalid command request:', msg);
+      return;
+    }
+
+    this.logger.info(`Command received: ${request.command} (${request.id})`);
+
+    // Check if command is registered
+    const handler = this.registry.get(request.command);
+    if (!handler) {
+      this.sendResult({
+        id: request.id,
+        command: request.command,
+        success: false,
+        error: `Unknown command: ${request.command}`,
+        durationMs: 0,
+      });
+      return;
+    }
+
+    // Send ack
+    this.wsClient.send({
+      type: 'agent:command_ack',
+      payload: { id: request.id, command: request.command },
+      timestamp: Date.now(),
+    });
+
+    // Execute with timeout
+    const start = Date.now();
+    const timeout = request.timeout || 30_000;
+    let timeoutId: NodeJS.Timeout | undefined;
+
+    try {
+      const data = await Promise.race([
+        handler(request.args),
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error('Command timed out')), timeout);
+        }),
+      ]);
+      clearTimeout(timeoutId);
+
+      this.sendResult({
+        id: request.id,
+        command: request.command,
+        success: true,
+        data: (data as Record<string, unknown>) || {},
+        durationMs: Date.now() - start,
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      this.sendResult({
+        id: request.id,
+        command: request.command,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - start,
+      });
+    }
+  }
+
+  private sendResult(result: CommandResult): void {
+    this.logger.info(
+      `Command result: ${result.command} (${result.id}) → ${result.success ? 'OK' : 'FAIL'} in ${result.durationMs}ms`
+    );
+
+    this.wsClient.send({
+      type: 'agent:command_result',
+      payload: result as unknown as Record<string, unknown>,
+      timestamp: Date.now(),
+    });
+  }
+}

package/src/services/health.ts

@@ -0,0 +1,161 @@
+import si from 'systeminformation';
+import net from 'net';
+import { URL } from 'url';
+import type { HealthReport, WsMessage } from '../lib/types.js';
+import type { WsClient } from './websocket.js';
+import type { Logger } from '../lib/logger.js';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { isRaspberryPi, getGpuTemp, getThrottled, isSdCardReadOnly } from '../lib/rpi.js';
+
+export class HealthMonitor {
+  private wsClient: WsClient;
+  private logger: Logger;
+  private intervalMs: number;
+  private timer: NodeJS.Timeout | null = null;
+  private agentVersion: string;
+  private serverUrl: string;
+
+  constructor(wsClient: WsClient, logger: Logger, intervalMs: number, serverUrl?: string) {
+    this.wsClient = wsClient;
+    this.logger = logger;
+    this.intervalMs = intervalMs;
+    this.serverUrl = serverUrl || '';
+
+    // Read version from package.json
+    try {
+      const pkg = JSON.parse(
+        readFileSync(resolve(process.cwd(), 'package.json'), 'utf-8')
+      );
+      this.agentVersion = pkg.version || '0.0.0';
+    } catch {
+      this.agentVersion = '0.0.0';
+    }
+  }
+
+  start(): void {
+    this.logger.info(`Health monitor started (interval: ${this.intervalMs}ms)`);
+
+    // Send initial report after a short delay
+    setTimeout(() => {
+      this.collectAndSend();
+    }, 5_000);
+
+    this.timer = setInterval(() => {
+      this.collectAndSend();
+    }, this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.logger.info('Health monitor stopped');
+  }
+
+  async collect(): Promise<HealthReport> {
+    const [cpu, mem, disk, temp] = await Promise.all([
+      si.currentLoad(),
+      si.mem(),
+      si.fsSize(),
+      si.cpuTemperature(),
+    ]);
+
+    // Use the first/main disk
+    const mainDisk = disk[0] || { size: 0, used: 0, use: 0 };
+
+    const report: HealthReport = {
+      cpuUsage: Math.round(cpu.currentLoad * 100) / 100,
+      memTotal: mem.total,
+      memUsed: mem.used,
+      memPercent: mem.total > 0 ? Math.round((mem.used / mem.total) * 10000) / 100 : 0,
+      diskTotal: mainDisk.size,
+      diskUsed: mainDisk.used,
+      diskPercent: Math.round(mainDisk.use * 100) / 100,
+      cpuTemp: temp.main !== null ? Math.round(temp.main * 10) / 10 : null,
+      uptime: Math.round(process.uptime()),
+      agentVersion: this.agentVersion,
+    };
+
+    // Add RPi-specific fields when running on Raspberry Pi
+    if (isRaspberryPi()) {
+      report.gpuTemp = getGpuTemp();
+      report.throttled = getThrottled();
+      report.sdCardReadOnly = isSdCardReadOnly();
+    }
+
+    // Add network info
+    try {
+      const ifaces = await si.networkInterfaces();
+      const ifaceList = Array.isArray(ifaces) ? ifaces : [ifaces];
+      const primary = ifaceList.find((i) => !i.internal && i.ip4) || null;
+
+      if (primary) {
+        let serverLatencyMs: number | null = null;
+        if (this.serverUrl) {
+          try {
+            const url = new URL(this.serverUrl);
+            const host = url.hostname;
+            const port = parseInt(url.port, 10) || 3001;
+            const start = Date.now();
+            const reachable = await this.tcpPing(host, port, 5000);
+            serverLatencyMs = reachable ? Date.now() - start : null;
+          } catch {
+            // Ignore ping errors in health collection
+          }
+        }
+
+        report.network = {
+          interface: primary.iface,
+          ip: primary.ip4,
+          mac: primary.mac,
+          serverLatencyMs,
+        };
+      }
+    } catch {
+      // Network info is optional, don't fail health collection
+    }
+
+    return report;
+  }
+
+  private tcpPing(host: string, port: number, timeoutMs: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      const socket = new net.Socket();
+      let resolved = false;
+
+      const done = (result: boolean) => {
+        if (resolved) return;
+        resolved = true;
+        socket.destroy();
+        resolve(result);
+      };
+
+      socket.setTimeout(timeoutMs);
+      socket.on('connect', () => done(true));
+      socket.on('timeout', () => done(false));
+      socket.on('error', () => done(false));
+      socket.connect(port, host);
+    });
+  }
+
+  private async collectAndSend(): Promise<void> {
+    try {
+      const report = await this.collect();
+      const msg: WsMessage = {
+        type: 'agent:health',
+        payload: report as unknown as Record<string, unknown>,
+        timestamp: Date.now(),
+      };
+      this.wsClient.send(msg);
+      this.logger.debug('Health report sent', {
+        cpu: report.cpuUsage,
+        mem: report.memPercent,
+        disk: report.diskPercent,
+      });
+    } catch (err) {
+      this.logger.error('Failed to collect health data:', err);
+    }
+  }
+}