@iaforged/context-code 1.0.72 → 1.0.74

package/dist/src/services/lsp/LSPDiagnosticRegistry.js

@@ -0,0 +1,277 @@
+import { randomUUID } from 'crypto';
+import { LRUCache } from 'lru-cache';
+import { logForDebugging } from '../../utils/debug.js';
+import { toError } from '../../utils/errors.js';
+import { logError } from '../../utils/log.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+/**
+ * LSP Diagnostic Registry
+ *
+ * Stores LSP diagnostics received asynchronously from LSP servers via
+ * textDocument/publishDiagnostics notifications. Follows the same pattern
+ * as AsyncHookRegistry for consistent async attachment delivery.
+ *
+ * Pattern:
+ * 1. LSP server sends publishDiagnostics notification
+ * 2. registerPendingLSPDiagnostic() stores diagnostic
+ * 3. checkForLSPDiagnostics() retrieves pending diagnostics
+ * 4. getLSPDiagnosticAttachments() converts to Attachment[]
+ * 5. getAttachments() delivers to conversation automatically
+ *
+ * Similar to AsyncHookRegistry but simpler since diagnostics arrive
+ * synchronously (no need to accumulate output over time).
+ */
+// Volume limiting constants
+const MAX_DIAGNOSTICS_PER_FILE = 10;
+const MAX_TOTAL_DIAGNOSTICS = 30;
+// Max files to track for deduplication - prevents unbounded memory growth
+const MAX_DELIVERED_FILES = 500;
+// Global registry state
+const pendingDiagnostics = new Map();
+// Cross-turn deduplication: tracks diagnostics that have been delivered
+// Maps file URI to a set of diagnostic keys (hash of message+severity+range)
+// Using LRUCache to prevent unbounded growth in long sessions
+const deliveredDiagnostics = new LRUCache({
+    max: MAX_DELIVERED_FILES,
+});
+/**
+ * Register LSP diagnostics received from a server.
+ * These will be delivered as attachments in the next query.
+ *
+ * @param serverName - Name of LSP server that sent diagnostics
+ * @param files - Diagnostic files to deliver
+ */
+export function registerPendingLSPDiagnostic({ serverName, files, }) {
+    // Use UUID for guaranteed uniqueness (handles rapid registrations)
+    const diagnosticId = randomUUID();
+    logForDebugging(`LSP Diagnostics: Registering ${files.length} diagnostic file(s) from ${serverName} (ID: ${diagnosticId})`);
+    pendingDiagnostics.set(diagnosticId, {
+        serverName,
+        files,
+        timestamp: Date.now(),
+        attachmentSent: false,
+    });
+}
+/**
+ * Maps severity string to numeric value for sorting.
+ * Error=1, Warning=2, Info=3, Hint=4
+ */
+function severityToNumber(severity) {
+    switch (severity) {
+        case 'Error':
+            return 1;
+        case 'Warning':
+            return 2;
+        case 'Info':
+            return 3;
+        case 'Hint':
+            return 4;
+        default:
+            return 4;
+    }
+}
+/**
+ * Creates a unique key for a diagnostic based on its content.
+ * Used for both within-batch and cross-turn deduplication.
+ */
+function createDiagnosticKey(diag) {
+    return jsonStringify({
+        message: diag.message,
+        severity: diag.severity,
+        range: diag.range,
+        source: diag.source || null,
+        code: diag.code || null,
+    });
+}
+/**
+ * Deduplicates diagnostics by file URI and diagnostic content.
+ * Also filters out diagnostics that were already delivered in previous turns.
+ * Two diagnostics are considered duplicates if they have the same:
+ * - File URI
+ * - Range (start/end line and character)
+ * - Message
+ * - Severity
+ * - Source and code (if present)
+ */
+function deduplicateDiagnosticFiles(allFiles) {
+    // Group diagnostics by file URI
+    const fileMap = new Map();
+    const dedupedFiles = [];
+    for (const file of allFiles) {
+        if (!fileMap.has(file.uri)) {
+            fileMap.set(file.uri, new Set());
+            dedupedFiles.push({ uri: file.uri, diagnostics: [] });
+        }
+        const seenDiagnostics = fileMap.get(file.uri);
+        const dedupedFile = dedupedFiles.find(f => f.uri === file.uri);
+        // Get previously delivered diagnostics for this file (for cross-turn dedup)
+        const previouslyDelivered = deliveredDiagnostics.get(file.uri) || new Set();
+        for (const diag of file.diagnostics) {
+            try {
+                const key = createDiagnosticKey(diag);
+                // Skip if already seen in this batch OR already delivered in previous turns
+                if (seenDiagnostics.has(key) || previouslyDelivered.has(key)) {
+                    continue;
+                }
+                seenDiagnostics.add(key);
+                dedupedFile.diagnostics.push(diag);
+            }
+            catch (error) {
+                const err = toError(error);
+                const truncatedMessage = diag.message?.substring(0, 100) || '<no message>';
+                logError(new Error(`Failed to deduplicate diagnostic in ${file.uri}: ${err.message}. ` +
+                    `Diagnostic message: ${truncatedMessage}`));
+                // Include the diagnostic anyway to avoid losing information
+                dedupedFile.diagnostics.push(diag);
+            }
+        }
+    }
+    // Filter out files with no diagnostics after deduplication
+    return dedupedFiles.filter(f => f.diagnostics.length > 0);
+}
+/**
+ * Get all pending LSP diagnostics that haven't been delivered yet.
+ * Deduplicates diagnostics to prevent sending the same diagnostic multiple times.
+ * Marks diagnostics as sent to prevent duplicate delivery.
+ *
+ * @returns Array of pending diagnostics ready for delivery (deduplicated)
+ */
+export function checkForLSPDiagnostics() {
+    logForDebugging(`LSP Diagnostics: Checking registry - ${pendingDiagnostics.size} pending`);
+    // Collect all diagnostic files from all pending notifications
+    const allFiles = [];
+    const serverNames = new Set();
+    const diagnosticsToMark = [];
+    for (const diagnostic of pendingDiagnostics.values()) {
+        if (!diagnostic.attachmentSent) {
+            allFiles.push(...diagnostic.files);
+            serverNames.add(diagnostic.serverName);
+            diagnosticsToMark.push(diagnostic);
+        }
+    }
+    if (allFiles.length === 0) {
+        return [];
+    }
+    // Deduplicate diagnostics across all files
+    let dedupedFiles;
+    try {
+        dedupedFiles = deduplicateDiagnosticFiles(allFiles);
+    }
+    catch (error) {
+        const err = toError(error);
+        logError(new Error(`Failed to deduplicate LSP diagnostics: ${err.message}`));
+        // Fall back to undedup'd files to avoid losing diagnostics
+        dedupedFiles = allFiles;
+    }
+    // Only mark as sent AFTER successful deduplication, then delete from map.
+    // Entries are tracked in deliveredDiagnostics LRU for dedup, so we don't
+    // need to keep them in pendingDiagnostics after delivery.
+    for (const diagnostic of diagnosticsToMark) {
+        diagnostic.attachmentSent = true;
+    }
+    for (const [id, diagnostic] of pendingDiagnostics) {
+        if (diagnostic.attachmentSent) {
+            pendingDiagnostics.delete(id);
+        }
+    }
+    const originalCount = allFiles.reduce((sum, f) => sum + f.diagnostics.length, 0);
+    const dedupedCount = dedupedFiles.reduce((sum, f) => sum + f.diagnostics.length, 0);
+    if (originalCount > dedupedCount) {
+        logForDebugging(`LSP Diagnostics: Deduplication removed ${originalCount - dedupedCount} duplicate diagnostic(s)`);
+    }
+    // Apply volume limiting: cap per file and total
+    let totalDiagnostics = 0;
+    let truncatedCount = 0;
+    for (const file of dedupedFiles) {
+        // Sort by severity (Error=1 < Warning=2 < Info=3 < Hint=4) to prioritize errors
+        file.diagnostics.sort((a, b) => severityToNumber(a.severity) - severityToNumber(b.severity));
+        // Cap per file
+        if (file.diagnostics.length > MAX_DIAGNOSTICS_PER_FILE) {
+            truncatedCount += file.diagnostics.length - MAX_DIAGNOSTICS_PER_FILE;
+            file.diagnostics = file.diagnostics.slice(0, MAX_DIAGNOSTICS_PER_FILE);
+        }
+        // Cap total
+        const remainingCapacity = MAX_TOTAL_DIAGNOSTICS - totalDiagnostics;
+        if (file.diagnostics.length > remainingCapacity) {
+            truncatedCount += file.diagnostics.length - remainingCapacity;
+            file.diagnostics = file.diagnostics.slice(0, remainingCapacity);
+        }
+        totalDiagnostics += file.diagnostics.length;
+    }
+    // Filter out files that ended up with no diagnostics after limiting
+    dedupedFiles = dedupedFiles.filter(f => f.diagnostics.length > 0);
+    if (truncatedCount > 0) {
+        logForDebugging(`LSP Diagnostics: Volume limiting removed ${truncatedCount} diagnostic(s) (max ${MAX_DIAGNOSTICS_PER_FILE}/file, ${MAX_TOTAL_DIAGNOSTICS} total)`);
+    }
+    // Track delivered diagnostics for cross-turn deduplication
+    for (const file of dedupedFiles) {
+        if (!deliveredDiagnostics.has(file.uri)) {
+            deliveredDiagnostics.set(file.uri, new Set());
+        }
+        const delivered = deliveredDiagnostics.get(file.uri);
+        for (const diag of file.diagnostics) {
+            try {
+                delivered.add(createDiagnosticKey(diag));
+            }
+            catch (error) {
+                // Log but continue - failure to track shouldn't prevent delivery
+                const err = toError(error);
+                const truncatedMessage = diag.message?.substring(0, 100) || '<no message>';
+                logError(new Error(`Failed to track delivered diagnostic in ${file.uri}: ${err.message}. ` +
+                    `Diagnostic message: ${truncatedMessage}`));
+            }
+        }
+    }
+    const finalCount = dedupedFiles.reduce((sum, f) => sum + f.diagnostics.length, 0);
+    // Return empty if no diagnostics to deliver (all filtered by deduplication)
+    if (finalCount === 0) {
+        logForDebugging(`LSP Diagnostics: No new diagnostics to deliver (all filtered by deduplication)`);
+        return [];
+    }
+    logForDebugging(`LSP Diagnostics: Delivering ${dedupedFiles.length} file(s) with ${finalCount} diagnostic(s) from ${serverNames.size} server(s)`);
+    // Return single result with all deduplicated diagnostics
+    return [
+        {
+            serverName: Array.from(serverNames).join(', '),
+            files: dedupedFiles,
+        },
+    ];
+}
+/**
+ * Clear all pending diagnostics.
+ * Used during cleanup/shutdown or for testing.
+ * Note: Does NOT clear deliveredDiagnostics - that's for cross-turn deduplication
+ * and should only be cleared when files are edited or on session reset.
+ */
+export function clearAllLSPDiagnostics() {
+    logForDebugging(`LSP Diagnostics: Clearing ${pendingDiagnostics.size} pending diagnostic(s)`);
+    pendingDiagnostics.clear();
+}
+/**
+ * Reset all diagnostic state including cross-turn tracking.
+ * Used on session reset or for testing.
+ */
+export function resetAllLSPDiagnosticState() {
+    logForDebugging(`LSP Diagnostics: Resetting all state (${pendingDiagnostics.size} pending, ${deliveredDiagnostics.size} files tracked)`);
+    pendingDiagnostics.clear();
+    deliveredDiagnostics.clear();
+}
+/**
+ * Clear delivered diagnostics for a specific file.
+ * Should be called when a file is edited so that new diagnostics for that file
+ * will be shown even if they match previously delivered ones.
+ *
+ * @param fileUri - URI of the file that was edited
+ */
+export function clearDeliveredDiagnosticsForFile(fileUri) {
+    if (deliveredDiagnostics.has(fileUri)) {
+        logForDebugging(`LSP Diagnostics: Clearing delivered diagnostics for ${fileUri}`);
+        deliveredDiagnostics.delete(fileUri);
+    }
+}
+/**
+ * Get count of pending diagnostics (for monitoring)
+ */
+export function getPendingLSPDiagnosticCount() {
+    return pendingDiagnostics.size;
+}

