specmem-hardwicksoftware 3.5.99

package/dist/mcp/reloadBroadcast.js

@@ -0,0 +1,275 @@
+/**
+ * reloadBroadcast.ts - Hot Reload Broadcast for Multi-Instance SpecMem
+ *
+ * Provides functionality to broadcast reload signals to ALL running SpecMem
+ * instances when code changes occur. Uses SIGUSR1 for graceful restart.
+ *
+ * Architecture:
+ * - Reads instance registry from instanceManager
+ * - Sends SIGUSR1 to each running instance (except self)
+ * - Emits coordination events for reload tracking
+ * - Handles failed signals gracefully (dead instances)
+ *
+ * @author hardwicksoftwareservices
+ * @task HR-7 - Hot Reload broadcast implementation
+ */
+import { listInstances, isProcessRunning } from '../utils/instanceManager.js';
+import { logger } from '../utils/logger.js';
+import { getLazyCoordinationServer, isCoordinationServerRunning } from '../coordination/server.js';
+import { RELOAD_EVENTS } from '../coordination/events.js';
+import { getProjectDirName } from '../config.js';
+// ============================================================================
+// Main Functions
+// ============================================================================
+/**
+ * Broadcast reload signal to all running SpecMem instances.
+ *
+ * This is the main entry point for hot reload. When called:
+ * 1. Gets all running instances from the registry
+ * 2. Sends SIGUSR1 to each instance (triggers graceful restart)
+ * 3. Emits coordination events for tracking
+ * 4. Returns detailed results
+ *
+ * @param reason - Human-readable reason for the reload (e.g., "Code changes detected")
+ * @param options - Optional configuration
+ * @returns Results of the broadcast operation
+ *
+ * @example
+ * // Broadcast reload due to code changes
+ * const result = await broadcastReload('TypeScript compilation completed');
+ * console.log(`Signaled ${result.signaled} instances`);
+ *
+ * @example
+ * // Broadcast with custom signal
+ * const result = await broadcastReload('Manual refresh', { signal: 'SIGUSR2' });
+ */
+export async function broadcastReload(reason, options = {}) {
+    const { signal = 'SIGUSR1', includeSelf = false, emitEvents = true, projectHashes, sameProjectOnly = true, // SAFETY: Default to same project only
+     } = options;
+    // Get current project identifier for filtering
+    const currentProjectDirName = getProjectDirName();
+    const timestamp = Date.now();
+    const result = {
+        signaled: 0,
+        failed: 0,
+        skipped: 0,
+        total: 0,
+        signaledPids: [],
+        failedPids: [],
+        errors: [],
+        timestamp,
+        reason,
+    };
+    logger.info({ reason, signal, includeSelf }, '[HotReload] Broadcasting reload to all instances');
+    // Emit reload requested event if coordination server is available
+    if (emitEvents) {
+        await emitReloadEvent(RELOAD_EVENTS.RELOAD_REQUESTED, {
+            reason,
+            timestamp,
+            signal,
+        });
+    }
+    // Get all running instances
+    let instances;
+    try {
+        instances = listInstances({ includeDockerStatus: false });
+        result.total = instances.length;
+    }
+    catch (error) {
+        const errorMsg = `Failed to list instances: ${error instanceof Error ? error.message : String(error)}`;
+        logger.error({ error }, '[HotReload] ' + errorMsg);
+        result.errors.push(errorMsg);
+        return result;
+    }
+    if (instances.length === 0) {
+        logger.info('[HotReload] No instances found in registry');
+        return result;
+    }
+    logger.info({ instanceCount: instances.length }, '[HotReload] Found instances in registry');
+    // SAFETY: Filter to same project only by default
+    if (sameProjectOnly && !projectHashes) {
+        instances = instances.filter(inst => inst.projectHash === currentProjectDirName);
+        logger.debug({ filtered: instances.length, currentProject: currentProjectDirName }, '[HotReload] Filtered to same project (SAFETY: sameProjectOnly=true)');
+    }
+    // Filter instances if project hashes specified
+    if (projectHashes && projectHashes.length > 0) {
+        instances = instances.filter(inst => projectHashes.includes(inst.projectHash));
+        logger.debug({ filtered: instances.length, projectHashes }, '[HotReload] Filtered to specific projects');
+    }
+    // Signal each instance
+    for (const instance of instances) {
+        const { pid, projectPath, projectHash } = instance;
+        // Skip self unless explicitly included
+        if (!includeSelf && pid === process.pid) {
+            logger.debug({ pid, projectPath }, '[HotReload] Skipping self');
+            result.skipped++;
+            continue;
+        }
+        // Check if process is still running
+        if (!isProcessRunning(pid)) {
+            logger.debug({ pid, projectPath }, '[HotReload] Instance process not running, skipping');
+            result.skipped++;
+            continue;
+        }
+        // Send signal
+        try {
+            process.kill(pid, signal);
+            result.signaled++;
+            result.signaledPids.push(pid);
+            logger.info({ pid, projectPath, projectHash, signal }, '[HotReload] Sent signal to instance');
+        }
+        catch (error) {
+            result.failed++;
+            result.failedPids.push(pid);
+            const errorMsg = `Failed to signal PID ${pid}: ${error instanceof Error ? error.message : String(error)}`;
+            result.errors.push(errorMsg);
+            logger.warn({ pid, projectPath, error }, '[HotReload] Failed to signal instance (may be dead)');
+        }
+    }
+    // Emit draining event
+    if (emitEvents && result.signaled > 0) {
+        await emitReloadEvent(RELOAD_EVENTS.RELOAD_DRAINING, {
+            instancesSignaled: result.signaled,
+            timestamp: Date.now(),
+        });
+    }
+    logger.info({
+        signaled: result.signaled,
+        failed: result.failed,
+        skipped: result.skipped,
+        total: result.total,
+        reason,
+    }, '[HotReload] Broadcast complete');
+    return result;
+}
+/**
+ * Broadcast reload to a specific instance by PID.
+ *
+ * @param pid - Process ID to signal
+ * @param reason - Reason for reload
+ * @param signal - Signal to send (default: SIGUSR1)
+ * @returns True if signal was sent successfully
+ */
+export function signalInstance(pid, reason, signal = 'SIGUSR1') {
+    logger.info({ pid, reason, signal }, '[HotReload] Signaling specific instance');
+    if (!isProcessRunning(pid)) {
+        logger.warn({ pid }, '[HotReload] Target process not running');
+        return false;
+    }
+    try {
+        process.kill(pid, signal);
+        logger.info({ pid, signal }, '[HotReload] Signal sent to instance');
+        return true;
+    }
+    catch (error) {
+        logger.error({ pid, error }, '[HotReload] Failed to signal instance');
+        return false;
+    }
+}
+/**
+ * Get the count of running SpecMem instances (excluding self).
+ * Useful for checking if broadcast is needed.
+ *
+ * @returns Number of other running instances
+ */
+export function getOtherInstanceCount() {
+    try {
+        const instances = listInstances({ includeDockerStatus: false });
+        return instances.filter(inst => inst.pid !== process.pid && isProcessRunning(inst.pid)).length;
+    }
+    catch (error) {
+        logger.warn({ error }, '[HotReload] Failed to count other instances');
+        return 0;
+    }
+}
+/**
+ * Check if there are other running instances to broadcast to.
+ *
+ * @returns True if there are other instances running
+ */
+export function hasOtherInstances() {
+    return getOtherInstanceCount() > 0;
+}
+// ============================================================================
+// Coordination Event Helpers
+// ============================================================================
+/**
+ * Emit a reload event via the coordination server (if available).
+ * This allows tracking reload progress across the cluster.
+ *
+ * @param eventType - Type of reload event
+ * @param data - Event data
+ */
+async function emitReloadEvent(eventType, data) {
+    try {
+        // Only emit if coordination server is running (don't start it just for this)
+        if (!isCoordinationServerRunning()) {
+            logger.debug({ eventType }, '[HotReload] Coordination server not running, skipping event emission');
+            return;
+        }
+        const server = await getLazyCoordinationServer();
+        if (!server) {
+            return;
+        }
+        const dispatcher = server.getDispatcher();
+        dispatcher.dispatchAsync({
+            type: eventType,
+            timestamp: Date.now(),
+            teamMemberId: 'hot-reload-manager',
+            ...data,
+        });
+        logger.debug({ eventType, data }, '[HotReload] Emitted coordination event');
+    }
+    catch (error) {
+        // Don't fail reload broadcast due to event emission issues
+        logger.warn({ eventType, error }, '[HotReload] Failed to emit coordination event');
+    }
+}
+/**
+ * Notify that a reload has completed on this instance.
+ * Called by the hot reload manager after successful reload.
+ *
+ * @param duration - How long the reload took in ms
+ * @param tier - Which tier of reload was performed
+ */
+export async function notifyReloadComplete(duration, tier) {
+    await emitReloadEvent(RELOAD_EVENTS.RELOAD_COMPLETE, {
+        pid: process.pid,
+        duration,
+        tier,
+        timestamp: Date.now(),
+    });
+    logger.info({ duration, tier }, '[HotReload] Reload complete notification sent');
+}
+/**
+ * Execute a reload broadcast from CLI context.
+ * Provides formatted output for terminal.
+ *
+ * @param reason - Reason for reload
+ * @returns Formatted result for CLI display
+ */
+export async function executeCLIReload(reason = 'Manual reload via CLI') {
+    const result = await broadcastReload(reason);
+    let message;
+    if (result.signaled === 0 && result.total === 0) {
+        message = 'No SpecMem instances found to reload.';
+    }
+    else if (result.signaled === 0) {
+        message = `No instances were signaled. ${result.skipped} skipped, ${result.failed} failed.`;
+    }
+    else {
+        message = `Reload signal sent to ${result.signaled}/${result.total} instances.`;
+        if (result.failed > 0) {
+            message += ` (${result.failed} failed)`;
+        }
+        if (result.skipped > 0) {
+            message += ` (${result.skipped} skipped)`;
+        }
+    }
+    return {
+        success: result.signaled > 0 || result.total === 0,
+        message,
+        details: result,
+    };
+}
+//# sourceMappingURL=reloadBroadcast.js.map

