byterover-cli 1.0.5 → 1.2.0

package/dist/infra/transport/socket-io-transport-client.js

@@ -1,6 +1,33 @@
 import { io } from 'socket.io-client';
 import { TRANSPORT_CONNECT_TIMEOUT_MS, TRANSPORT_DEFAULT_TRANSPORTS, TRANSPORT_RECONNECTION_ATTEMPTS, TRANSPORT_RECONNECTION_DELAY_MAX_MS, TRANSPORT_RECONNECTION_DELAY_MS, TRANSPORT_REQUEST_TIMEOUT_MS, TRANSPORT_ROOM_TIMEOUT_MS, } from '../../constants.js';
 import { TransportConnectionError, TransportNotConnectedError, TransportRequestError, TransportRequestTimeoutError, TransportRoomError, TransportRoomTimeoutError, } from '../../core/domain/errors/transport-error.js';
+import { processLog } from '../../utils/process-logger.js';
+/**
+ * Log transport client events for debugging reconnection issues.
+ */
+function clientLog(message) {
+    processLog(`[TransportClient] ${message}`);
+}
+/**
+ * Force reconnect delays after Socket.IO gives up (exponential backoff).
+ * Used when all built-in reconnection attempts fail.
+ */
+const FORCE_RECONNECT_DELAYS = [5000, 10_000, 20_000, 30_000, 60_000]; // 5s, 10s, 20s, 30s, 60s cap
+/**
+ * Maximum number of force reconnect attempts before giving up.
+ * After this, ProcessManager's periodic health check will detect the failure and restart.
+ */
+const MAX_FORCE_RECONNECT_ATTEMPTS = 10;
+/**
+ * Interval for checking time jumps that indicate system wake from sleep.
+ * Uses a short interval so we detect wake quickly.
+ */
+const WAKE_DETECTION_INTERVAL_MS = 5000;
+/**
+ * Time jump threshold to detect wake from sleep/hibernate.
+ * If the actual elapsed time exceeds expected by this amount, system likely woke from sleep.
+ */
+const WAKE_TIME_JUMP_THRESHOLD_MS = 10_000;
 /**
  * Socket.IO implementation of ITransportClient.
  *
@@ -8,15 +35,29 @@ import { TransportConnectionError, TransportNotConnectedError, TransportRequestE
  * - Auto-reconnects with exponential backoff
  * - Request/response uses Socket.IO acknowledgements (callbacks)
  * - Connection state is tracked and exposed via onStateChange
+ * - Force reconnect after all built-in attempts fail (sleep/wake recovery)
+ * - Auto-rejoins rooms after reconnect
  */
 export class SocketIOTransportClient {
     config;
     eventHandlers = new Map();
+    /** Track force reconnect attempt count for backoff calculation */
+    forceReconnectAttempt = 0;
+    /** Timer for scheduled force reconnect */
+    forceReconnectTimer;
+    /** Track joined rooms for auto-rejoin after reconnect */
+    joinedRooms = new Set();
+    /** Last time we checked for wake (for detecting time jumps) */
+    lastWakeCheckTime = Date.now();
     /** Track which events have socket listeners registered (prevents duplicates on reconnect) */
     registeredSocketEvents = new Set();
+    /** Store server URL for force reconnect */
+    serverUrl;
     socket;
     state = 'disconnected';
     stateHandlers = new Set();
+    /** Timer for wake detection */
+    wakeDetectionTimer;
     constructor(config) {
         this.config = {
             connectTimeoutMs: config?.connectTimeoutMs ?? TRANSPORT_CONNECT_TIMEOUT_MS,
@@ -32,6 +73,20 @@ export class SocketIOTransportClient {
         if (this.socket?.connected) {
             return;
         }
+        // Cleanup existing socket if present but not connected
+        // This prevents resource leaks when connect() is called again after a failed connection
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.io.removeAllListeners();
+            this.socket.disconnect();
+            this.socket = undefined;
+            this.registeredSocketEvents.clear();
+        }
+        // Store URL for force reconnect
+        this.serverUrl = url;
+        // Clear any pending force reconnect timer (we're connecting now)
+        // Do NOT reset counter - connection may still fail, need to preserve backoff
+        this.clearForceReconnectTimer();
         return new Promise((resolve, reject) => {
             this.setState('connecting');
             this.socket = io(url, {
@@ -51,6 +106,8 @@ export class SocketIOTransportClient {
                 // This fixes the issue where on() called before connect() would not
                 // actually register handlers on the socket.
                 this.registerPendingEventHandlers();
+                // Start wake detection to handle sleep/hibernate recovery
+                this.startWakeDetection();
                 resolve();
             };
             const onConnectError = (error) => {
@@ -74,7 +131,8 @@ export class SocketIOTransportClient {
             this.socket.on('connect', onConnect);
             this.socket.once('connect_error', onConnectError);
             // Set up persistent event handlers
-            this.socket.on('disconnect', () => {
+            this.socket.on('disconnect', (reason) => {
+                clientLog(`Socket disconnected, reason: ${reason}, active: ${this.socket?.active}`);
                 if (this.socket?.active) {
                     // Socket.IO is attempting to reconnect
                     this.setState('reconnecting');
@@ -83,19 +141,31 @@ export class SocketIOTransportClient {
                     this.setState('disconnected');
                 }
             });
-            this.socket.io.on('reconnect', () => {
+            this.socket.io.on('reconnect', (attemptNumber) => {
+                clientLog(`Socket.IO built-in reconnect succeeded after ${attemptNumber} attempts`);
                 this.setState('connected');
                 // Re-register event handlers after reconnect
                 // Clear tracking first since socket listeners were reset during reconnect
                 this.registeredSocketEvents.clear();
                 this.registerPendingEventHandlers();
+                // Auto-rejoin rooms after reconnect
+                // Use process.nextTick to ensure socket.connected is true
+                // (reconnect event fires before socket.connected is updated)
+                process.nextTick(() => this.rejoinRooms());
             });
             this.socket.io.on('reconnect_failed', () => {
+                clientLog('Socket.IO built-in reconnection failed after all attempts, starting force reconnect');
                 this.setState('disconnected');
+                // Start force reconnect loop after Socket.IO gives up
+                this.scheduleForceReconnect();
             });
         });
     }
     async disconnect() {
+        // Cancel any pending force reconnect
+        this.cancelForceReconnect();
+        // Stop wake detection
+        this.stopWakeDetection();
         const { socket } = this;
         if (!socket) {
             return;
@@ -107,10 +177,12 @@ export class SocketIOTransportClient {
             socket.disconnect();
             this.socket = undefined;
             this.setState('disconnected');
-            // Clear all tracking state to prevent leaks
+            // Clear socket-specific tracking state to prevent leaks
+            // Note: stateHandlers are NOT cleared - subscriptions persist across disconnect/connect cycles
+            // Users can unsubscribe via the returned function from onStateChange()
             this.eventHandlers.clear();
             this.registeredSocketEvents.clear();
-            this.stateHandlers.clear();
+            this.joinedRooms.clear();
             resolve();
         });
     }
@@ -120,18 +192,52 @@ export class SocketIOTransportClient {
     getState() {
         return this.state;
     }
+    /**
+     * Checks if the socket is actually connected and responsive.
+     * Uses Socket.IO's built-in volatile emit with acknowledgement to verify bidirectional communication.
+     * @param timeoutMs - Timeout in milliseconds (default: 2000)
+     * @returns true if socket is connected and responsive, false otherwise
+     */
+    async isConnected(timeoutMs = 2000) {
+        const { socket } = this;
+        // Quick check: if socket doesn't exist or isn't marked as connected, return false immediately
+        if (!socket?.connected) {
+            return false;
+        }
+        // Verify actual bidirectional communication with a ping
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                resolve(false);
+            }, timeoutMs);
+            // Use Socket.IO's built-in ping mechanism via volatile emit
+            // Volatile means if the message can't be sent, it won't be buffered
+            socket.volatile.emit('ping', { timestamp: Date.now() }, () => {
+                clearTimeout(timeout);
+                resolve(true);
+            });
+        });
+    }
     async joinRoom(room) {
         const { socket } = this;
         if (!socket?.connected) {
             throw new TransportNotConnectedError('joinRoom');
         }
         return new Promise((resolve, reject) => {
+            // Flag to prevent callback from executing after timeout
+            let resolved = false;
             const timer = setTimeout(() => {
+                resolved = true;
                 reject(new TransportRoomTimeoutError(room, 'join', this.config.roomTimeoutMs));
             }, this.config.roomTimeoutMs);
             socket.emit('room:join', room, (response) => {
+                // Don't process if timeout already fired
+                if (resolved)
+                    return;
+                resolved = true;
                 clearTimeout(timer);
                 if (response.success) {
+                    // Track joined room for auto-rejoin after reconnect
+                    this.joinedRooms.add(room);
                     resolve();
                 }
                 else {
@@ -146,12 +252,21 @@ export class SocketIOTransportClient {
             throw new TransportNotConnectedError('leaveRoom');
         }
         return new Promise((resolve, reject) => {
+            // Flag to prevent callback from executing after timeout
+            let resolved = false;
             const timer = setTimeout(() => {
+                resolved = true;
                 reject(new TransportRoomTimeoutError(room, 'leave', this.config.roomTimeoutMs));
             }, this.config.roomTimeoutMs);
             socket.emit('room:leave', room, (response) => {
+                // Don't process if timeout already fired
+                if (resolved)
+                    return;
+                resolved = true;
                 clearTimeout(timer);
                 if (response.success) {
+                    // Remove from tracked rooms
+                    this.joinedRooms.delete(room);
                     resolve();
                 }
                 else {
@@ -167,7 +282,9 @@ export class SocketIOTransportClient {
         // Register socket listener if connected and not already registered
         // Use registeredSocketEvents to prevent duplicates across reconnects
         this.registerSocketEventIfNeeded(event);
-        // Wrap handler to store without type assertion
+        // Wrap handler to match StoredEventHandler signature.
+        // BOUNDARY CAST: Socket.IO delivers unknown data; caller specifies T via generic.
+        // Type guard not possible for generic T at runtime.
         const wrappedHandler = (data) => handler(data);
         const handlers = this.eventHandlers.get(event);
         handlers?.add(wrappedHandler);
@@ -188,6 +305,14 @@ export class SocketIOTransportClient {
         }
         socket.once(event, handler);
     }
+    /**
+     * Subscribe to connection state changes.
+     *
+     * Important: Subscriptions persist across disconnect/connect cycles. Call the returned
+     * function to unsubscribe when no longer needed to prevent memory leaks.
+     *
+     * @returns Unsubscribe function - call to remove the handler
+     */
     onStateChange(handler) {
         this.stateHandlers.add(handler);
         return () => {
@@ -210,8 +335,9 @@ export class SocketIOTransportClient {
                     resolve(response.data);
                 }
                 else if (response.success) {
-                    // Response success but data is undefined - resolve with undefined cast
-                    // This is a boundary case where server returns void
+                    // BOUNDARY CAST: Server returned success without data (void response).
+                    // Caller must specify TResponse=void for void endpoints.
+                    // Type guard not applicable - void vs non-void is a type-level distinction.
                     resolve(undefined);
                 }
                 else {
@@ -220,6 +346,88 @@ export class SocketIOTransportClient {
             });
         });
     }
+    /**
+     * Attempt force reconnect after Socket.IO gives up.
+     * Creates a new socket and connects.
+     * Gives up after MAX_FORCE_RECONNECT_ATTEMPTS (ProcessManager will detect via periodic health check).
+     */
+    async attemptForceReconnect() {
+        if (!this.serverUrl || this.state === 'connected') {
+            return;
+        }
+        // Check max attempts - give up if exceeded
+        // ProcessManager's periodic health check (30s) will detect and restart
+        if (this.forceReconnectAttempt >= MAX_FORCE_RECONNECT_ATTEMPTS) {
+            clientLog(`Force reconnect gave up after ${MAX_FORCE_RECONNECT_ATTEMPTS} attempts`);
+            this.setState('disconnected');
+            return;
+        }
+        clientLog(`Force reconnect attempt ${this.forceReconnectAttempt + 1}/${MAX_FORCE_RECONNECT_ATTEMPTS}`);
+        try {
+            // Cleanup old socket completely
+            if (this.socket) {
+                this.socket.removeAllListeners();
+                this.socket.io.removeAllListeners();
+                this.socket.disconnect();
+                this.socket = undefined;
+            }
+            // Reset tracking (will be re-populated on connect)
+            this.registeredSocketEvents.clear();
+            // Attempt to connect
+            await this.connect(this.serverUrl);
+            // Rejoin rooms after force reconnect (same as built-in reconnect)
+            // Without this, TUI REPL won't receive events from broadcast-room
+            // Use process.nextTick for consistency with built-in reconnect handler
+            clientLog(`Force reconnect succeeded, rejoining ${this.joinedRooms.size} rooms`);
+            process.nextTick(() => this.rejoinRooms());
+            // Success - reset attempt counter
+            this.forceReconnectAttempt = 0;
+        }
+        catch (error) {
+            // Failed - schedule next attempt
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            clientLog(`Force reconnect failed: ${errorMsg}`);
+            this.scheduleForceReconnect();
+        }
+    }
+    /**
+     * Cancel force reconnect completely (clears timer AND resets counter).
+     * Used when connection is stable or on disconnect().
+     */
+    cancelForceReconnect() {
+        this.clearForceReconnectTimer();
+        this.forceReconnectAttempt = 0;
+    }
+    /**
+     * Clear force reconnect timer only (does NOT reset counter).
+     * Used when initiating new connection attempt - counter preserved for backoff continuity.
+     */
+    clearForceReconnectTimer() {
+        if (this.forceReconnectTimer) {
+            clearTimeout(this.forceReconnectTimer);
+            this.forceReconnectTimer = undefined;
+        }
+    }
+    /**
+     * Handle system wake from sleep/hibernate.
+     * Re-triggers reconnection if not connected and force reconnect has given up.
+     */
+    handleWakeFromSleep() {
+        // Only take action if disconnected (force reconnect may have given up before sleep)
+        if (this.state === 'disconnected' && this.serverUrl) {
+            clientLog('handleWakeFromSleep: state is disconnected, restarting force reconnect');
+            // Reset attempt counter to get fresh tries after wake
+            this.forceReconnectAttempt = 0;
+            this.scheduleForceReconnect();
+        }
+        else if (this.state === 'connected' && this.socket && !this.socket.connected) {
+            // State says connected but socket isn't - stale state after wake
+            clientLog('handleWakeFromSleep: state mismatch (connected but socket disconnected), triggering reconnect');
+            this.setState('disconnected');
+            this.forceReconnectAttempt = 0;
+            this.scheduleForceReconnect();
+        }
+    }
     /**
      * Register all pending event handlers on the socket.
      * Called after successful connection to handle handlers added before connect().
@@ -249,6 +457,52 @@ export class SocketIOTransportClient {
         });
         this.registeredSocketEvents.add(event);
     }
+    /**
+     * Re-join all tracked rooms after reconnect.
+     * Retries failed room joins with exponential backoff.
+     */
+    rejoinRooms() {
+        clientLog(`rejoinRooms: rejoining ${this.joinedRooms.size} rooms: [${[...this.joinedRooms].join(', ')}]`);
+        for (const room of this.joinedRooms) {
+            this.rejoinRoomWithRetry(room, 0);
+        }
+    }
+    /**
+     * Rejoin a single room with retry logic.
+     * Uses exponential backoff: 50ms, 100ms, 200ms, 400ms, 800ms (max 5 attempts).
+     * Retries BOTH when socket not connected AND when room:join fails.
+     */
+    rejoinRoomWithRetry(room, attempt) {
+        const MAX_REJOIN_ATTEMPTS = 5;
+        const REJOIN_BASE_DELAY_MS = 50;
+        if (attempt >= MAX_REJOIN_ATTEMPTS) {
+            clientLog(`rejoinRoomWithRetry: gave up rejoining '${room}' after ${MAX_REJOIN_ATTEMPTS} attempts`);
+            return;
+        }
+        // If socket not connected yet, retry with backoff (don't silent return!)
+        // This handles race condition where reconnect event fires before socket.connected is true
+        if (!this.socket?.connected) {
+            const delay = REJOIN_BASE_DELAY_MS * 2 ** attempt;
+            clientLog(`rejoinRoomWithRetry: socket not connected, retrying '${room}' in ${delay}ms (attempt ${attempt + 1}/${MAX_REJOIN_ATTEMPTS})`);
+            setTimeout(() => this.rejoinRoomWithRetry(room, attempt + 1), delay);
+            return;
+        }
+        clientLog(`rejoinRoomWithRetry: attempting to rejoin '${room}' (attempt ${attempt + 1}/${MAX_REJOIN_ATTEMPTS})`);
+        this.socket.emit('room:join', room, (response) => {
+            if (response?.success) {
+                clientLog(`rejoinRoomWithRetry: successfully rejoined '${room}'`);
+            }
+            else if (attempt < MAX_REJOIN_ATTEMPTS - 1) {
+                // Retry with exponential backoff
+                const delay = REJOIN_BASE_DELAY_MS * 2 ** attempt;
+                clientLog(`rejoinRoomWithRetry: room:join failed for '${room}', retrying in ${delay}ms`);
+                setTimeout(() => this.rejoinRoomWithRetry(room, attempt + 1), delay);
+            }
+            else {
+                clientLog(`rejoinRoomWithRetry: failed to rejoin '${room}' on final attempt`);
+            }
+        });
+    }
     /**
      * Remove socket listener for an event and clear tracking.
      */
@@ -259,12 +513,59 @@ export class SocketIOTransportClient {
             this.registeredSocketEvents.delete(event);
         }
     }
+    /**
+     * Schedule force reconnect with exponential backoff.
+     * Called after Socket.IO's built-in reconnection gives up.
+     */
+    scheduleForceReconnect() {
+        if (!this.serverUrl) {
+            clientLog('scheduleForceReconnect: no serverUrl, skipping');
+            return;
+        }
+        // Clear existing timer to prevent duplicate timers (fixes concurrent reconnect race)
+        // This can happen when both 'connect_error' and 'reconnect_failed' schedule timers
+        this.clearForceReconnectTimer();
+        const delay = FORCE_RECONNECT_DELAYS[Math.min(this.forceReconnectAttempt, FORCE_RECONNECT_DELAYS.length - 1)];
+        clientLog(`scheduleForceReconnect: scheduling attempt ${this.forceReconnectAttempt + 1} in ${delay}ms`);
+        this.forceReconnectTimer = setTimeout(() => {
+            this.forceReconnectAttempt++;
+            this.attemptForceReconnect();
+        }, delay);
+    }
     setState(state) {
         if (this.state !== state) {
+            clientLog(`State change: ${this.state} -> ${state}`);
             this.state = state;
             for (const handler of this.stateHandlers) {
                 handler(state);
             }
         }
     }
+    /**
+     * Start wake detection timer.
+     * Periodically checks for time jumps that indicate system woke from sleep.
+     */
+    startWakeDetection() {
+        this.stopWakeDetection();
+        this.lastWakeCheckTime = Date.now();
+        this.wakeDetectionTimer = setInterval(() => {
+            const now = Date.now();
+            const elapsed = now - this.lastWakeCheckTime;
+            this.lastWakeCheckTime = now;
+            // If elapsed time is much greater than interval, system likely woke from sleep
+            if (elapsed > WAKE_DETECTION_INTERVAL_MS + WAKE_TIME_JUMP_THRESHOLD_MS) {
+                clientLog(`Wake detected: time jump of ${elapsed}ms (expected ~${WAKE_DETECTION_INTERVAL_MS}ms)`);
+                this.handleWakeFromSleep();
+            }
+        }, WAKE_DETECTION_INTERVAL_MS);
+    }
+    /**
+     * Stop wake detection timer.
+     */
+    stopWakeDetection() {
+        if (this.wakeDetectionTimer) {
+            clearInterval(this.wakeDetectionTimer);
+            this.wakeDetectionTimer = undefined;
+        }
+    }
 }

package/dist/infra/transport/socket-io-transport-server.js

@@ -145,6 +145,10 @@ export class SocketIOTransportServer {
                     socket.leave(room);
                     callback?.({ success: true });
                 });
+                // Handle ping requests for health checks
+                socket.on('ping', (_data, callback) => {
+                    callback?.({ pong: true, timestamp: Date.now() });
+                });
             });
             this.httpServer.on('error', (err) => {
                 if (err.code === 'EADDRINUSE') {

package/dist/infra/usecase/connectors-use-case.d.ts

@@ -0,0 +1,63 @@
+import type { IConnectorManager } from '../../core/interfaces/connectors/i-connector-manager.js';
+import type { ITerminal } from '../../core/interfaces/i-terminal.js';
+import type { ITrackingService } from '../../core/interfaces/i-tracking-service.js';
+import { IConnectorsUseCase } from '../../core/interfaces/usecase/i-connectors-use-case.js';
+/**
+ * Options for constructing ConnectorsUseCase.
+ */
+export interface ConnectorsUseCaseOptions {
+    connectorManager: IConnectorManager;
+    terminal: ITerminal;
+    trackingService: ITrackingService;
+}
+/**
+ * Use case for managing connectors.
+ * Shows list of connected agents and allows managing or adding new connections.
+ */
+export declare class ConnectorsUseCase implements IConnectorsUseCase {
+    private readonly connectorManager;
+    private readonly terminal;
+    private readonly trackingService;
+    constructor(options: ConnectorsUseCaseOptions);
+    run(): Promise<void>;
+    /**
+     * Display manual setup instructions for MCP configuration.
+     */
+    private displayManualInstructions;
+    /**
+     * Gets a description for a connector type.
+     */
+    private getConnectorDescription;
+    /**
+     * Gets a human-readable label for a connector type.
+     */
+    private getConnectorLabel;
+    /**
+     * Handles the case when connectors are already installed.
+     */
+    private handleExistingConnectors;
+    /**
+     * Handles the case when no connectors are installed.
+     */
+    private handleNoConnectorsInstalled;
+    /**
+     * Installs the selected connector and displays result.
+     */
+    private installConnector;
+    /**
+     * Prompts user to select from connected agents or add new.
+     */
+    private promptForAgentToManage;
+    /**
+     * Prompts the user to select a connector type.
+     */
+    private promptForConnectorType;
+    /**
+     * Prompts user to select a new agent (excludes already connected agents).
+     */
+    private promptForNewAgentSelection;
+    /**
+     * Prompts the user to confirm switching connectors.
+     */
+    private promptForSwitchConfirmation;
+}