package/dist/src/services/lsp/LSPServerInstance.js

@@ -0,0 +1,390 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+import { getCwd } from '../../utils/cwd.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { errorMessage } from '../../utils/errors.js';
+import { logError } from '../../utils/log.js';
+import { sleep } from '../../utils/sleep.js';
+/**
+ * LSP error code for "content modified" - indicates the server's state changed
+ * during request processing (e.g., rust-analyzer still indexing the project).
+ * This is a transient error that can be retried.
+ */
+const LSP_ERROR_CONTENT_MODIFIED = -32801;
+/**
+ * Maximum number of retries for transient LSP errors like "content modified".
+ */
+const MAX_RETRIES_FOR_TRANSIENT_ERRORS = 3;
+/**
+ * Base delay in milliseconds for exponential backoff on transient errors.
+ * Actual delays: 500ms, 1000ms, 2000ms
+ */
+const RETRY_BASE_DELAY_MS = 500;
+/**
+ * Creates and manages a single LSP server instance.
+ *
+ * Uses factory function pattern with closures for state encapsulation (avoiding classes).
+ * Provides state tracking, health monitoring, and request forwarding for an LSP server.
+ * Supports manual restart with configurable retry limits.
+ *
+ * State machine transitions:
+ * - stopped → starting → running
+ * - running → stopping → stopped
+ * - any → error (on failure)
+ * - error → starting (on retry)
+ *
+ * @param name - Unique identifier for this server instance
+ * @param config - Server configuration including command, args, and limits
+ * @returns LSP server instance with lifecycle management methods
+ *
+ * @example
+ * const instance = createLSPServerInstance('my-server', config)
+ * await instance.start()
+ * const result = await instance.sendRequest('textDocument/definition', params)
+ * await instance.stop()
+ */
+export function createLSPServerInstance(name, config) {
+    // Validate that unimplemented fields are not set
+    if (config.restartOnCrash !== undefined) {
+        throw new Error(`LSP server '${name}': restartOnCrash is not yet implemented. Remove this field from the configuration.`);
+    }
+    if (config.shutdownTimeout !== undefined) {
+        throw new Error(`LSP server '${name}': shutdownTimeout is not yet implemented. Remove this field from the configuration.`);
+    }
+    // Private state encapsulated via closures. Lazy-require LSPClient so
+    // vscode-jsonrpc (~129KB) only loads when an LSP server is actually
+    // instantiated, not when the static import chain reaches this module.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createLSPClient } = require('./LSPClient.js');
+    let state = 'stopped';
+    let startTime;
+    let lastError;
+    let restartCount = 0;
+    let crashRecoveryCount = 0;
+    // Propagate crash state so ensureServerStarted can restart on next use.
+    // Without this, state stays 'running' after crash and the server is never
+    // restarted (zombie state).
+    const client = createLSPClient(name, error => {
+        state = 'error';
+        lastError = error;
+        crashRecoveryCount++;
+    });
+    /**
+     * Starts the LSP server and initializes it with workspace information.
+     *
+     * If the server is already running or starting, this method returns immediately.
+     * On failure, sets state to 'error', logs for monitoring, and throws.
+     *
+     * @throws {Error} If server fails to start or initialize
+     */
+    async function start() {
+        if (state === 'running' || state === 'starting') {
+            return;
+        }
+        // Cap crash-recovery attempts so a persistently crashing server doesn't
+        // spawn unbounded child processes on every incoming request.
+        const maxRestarts = config.maxRestarts ?? 3;
+        if (state === 'error' && crashRecoveryCount > maxRestarts) {
+            const error = new Error(`LSP server '${name}' exceeded max crash recovery attempts (${maxRestarts})`);
+            lastError = error;
+            logError(error);
+            throw error;
+        }
+        let initPromise;
+        try {
+            state = 'starting';
+            logForDebugging(`Starting LSP server instance: ${name}`);
+            // Start the client
+            await client.start(config.command, config.args || [], {
+                env: config.env,
+                cwd: config.workspaceFolder,
+            });
+            // Initialize with workspace info
+            const workspaceFolder = config.workspaceFolder || getCwd();
+            const workspaceUri = pathToFileURL(workspaceFolder).href;
+            const initParams = {
+                processId: process.pid,
+                // Pass server-specific initialization options from plugin config
+                // Required by vue-language-server, optional for others
+                // Provide empty object as default to avoid undefined errors in servers
+                // that expect this field to exist
+                initializationOptions: config.initializationOptions ?? {},
+                // Modern approach (LSP 3.16+) - required for Pyright, gopls
+                workspaceFolders: [
+                    {
+                        uri: workspaceUri,
+                        name: path.basename(workspaceFolder),
+                    },
+                ],
+                // Deprecated fields - some servers still need these for proper URI resolution
+                rootPath: workspaceFolder, // Deprecated in LSP 3.8 but needed by some servers
+                rootUri: workspaceUri, // Deprecated in LSP 3.16 but needed by typescript-language-server for goToDefinition
+                // Client capabilities - declare what features we support
+                capabilities: {
+                    workspace: {
+                        // Don't claim to support workspace/configuration since we don't implement it
+                        // This prevents servers from requesting config we can't provide
+                        configuration: false,
+                        // Don't claim to support workspace folders changes since we don't handle
+                        // workspace/didChangeWorkspaceFolders notifications
+                        workspaceFolders: false,
+                    },
+                    textDocument: {
+                        synchronization: {
+                            dynamicRegistration: false,
+                            willSave: false,
+                            willSaveWaitUntil: false,
+                            didSave: true,
+                        },
+                        publishDiagnostics: {
+                            relatedInformation: true,
+                            tagSupport: {
+                                valueSet: [1, 2], // Unnecessary (1), Deprecated (2)
+                            },
+                            versionSupport: false,
+                            codeDescriptionSupport: true,
+                            dataSupport: false,
+                        },
+                        hover: {
+                            dynamicRegistration: false,
+                            contentFormat: ['markdown', 'plaintext'],
+                        },
+                        definition: {
+                            dynamicRegistration: false,
+                            linkSupport: true,
+                        },
+                        references: {
+                            dynamicRegistration: false,
+                        },
+                        documentSymbol: {
+                            dynamicRegistration: false,
+                            hierarchicalDocumentSymbolSupport: true,
+                        },
+                        callHierarchy: {
+                            dynamicRegistration: false,
+                        },
+                    },
+                    general: {
+                        positionEncodings: ['utf-16'],
+                    },
+                },
+            };
+            initPromise = client.initialize(initParams);
+            if (config.startupTimeout !== undefined) {
+                await withTimeout(initPromise, config.startupTimeout, `LSP server '${name}' timed out after ${config.startupTimeout}ms during initialization`);
+            }
+            else {
+                await initPromise;
+            }
+            state = 'running';
+            startTime = new Date();
+            crashRecoveryCount = 0;
+            logForDebugging(`LSP server instance started: ${name}`);
+        }
+        catch (error) {
+            // Clean up the spawned child process on timeout/error
+            client.stop().catch(() => { });
+            // Prevent unhandled rejection from abandoned initialize promise
+            initPromise?.catch(() => { });
+            state = 'error';
+            lastError = error;
+            logError(error);
+            throw error;
+        }
+    }
+    /**
+     * Stops the LSP server gracefully.
+     *
+     * If already stopped or stopping, returns immediately.
+     * On failure, sets state to 'error', logs for monitoring, and throws.
+     *
+     * @throws {Error} If server fails to stop
+     */
+    async function stop() {
+        if (state === 'stopped' || state === 'stopping') {
+            return;
+        }
+        try {
+            state = 'stopping';
+            await client.stop();
+            state = 'stopped';
+            logForDebugging(`LSP server instance stopped: ${name}`);
+        }
+        catch (error) {
+            state = 'error';
+            lastError = error;
+            logError(error);
+            throw error;
+        }
+    }
+    /**
+     * Manually restarts the server by stopping and starting it.
+     *
+     * Increments restartCount and enforces maxRestarts limit.
+     * Note: This is NOT automatic - must be called explicitly.
+     *
+     * @throws {Error} If stop or start fails, or if restartCount exceeds config.maxRestarts (default: 3)
+     */
+    async function restart() {
+        try {
+            await stop();
+        }
+        catch (error) {
+            const stopError = new Error(`Failed to stop LSP server '${name}' during restart: ${errorMessage(error)}`);
+            logError(stopError);
+            throw stopError;
+        }
+        restartCount++;
+        const maxRestarts = config.maxRestarts ?? 3;
+        if (restartCount > maxRestarts) {
+            const error = new Error(`Max restart attempts (${maxRestarts}) exceeded for server '${name}'`);
+            logError(error);
+            throw error;
+        }
+        try {
+            await start();
+        }
+        catch (error) {
+            const startError = new Error(`Failed to start LSP server '${name}' during restart (attempt ${restartCount}/${maxRestarts}): ${errorMessage(error)}`);
+            logError(startError);
+            throw startError;
+        }
+    }
+    /**
+     * Checks if the server is healthy and ready to handle requests.
+     *
+     * @returns true if state is 'running' AND the client has completed initialization
+     */
+    function isHealthy() {
+        return state === 'running' && client.isInitialized;
+    }
+    /**
+     * Sends an LSP request to the server with retry logic for transient errors.
+     *
+     * Checks server health before sending and wraps errors with context.
+     * Automatically retries on "content modified" errors (code -32801) which occur
+     * when servers like rust-analyzer are still indexing. This is expected LSP behavior
+     * and clients should retry silently per the LSP specification.
+     *
+     * @param method - LSP method name (e.g., 'textDocument/definition')
+     * @param params - Method-specific parameters
+     * @returns The server's response
+     * @throws {Error} If server is not healthy or request fails after all retries
+     */
+    async function sendRequest(method, params) {
+        if (!isHealthy()) {
+            const error = new Error(`Cannot send request to LSP server '${name}': server is ${state}` +
+                `${lastError ? `, last error: ${lastError.message}` : ''}`);
+            logError(error);
+            throw error;
+        }
+        let lastAttemptError;
+        for (let attempt = 0; attempt <= MAX_RETRIES_FOR_TRANSIENT_ERRORS; attempt++) {
+            try {
+                return await client.sendRequest(method, params);
+            }
+            catch (error) {
+                lastAttemptError = error;
+                // Check if this is a transient "content modified" error that we should retry
+                // This commonly happens with rust-analyzer during initial project indexing.
+                // We use duck typing instead of instanceof because there may be multiple
+                // versions of vscode-jsonrpc in the dependency tree (8.2.0 vs 8.2.1).
+                const errorCode = error.code;
+                const isContentModifiedError = typeof errorCode === 'number' &&
+                    errorCode === LSP_ERROR_CONTENT_MODIFIED;
+                if (isContentModifiedError &&
+                    attempt < MAX_RETRIES_FOR_TRANSIENT_ERRORS) {
+                    const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+                    logForDebugging(`LSP request '${method}' to '${name}' got ContentModified error, ` +
+                        `retrying in ${delay}ms (attempt ${attempt + 1}/${MAX_RETRIES_FOR_TRANSIENT_ERRORS})…`);
+                    await sleep(delay);
+                    continue;
+                }
+                // Non-retryable error or max retries exceeded
+                break;
+            }
+        }
+        // All retries failed or non-retryable error
+        const requestError = new Error(`LSP request '${method}' failed for server '${name}': ${lastAttemptError?.message ?? 'unknown error'}`);
+        logError(requestError);
+        throw requestError;
+    }
+    /**
+     * Send a notification to the LSP server (fire-and-forget).
+     * Used for file synchronization (didOpen, didChange, didClose).
+     */
+    async function sendNotification(method, params) {
+        if (!isHealthy()) {
+            const error = new Error(`Cannot send notification to LSP server '${name}': server is ${state}`);
+            logError(error);
+            throw error;
+        }
+        try {
+            await client.sendNotification(method, params);
+        }
+        catch (error) {
+            const notificationError = new Error(`LSP notification '${method}' failed for server '${name}': ${errorMessage(error)}`);
+            logError(notificationError);
+            throw notificationError;
+        }
+    }
+    /**
+     * Registers a handler for LSP notifications from the server.
+     *
+     * @param method - LSP notification method (e.g., 'window/logMessage')
+     * @param handler - Callback function to handle the notification
+     */
+    function onNotification(method, handler) {
+        client.onNotification(method, handler);
+    }
+    /**
+     * Registers a handler for LSP requests from the server.
+     *
+     * Some LSP servers send requests TO the client (reverse direction).
+     * This allows registering handlers for such requests.
+     *
+     * @param method - LSP request method (e.g., 'workspace/configuration')
+     * @param handler - Callback function to handle the request and return a response
+     */
+    function onRequest(method, handler) {
+        client.onRequest(method, handler);
+    }
+    // Return public API
+    return {
+        name,
+        config,
+        get state() {
+            return state;
+        },
+        get startTime() {
+            return startTime;
+        },
+        get lastError() {
+            return lastError;
+        },
+        get restartCount() {
+            return restartCount;
+        },
+        start,
+        stop,
+        restart,
+        isHealthy,
+        sendRequest,
+        sendNotification,
+        onNotification,
+        onRequest,
+    };
+}
+/**
+ * Race a promise against a timeout. Cleans up the timer regardless of outcome
+ * to avoid unhandled rejections from orphaned setTimeout callbacks.
+ */
+function withTimeout(promise, ms, message) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout((rej, msg) => rej(new Error(msg)), ms, reject, message);
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+}