package/dist/mcp/reloadBroadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reloadBroadcast.js","sourceRoot":"","sources":["../../src/mcp/reloadBroadcast.ts"],"names":[],"mappings":"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"}

package/dist/mcp/resilientTransport.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Resilient Transport Layer for MCP Server
+ *
+ * Implements connection health monitoring, exponential backoff reconnection,
+ * and graceful handling for the stdio-based MCP transport. Since MCP servers
+ * run as child processes of  Code and communicate via stdin/stdout,
+ * actual transport reconnection is handled by  Code restarting the process.
+ * This module focuses on:
+ *
+ * 1. Detecting connection issues early (stdin EOF, pipe breaks, EPIPE errors)
+ * 2. Graceful shutdown when connection is irrecoverably lost
+ * 3. Announcing connection state changes to logs WITH TIMESTAMPS
+ * 4. Health monitoring for proactive issue detection
+ * 5. Recovery attempts with exponential backoff before giving up
+ * 6. Clear, actionable error messages explaining what went wrong
+ *
+ * IMPORTANT: The MCP protocol uses stdio - stdout is reserved for JSON-RPC
+ * messages, so all logging MUST go to stderr.
+ *
+ * Environment Variables (all configurable, no hardcoded timeouts):
+ * - SPECMEM_TRANSPORT_HEALTH_INTERVAL: Health check interval (default: 30000ms)
+ * - SPECMEM_TRANSPORT_INACTIVITY_THRESHOLD: Degraded state threshold (default: 300000ms)
+ * - SPECMEM_TRANSPORT_MAX_ERRORS: Max errors before shutdown (default: 10)
+ * - SPECMEM_TRANSPORT_DEBUG: Enable verbose debug logging (default: false)
+ * - SPECMEM_TRANSPORT_KEEPALIVE_INTERVAL: Keepalive ping interval (default: 60000ms)
+ * - SPECMEM_TRANSPORT_KEEPALIVE_ENABLED: Enable keepalive (default: true)
+ * - SPECMEM_TRANSPORT_RECOVERY_ENABLED: Enable recovery attempts (default: true)
+ * - SPECMEM_TRANSPORT_RECOVERY_MAX_ATTEMPTS: Max recovery attempts (default: 5)
+ * - SPECMEM_TRANSPORT_RECOVERY_BASE_DELAY: Base delay for backoff (default: 1000ms)
+ * - SPECMEM_TRANSPORT_RECOVERY_MAX_DELAY: Max delay cap (default: 30000ms)
+ * - SPECMEM_TRANSPORT_RECOVERY_MULTIPLIER: Backoff multiplier (default: 2)
+ * - SPECMEM_TRANSPORT_STDIN_GRACE_PERIOD: Grace period for stdin close (default: 5000ms)
+ * - SPECMEM_TRANSPORT_SHUTDOWN_GRACE_PERIOD: Grace period before shutdown (default: 100ms)
+ */
+import { EventEmitter } from 'events';
+export declare enum ConnectionState {
+    INITIALIZING = "initializing",
+    CONNECTED = "connected",
+    DEGRADED = "degraded",
+    RECOVERING = "recovering",// NEW: Attempting recovery with backoff
+    DISCONNECTING = "disconnecting",
+    DISCONNECTED = "disconnected"
+}
+export interface HealthCheckResult {
+    state: ConnectionState;
+    stdinOpen: boolean;
+    stdoutOpen: boolean;
+    lastActivityMs: number;
+    errorCount: number;
+    warningMessage: string | null;
+    timestamp: string;
+    recoveryAttempts: number;
+}
+export interface TransportError {
+    type: string;
+    message: string;
+    timestamp: string;
+    suggestion: string;
+    code?: string;
+    syscall?: string;
+}
+export interface ResilientTransportConfig {
+    healthCheckIntervalMs: number;
+    inactivityThresholdMs: number;
+    maxErrorsBeforeShutdown: number;
+    debugMode: boolean;
+    keepaliveIntervalMs: number;
+    keepaliveEnabled: boolean;
+    recoveryEnabled: boolean;
+    recoveryMaxAttempts: number;
+    recoveryBaseDelayMs: number;
+    recoveryMaxDelayMs: number;
+    recoveryMultiplier: number;
+    stdinGracePeriodMs: number;
+    shutdownGracePeriodMs: number;
+}
+/**
+ * ResilientTransport - monitors and manages MCP stdio transport health
+ *
+ * This wraps the standard StdioServerTransport with health monitoring,
+ * exponential backoff recovery, and graceful error handling. It emits
+ * events that the MCP server can listen to for handling connection state changes.
+ *
+ * Key features:
+ * - Exponential backoff reconnection attempts before giving up
+ * - Detailed error messages with actionable suggestions
+ * - Timestamp logging for all state changes
+ * - Configurable via environment variables (no hardcoded values)
+ * - Handles stdio edge cases (EPIPE, broken pipe, EAGAIN, etc.)
+ */
+export declare class ResilientTransport extends EventEmitter {
+    private config;
+    private state;
+    private lastActivityTime;
+    private monitoringStartTime;
+    private errorCount;
+    private healthCheckTimer;
+    private keepaliveTimer;
+    private recoveryTimer;
+    private stdinMonitor;
+    private stdoutMonitor;
+    private shutdownInProgress;
+    private keepaliveCallback;
+    private connectionRecoveryCallback;
+    private recoveryAttempts;
+    private lastRecoveryTime;
+    private recentErrors;
+    private readonly MAX_RECENT_ERRORS;
+    constructor(config?: Partial<ResilientTransportConfig>);
+    /**
+     * Get a human-readable suggestion for a specific error type
+     * Helps users understand what went wrong and how to fix it
+     */
+    private getErrorSuggestion;
+    /**
+     * Calculate the next backoff delay using exponential backoff with jitter
+     * Formula: min(maxDelay, baseDelay * multiplier^attempt) + random jitter
+     */
+    private calculateBackoffDelay;
+    /**
+     * Format a timestamp for logging
+     */
+    private formatTimestamp;
+    /**
+     * Start monitoring the stdio streams
+     * Should be called after MCP server.connect()
+     */
+    startMonitoring(): void;
+    /**
+     * Set the keepalive callback - this will be called periodically to keep connection alive
+     * The callback should send a log message or ping to 
+     */
+    setKeepaliveCallback(callback: () => Promise<void>): void;
+    /**
+     * Set the connection recovery callback - called when connection is restored from degraded
+     * The callback should re-send tool list notifications to 
+     */
+    setConnectionRecoveryCallback(callback: () => Promise<void>): void;
+    /**
+     * Start the keepalive timer
+     * Sends periodic keepalive pings to prevent idle disconnection
+     */
+    private startKeepalive;
+    /**
+     * Send a keepalive ping
+     * Records activity and optionally calls the keepalive callback
+     */
+    private sendKeepalive;
+    /**
+     * Setup stdin monitoring for connection issues
+     * Handles edge cases: EOF, close, EPIPE, EAGAIN, etc.
+     */
+    private setupStdinMonitoring;
+    /**
+     * Setup stdout monitoring for write issues
+     * Handles edge cases: EPIPE (broken pipe), EAGAIN, write errors
+     */
+    private setupStdoutMonitoring;
+    /**
+     * Start periodic health checks
+     */
+    private startHealthChecks;
+    /**
+     * Perform a health check and emit status
+     */
+    private performHealthCheck;
+    /**
+     * Trigger connection recovery - re-sends tool list notifications
+     */
+    private triggerConnectionRecovery;
+    /**
+     * Record that activity occurred (message sent/received)
+     */
+    recordActivity(): void;
+    /**
+     * Record an error for tracking
+     */
+    recordError(type: string, message: string): void;
+    /**
+     * Handle a connection issue with exponential backoff recovery
+     * This is the main entry point for connection problems
+     *
+     * Flow:
+     * 1. If recovery is disabled or exhausted, go to handleConnectionLoss
+     * 2. Otherwise, enter RECOVERING state and schedule a recovery attempt
+     * 3. On each attempt, check if connection is restored
+     * 4. If all attempts fail, escalate to handleConnectionLoss
+     */
+    private handleConnectionIssue;
+    /**
+     * Attempt to recover the connection after backoff delay
+     */
+    private attemptRecovery;
+    /**
+     * Handle detected connection loss - final shutdown path
+     * This is called when recovery is disabled or all recovery attempts have failed
+     */
+    private handleConnectionLoss;
+    /**
+     * Get current connection health
+     */
+    getHealth(): HealthCheckResult;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if connection is healthy
+     */
+    isHealthy(): boolean;
+    /**
+     * Check if connection is usable (connected or degraded)
+     */
+    isUsable(): boolean;
+    /**
+     * Shutdown monitoring and cleanup
+     */
+    shutdown(): void;
+    /**
+     * Reset error count (e.g., after successful recovery)
+     */
+    resetErrors(): void;
+    /**
+     * Get recent errors for debugging
+     */
+    getRecentErrors(): TransportError[];
+    /**
+     * Check if currently in recovery state
+     */
+    isRecovering(): boolean;
+    /**
+     * Get current recovery status
+     */
+    getRecoveryStatus(): {
+        isRecovering: boolean;
+        attempts: number;
+        maxAttempts: number;
+        lastRecoveryTime: number;
+    };
+}
+/**
+ * Get or create the resilient transport singleton
+ */
+export declare function getResilientTransport(config?: Partial<ResilientTransportConfig>): ResilientTransport;
+/**
+ * Reset the resilient transport (for testing or restart)
+ */
+export declare function resetResilientTransport(): void;
+//# sourceMappingURL=resilientTransport.d.ts.map

package/dist/mcp/resilientTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilientTransport.d.ts","sourceRoot":"","sources":["../../src/mcp/resilientTransport.ts"],"names":[],"mappings":"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"}