feat(satellite): implement job management system with heartbeat job

Author: Lasim

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "github.copilot.chat.commitMessageGeneration.instructions": [
     {
-      "text": "Generate commit messages following the Conventional Commits specification with MANDATORY scope for monorepo. Use this structure:\n\n<type>(<scope>): <description>\n\nRules:\n1. **SCOPE IS MANDATORY** - Must be one of: frontend, backend, gateway, shared, all\n2. **Type must be one of**: feat, fix, docs, style, refactor, perf, test, build, ci, chore\n3. **Description**: Imperative mood, no period at end, max 72 characters\n4. **Examples**:\n   - feat(frontend): add dark mode toggle\n   - fix(backend): resolve database connection issue\n   - chore(gateway): update dependencies\n   - docs(all): update README installation guide\n   - refactor(shared): extract common utilities\n\nAlways include the scope to ensure proper changelog filtering per service. Use 'all' scope only for changes affecting multiple services or project-wide changes."
+      "text": "Generate commit messages following the Conventional Commits specification with MANDATORY scope for monorepo. Use this structure:\n\n<type>(<scope>): <description>\n\nRules:\n1. **SCOPE IS MANDATORY** - Must be one of: frontend, backend, satellite, shared, all, ci, deps\n2. **Type must be one of**: feat, fix, docs, style, refactor, perf, test, build, ci, chore\n3. **Description**: Imperative mood, no period at end, max 72 characters\n4. **Examples**:\n   - feat(frontend): add dark mode toggle\n   - fix(backend): resolve database connection issue\n   - feat(satellite): implement MCP server process management\n - chore(deps): update dependencies\n   - docs(all): update README installation guide\n   - refactor(shared): extract common utilities\n\nAlways include the scope to ensure proper changelog filtering per service. Use 'all' scope only for changes affecting multiple services or project-wide changes."
     }
   ],
   "github.copilot.chat.codeGeneration.useInstructionFiles": true

services/satellite/src/jobs/base-job.ts

@@ -0,0 +1,216 @@
+import { FastifyBaseLogger } from 'fastify';
+
+/**
+ * Base Job Interface
+ * 
+ * All recurring jobs must implement this interface to be managed by the JobManager.
+ */
+export interface Job {
+  /**
+   * Unique job name for logging and tracking
+   */
+  readonly name: string;
+
+  /**
+   * Job execution interval in milliseconds
+   */
+  readonly interval: number;
+
+  /**
+   * Start the job
+   */
+  start(): void;
+
+  /**
+   * Stop the job
+   */
+  stop(): void;
+
+  /**
+   * Check if job is currently running
+   */
+  isRunning(): boolean;
+
+  /**
+   * Get job execution statistics
+   */
+  getStats(): JobStats;
+}
+
+/**
+ * Job execution statistics
+ */
+export interface JobStats {
+  name: string;
+  isRunning: boolean;
+  executionCount: number;
+  lastExecution?: Date;
+  nextExecution?: Date;
+  averageExecutionTime?: number;
+  errorCount: number;
+}
+
+/**
+ * Abstract Base Job Class
+ * 
+ * Provides common functionality for interval-based jobs.
+ * Subclasses must implement the execute() method.
+ */
+export abstract class BaseJob implements Job {
+  public readonly name: string;
+  public readonly interval: number;
+  protected logger: FastifyBaseLogger;
+  protected intervalHandle?: NodeJS.Timeout;
+  protected running: boolean = false;
+  protected executionCount: number = 0;
+  protected errorCount: number = 0;
+  protected lastExecution?: Date;
+  protected executionTimes: number[] = [];
+
+  constructor(name: string, interval: number, logger: FastifyBaseLogger) {
+    this.name = name;
+    this.interval = interval;
+    this.logger = logger;
+  }
+
+  /**
+   * Start the job with immediate first execution
+   */
+  start(): void {
+    if (this.running) {
+      this.logger.warn({
+        operation: 'job_already_running',
+        job_name: this.name
+      }, `Job "${this.name}" is already running`);
+      return;
+    }
+
+    this.logger.info({
+      operation: 'job_start',
+      job_name: this.name,
+      interval_ms: this.interval,
+      interval_seconds: Math.round(this.interval / 1000)
+    }, `Starting job "${this.name}" (${Math.round(this.interval / 1000)}s interval)`);
+
+    this.running = true;
+
+    // Execute immediately on start
+    this.executeJob();
+
+    // Set up recurring execution
+    this.intervalHandle = setInterval(() => {
+      this.executeJob();
+    }, this.interval);
+  }
+
+  /**
+   * Stop the job
+   */
+  stop(): void {
+    if (!this.running) {
+      this.logger.warn({
+        operation: 'job_already_stopped',
+        job_name: this.name
+      }, `Job "${this.name}" is not running`);
+      return;
+    }
+
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = undefined;
+    }
+
+    this.running = false;
+
+    this.logger.info({
+      operation: 'job_stop',
+      job_name: this.name,
+      total_executions: this.executionCount,
+      total_errors: this.errorCount
+    }, `Stopped job "${this.name}" (${this.executionCount} executions, ${this.errorCount} errors)`);
+  }
+
+  /**
+   * Check if job is running
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Get job statistics
+   */
+  getStats(): JobStats {
+    const avgTime = this.executionTimes.length > 0
+      ? this.executionTimes.reduce((a, b) => a + b, 0) / this.executionTimes.length
+      : undefined;
+
+    const nextExecution = this.running && this.lastExecution
+      ? new Date(this.lastExecution.getTime() + this.interval)
+      : undefined;
+
+    return {
+      name: this.name,
+      isRunning: this.running,
+      executionCount: this.executionCount,
+      lastExecution: this.lastExecution,
+      nextExecution,
+      averageExecutionTime: avgTime,
+      errorCount: this.errorCount
+    };
+  }
+
+  /**
+   * Execute the job with error handling and metrics
+   */
+  private async executeJob(): Promise<void> {
+    const startTime = Date.now();
+
+    try {
+      this.executionCount++;
+      this.lastExecution = new Date();
+
+      this.logger.debug({
+        operation: 'job_execute_start',
+        job_name: this.name,
+        execution_number: this.executionCount
+      }, `Executing job "${this.name}" (#${this.executionCount})`);
+
+      await this.execute();
+
+      const executionTime = Date.now() - startTime;
+      
+      // Keep last 10 execution times for average calculation
+      this.executionTimes.push(executionTime);
+      if (this.executionTimes.length > 10) {
+        this.executionTimes.shift();
+      }
+
+      this.logger.debug({
+        operation: 'job_execute_success',
+        job_name: this.name,
+        execution_number: this.executionCount,
+        execution_time_ms: executionTime
+      }, `Job "${this.name}" completed in ${executionTime}ms`);
+
+    } catch (error) {
+      this.errorCount++;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const executionTime = Date.now() - startTime;
+
+      this.logger.error({
+        operation: 'job_execute_error',
+        job_name: this.name,
+        execution_number: this.executionCount,
+        error_count: this.errorCount,
+        execution_time_ms: executionTime,
+        error: errorMessage
+      }, `Job "${this.name}" failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Execute method to be implemented by subclasses
+   */
+  protected abstract execute(): Promise<void>;
+}

services/satellite/src/jobs/heartbeat-job.ts

@@ -0,0 +1,55 @@
+import { Job, JobStats } from './base-job';
+import { HeartbeatService } from '../services/heartbeat-service';
+
+/**
+ * Heartbeat Job
+ * 
+ * Wraps the existing HeartbeatService to integrate with the job management system.
+ * The HeartbeatService handles all heartbeat logic and reporting.
+ */
+export class HeartbeatJob implements Job {
+  public readonly name = 'heartbeat';
+  public readonly interval = 30000; // 30 seconds
+
+  constructor(private heartbeatService: HeartbeatService) {}
+
+  /**
+   * Start the heartbeat service
+   */
+  start(): void {
+    this.heartbeatService.start();
+  }
+
+  /**
+   * Stop the heartbeat service
+   */
+  stop(): void {
+    this.heartbeatService.stop();
+  }
+
+  /**
+   * Check if heartbeat service is running
+   */
+  isRunning(): boolean {
+    return this.heartbeatService.getStatus().isRunning;
+  }
+
+  /**
+   * Get heartbeat job statistics
+   */
+  getStats(): JobStats {
+    const status = this.heartbeatService.getStatus();
+    
+    return {
+      name: this.name,
+      isRunning: status.isRunning,
+      executionCount: status.heartbeatCount,
+      errorCount: 0, // HeartbeatService doesn't expose error count yet
+      lastExecution: undefined, // Could be tracked in HeartbeatService
+      nextExecution: status.isRunning 
+        ? new Date(Date.now() + this.interval)
+        : undefined,
+      averageExecutionTime: undefined // Could be tracked in HeartbeatService
+    };
+  }
+}