@sns-myagent/cli 0.2.0

package/src/lsp/client.ts

@@ -0,0 +1,1135 @@
+import * as path from "node:path";
+import { isEnoent, logger, ptree, untilAborted } from "@oh-my-pi/pi-utils";
+import { MessageFramer } from "../jsonrpc/message-framing";
+import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
+import { applyWorkspaceEdit } from "./edits";
+import { getLspmuxCommand, isLspmuxSupported } from "./lspmux";
+import type {
+	LspClient,
+	LspJsonRpcId,
+	LspJsonRpcNotification,
+	LspJsonRpcRequest,
+	LspJsonRpcResponse,
+	PublishDiagnosticsParams,
+	ServerConfig,
+	WorkspaceEdit,
+} from "./types";
+import { detectLanguageId, fileToUri } from "./utils";
+
+// =============================================================================
+// Client State
+// =============================================================================
+
+const clients = new Map<string, LspClient>();
+const clientLocks = new Map<string, Promise<LspClient>>();
+const fileOperationLocks = new Map<string, Promise<void>>();
+
+/** Negative cache of recent init failures so a broken server fails fast instead of re-spawning per call. */
+const INIT_FAILURE_BACKOFF_MS = 3 * 60 * 1000;
+const initFailures = new Map<string, { at: number; message: string }>();
+
+// Idle timeout configuration (disabled by default)
+let idleTimeoutMs: number | null = null;
+let idleCheckInterval: NodeJS.Timeout | null = null;
+const IDLE_CHECK_INTERVAL_MS = 60 * 1000;
+
+/**
+ * Configure the idle timeout for LSP clients.
+ * @param ms - Timeout in milliseconds, or null/undefined to disable
+ */
+export function setIdleTimeout(ms: number | null | undefined): void {
+	idleTimeoutMs = ms ?? null;
+
+	if (idleTimeoutMs && idleTimeoutMs > 0) {
+		startIdleChecker();
+	} else {
+		stopIdleChecker();
+	}
+}
+
+function startIdleChecker(): void {
+	if (idleCheckInterval) return;
+	idleCheckInterval = setInterval(() => {
+		if (!idleTimeoutMs) return;
+		const now = Date.now();
+		for (const [key, client] of Array.from(clients.entries())) {
+			if (now - client.lastActivity > idleTimeoutMs) {
+				void shutdownClient(key);
+			}
+		}
+	}, IDLE_CHECK_INTERVAL_MS);
+}
+
+function stopIdleChecker(): void {
+	if (idleCheckInterval) {
+		clearInterval(idleCheckInterval);
+		idleCheckInterval = null;
+	}
+}
+
+// =============================================================================
+// Client Capabilities
+// =============================================================================
+
+const CLIENT_CAPABILITIES = {
+	textDocument: {
+		synchronization: {
+			didSave: true,
+			dynamicRegistration: false,
+			willSave: false,
+			willSaveWaitUntil: false,
+		},
+		hover: {
+			contentFormat: ["markdown", "plaintext"],
+			dynamicRegistration: false,
+		},
+		definition: {
+			dynamicRegistration: false,
+			linkSupport: true,
+		},
+		typeDefinition: {
+			dynamicRegistration: false,
+			linkSupport: true,
+		},
+		implementation: {
+			dynamicRegistration: false,
+			linkSupport: true,
+		},
+		references: {
+			dynamicRegistration: false,
+		},
+		documentSymbol: {
+			dynamicRegistration: false,
+			hierarchicalDocumentSymbolSupport: true,
+			symbolKind: {
+				valueSet: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26],
+			},
+		},
+		rename: {
+			dynamicRegistration: false,
+			prepareSupport: true,
+		},
+		codeAction: {
+			dynamicRegistration: false,
+			codeActionLiteralSupport: {
+				codeActionKind: {
+					valueSet: [
+						"quickfix",
+						"refactor",
+						"refactor.extract",
+						"refactor.inline",
+						"refactor.rewrite",
+						"source",
+						"source.organizeImports",
+						"source.fixAll",
+					],
+				},
+			},
+			resolveSupport: {
+				properties: ["edit"],
+			},
+		},
+		formatting: {
+			dynamicRegistration: false,
+		},
+		rangeFormatting: {
+			dynamicRegistration: false,
+		},
+		publishDiagnostics: {
+			relatedInformation: true,
+			versionSupport: true,
+			tagSupport: { valueSet: [1, 2] },
+			codeDescriptionSupport: true,
+			dataSupport: true,
+		},
+	},
+	window: {
+		workDoneProgress: true,
+	},
+	workspace: {
+		applyEdit: true,
+		workspaceEdit: {
+			documentChanges: true,
+			resourceOperations: ["create", "rename", "delete"],
+			failureHandling: "textOnlyTransactional",
+		},
+		configuration: true,
+		workspaceFolders: true,
+		symbol: {
+			dynamicRegistration: false,
+			symbolKind: {
+				valueSet: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26],
+			},
+		},
+		fileOperations: {
+			dynamicRegistration: false,
+			willCreate: false,
+			didCreate: false,
+			willRename: true,
+			didRename: true,
+			willDelete: false,
+			didDelete: false,
+		},
+	},
+	experimental: {
+		snippetTextEdit: true,
+	},
+};
+
+// =============================================================================
+// LSP Message Protocol
+// =============================================================================
+
+async function writeMessage(
+	sink: Bun.FileSink,
+	message: LspJsonRpcRequest | LspJsonRpcNotification | LspJsonRpcResponse,
+): Promise<void> {
+	const content = JSON.stringify(message);
+	sink.write(`Content-Length: ${Buffer.byteLength(content, "utf-8")}\r\n\r\n${content}`);
+	await sink.flush();
+}
+
+function queueWriteMessage(
+	client: LspClient,
+	message: LspJsonRpcRequest | LspJsonRpcNotification | LspJsonRpcResponse,
+): Promise<void> {
+	const write = client.writeQueue.catch(() => {}).then(() => writeMessage(client.proc.stdin, message));
+	client.writeQueue = write.catch(() => {});
+	return write;
+}
+
+// =============================================================================
+// Message Reader
+// =============================================================================
+
+/**
+ * Start background message reader for a client.
+ * Routes responses to pending requests and handles notifications.
+ */
+async function startMessageReader(client: LspClient): Promise<void> {
+	if (client.isReading) return;
+	client.isReading = true;
+
+	const reader = (client.proc.stdout as ReadableStream<Uint8Array>).getReader();
+
+	const framer = new MessageFramer(Buffer.from(client.messageBuffer));
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			framer.push(Buffer.from(value));
+
+			// Drain every complete message currently buffered.
+			for (const messageText of framer.drain(headerText => {
+				// Non-protocol bytes on stdout (e.g. a wrapper script printing).
+				// Drop past the bogus terminator and resync instead of stalling
+				// on the same junk header forever.
+				logger.warn("LSP framing resync: header block without Content-Length", {
+					server: client.name,
+					header: headerText.slice(0, 200),
+				});
+			})) {
+				// A malformed message or a throwing server-request handler must not
+				// kill the reader — later messages are still well-framed.
+				try {
+					const message: LspJsonRpcResponse | LspJsonRpcNotification = JSON.parse(messageText);
+
+					// Route message. A JSON-RPC message carrying a `method` is always
+					// server-originated: a request when it also has an `id`, a
+					// notification otherwise. A message with only an `id` is a response
+					// to one of our requests. Disambiguate on `method` FIRST: a
+					// server's request ids live in its own id space and routinely
+					// collide with our in-flight client request ids (e.g. a
+					// basedpyright `workspace/configuration` pull arriving while a
+					// `documentSymbol` request with the same id is pending). Matching
+					// pending requests first would swallow that pull as a bogus
+					// response -- dropping the config answer the server blocks on and
+					// resolving our request with `undefined`, wedging the lazy
+					// cold-start handshake (#3001).
+					if ("method" in message) {
+						if ("id" in message && message.id !== undefined) {
+							// Server-initiated request: must be answered.
+							await handleServerRequest(client, message as LspJsonRpcRequest);
+						} else {
+							// Server notification
+							if (message.method === "textDocument/publishDiagnostics" && message.params) {
+								const params = message.params as PublishDiagnosticsParams;
+								client.diagnostics.set(params.uri, {
+									diagnostics: params.diagnostics,
+									version: params.version ?? null,
+								});
+								client.diagnosticsVersion += 1;
+							} else if (message.method === "$/progress" && message.params) {
+								const params = message.params as { token: string | number; value?: { kind?: string } };
+								if (params.value?.kind === "begin") {
+									client.activeProgressTokens.add(params.token);
+								} else if (params.value?.kind === "end") {
+									client.activeProgressTokens.delete(params.token);
+									if (client.activeProgressTokens.size === 0) {
+										client.resolveProjectLoaded();
+									}
+								}
+							}
+						}
+					} else if ("id" in message && message.id !== undefined) {
+						// Response to one of our requests.
+						const pending = client.pendingRequests.get(message.id);
+						if (pending) {
+							client.pendingRequests.delete(message.id);
+							if ("error" in message && message.error) {
+								pending.reject(new Error(`LSP error: ${message.error.message}`));
+							} else {
+								pending.resolve(message.result);
+							}
+						}
+					}
+				} catch (err) {
+					logger.warn("LSP message handling failed", {
+						server: client.name,
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			}
+		}
+	} catch (err) {
+		// Connection closed or error - reject all pending requests
+		for (const pending of Array.from(client.pendingRequests.values())) {
+			pending.reject(new Error(`LSP connection closed: ${err}`));
+		}
+		client.pendingRequests.clear();
+	} finally {
+		// Persist any unparsed remainder so a restarted reader resumes mid-message.
+		client.messageBuffer = framer.remainder();
+		reader.releaseLock();
+		client.isReading = false;
+		// Reader exited while the server process is still alive (unrecoverable
+		// read error or bad stream state): nothing will route responses anymore,
+		// so tear the client down — the next call respawns instead of timing out.
+		if (client.proc.exitCode === null) {
+			client.status = "error";
+			if (clients.get(client.name) === client) {
+				clients.delete(client.name);
+			}
+			const teardownErr = new Error("LSP reader stopped; client torn down");
+			for (const pending of client.pendingRequests.values()) {
+				pending.reject(teardownErr);
+			}
+			client.pendingRequests.clear();
+			client.resolveProjectLoaded();
+			client.proc.kill();
+		}
+	}
+}
+
+/**
+ * Build the workspace folder list advertised to the server. Identical shape
+ * for `initialize` params and `workspace/workspaceFolders` server requests.
+ */
+function currentWorkspaceFolders(client: LspClient): Array<{ uri: string; name: string }> {
+	return [{ uri: fileToUri(client.cwd), name: path.basename(client.cwd) || "workspace" }];
+}
+
+/**
+ * Handle workspace/workspaceFolders requests from the server.
+ */
+async function handleWorkspaceFoldersRequest(client: LspClient, message: LspJsonRpcRequest): Promise<void> {
+	await sendResponse(client, message.id, currentWorkspaceFolders(client), "workspace/workspaceFolders");
+}
+
+/**
+ * Handle workspace/configuration requests from the server.
+ */
+async function handleConfigurationRequest(client: LspClient, message: LspJsonRpcRequest): Promise<void> {
+	const params = message.params as { items?: Array<{ section?: string }> };
+	const items = params?.items ?? [];
+	const result = items.map(item => {
+		const section = item.section ?? "";
+		return client.config.settings?.[section] ?? {};
+	});
+	await sendResponse(client, message.id, result, "workspace/configuration");
+}
+
+/**
+ * Handle workspace/applyEdit requests from the server.
+ */
+async function handleApplyEditRequest(client: LspClient, message: LspJsonRpcRequest): Promise<void> {
+	const params = message.params as { edit?: WorkspaceEdit };
+	if (!params?.edit) {
+		await sendResponse(
+			client,
+			message.id,
+			{ applied: false, failureReason: "No edit provided" },
+			"workspace/applyEdit",
+		);
+		return;
+	}
+
+	try {
+		await applyWorkspaceEdit(params.edit, client.cwd);
+		await sendResponse(client, message.id, { applied: true }, "workspace/applyEdit");
+	} catch (err) {
+		await sendResponse(client, message.id, { applied: false, failureReason: String(err) }, "workspace/applyEdit");
+	}
+}
+
+/**
+ * Respond to a server-initiated request.
+ */
+async function handleServerRequest(client: LspClient, message: LspJsonRpcRequest): Promise<void> {
+	if (message.method === "workspace/configuration") {
+		await handleConfigurationRequest(client, message);
+		return;
+	}
+	if (message.method === "workspace/workspaceFolders") {
+		await handleWorkspaceFoldersRequest(client, message);
+		return;
+	}
+	if (message.method === "workspace/applyEdit") {
+		await handleApplyEditRequest(client, message);
+		return;
+	}
+	if (message.method === "window/workDoneProgress/create") {
+		// Accept progress token registration from the server.
+		await sendResponse(client, message.id, null, message.method);
+		return;
+	}
+	if (message.method === "client/registerCapability" || message.method === "client/unregisterCapability") {
+		// Some servers block semantic requests until dynamic registration succeeds.
+		await sendResponse(client, message.id, null, message.method);
+		return;
+	}
+	if (message.method === "window/showMessageRequest") {
+		// Headless: no UI to surface the prompt. Spec says null = "no action selected".
+		await sendResponse(client, message.id, null, message.method);
+		return;
+	}
+	if (message.method === "window/showDocument") {
+		// Headless: nothing to display. Spec result is `{ success: boolean }`.
+		await sendResponse(client, message.id, { success: false }, message.method);
+		return;
+	}
+	if (
+		message.method === "workspace/semanticTokens/refresh" ||
+		message.method === "workspace/inlayHint/refresh" ||
+		message.method === "workspace/codeLens/refresh" ||
+		message.method === "workspace/codeAction/refresh" ||
+		message.method === "workspace/inlineValue/refresh" ||
+		message.method === "workspace/foldingRange/refresh" ||
+		message.method === "workspace/diagnostic/refresh"
+	) {
+		// Void acknowledgement per spec; servers that stall waiting for a reply
+		// (same failure mode as the dynamic-registration hang in #3029) move on.
+		await sendResponse(client, message.id, null, message.method);
+		return;
+	}
+	await sendResponse(client, message.id, null, message.method, {
+		code: -32601,
+		message: `Method not found: ${message.method}`,
+	});
+}
+
+/**
+ * Send an LSP response to the server.
+ */
+async function sendResponse(
+	client: LspClient,
+	id: LspJsonRpcId,
+	result: unknown,
+	method: string,
+	error?: { code: number; message: string; data?: unknown },
+): Promise<void> {
+	const response: LspJsonRpcResponse = {
+		jsonrpc: "2.0",
+		id,
+		...(error ? { error } : { result }),
+	};
+
+	try {
+		await queueWriteMessage(client, response);
+	} catch (err) {
+		logger.error("LSP failed to respond.", { method, error: String(err) });
+	}
+}
+
+// =============================================================================
+// Client Management
+// =============================================================================
+
+/** Timeout for warmup initialize requests (5 seconds) */
+export const WARMUP_TIMEOUT_MS = 5000;
+
+/** Max time to poll rust-analyzer after progress ends but before Cargo workspaces are ready. */
+const RUST_ANALYZER_WORKSPACE_READY_TIMEOUT_MS = 5_000;
+const RUST_ANALYZER_WORKSPACE_READY_POLL_MS = 100;
+const RUST_ANALYZER_WORKSPACE_READY_SETTLE_MS = 2_000;
+const RUST_ANALYZER_STATUS_REQUEST_TIMEOUT_MS = 1_000;
+const rustAnalyzerReadyClients = new WeakSet<LspClient>();
+
+function commandBasename(command: string): string {
+	const slash = command.lastIndexOf("/");
+	const backslash = command.lastIndexOf("\\");
+	const separator = Math.max(slash, backslash);
+	return separator === -1 ? command : command.slice(separator + 1);
+}
+
+function isRustAnalyzerClient(client: LspClient): boolean {
+	return (
+		commandBasename(client.config.command) === "rust-analyzer" ||
+		(client.config.resolvedCommand ? commandBasename(client.config.resolvedCommand) === "rust-analyzer" : false)
+	);
+}
+
+function isRustAnalyzerStatusTimeout(err: unknown): boolean {
+	return err instanceof Error && err.message.startsWith("LSP request rust-analyzer/analyzerStatus timed out after ");
+}
+
+async function waitForRustAnalyzerWorkspace(client: LspClient, signal?: AbortSignal): Promise<void> {
+	if (rustAnalyzerReadyClients.has(client)) {
+		return;
+	}
+	const timings = client.config.workspaceReadyTimings;
+	const timeoutMs = timings?.timeoutMs ?? RUST_ANALYZER_WORKSPACE_READY_TIMEOUT_MS;
+	const pollMs = timings?.pollMs ?? RUST_ANALYZER_WORKSPACE_READY_POLL_MS;
+	const settleMs = timings?.settleMs ?? RUST_ANALYZER_WORKSPACE_READY_SETTLE_MS;
+	const statusRequestTimeoutMs = timings?.statusRequestTimeoutMs ?? RUST_ANALYZER_STATUS_REQUEST_TIMEOUT_MS;
+	const started = Date.now();
+	const deadline = started + timeoutMs;
+	while (true) {
+		throwIfAborted(signal);
+		let status: unknown;
+		try {
+			status = await sendRequest(client, "rust-analyzer/analyzerStatus", {}, signal, statusRequestTimeoutMs);
+		} catch (err) {
+			if (!isRustAnalyzerStatusTimeout(err) || Date.now() >= deadline) {
+				return;
+			}
+			await Bun.sleep(pollMs);
+			continue;
+		}
+		const ready = typeof status === "string" && !status.startsWith("No workspaces");
+		if (ready && Date.now() - started >= settleMs) {
+			rustAnalyzerReadyClients.add(client);
+			return;
+		}
+		if (Date.now() >= deadline) {
+			return;
+		}
+		await Bun.sleep(pollMs);
+	}
+}
+
+const PROJECT_LOAD_TIMEOUT_MS = 15_000;
+
+/** Max time to wait for graceful LSP shutdown and process exit. */
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+const EXIT_TIMEOUT_MS = 1_000;
+
+/**
+ * Get or create an LSP client for the given server configuration and working directory.
+ * @param config - Server configuration
+ * @param cwd - Working directory
+ * @param initTimeoutMs - Optional timeout for the initialize request (defaults to 30s)
+ */
+export async function getOrCreateClient(config: ServerConfig, cwd: string, initTimeoutMs?: number): Promise<LspClient> {
+	const key = `${config.command}:${cwd}`;
+
+	// Check if client already exists
+	const existingClient = clients.get(key);
+	if (existingClient) {
+		existingClient.lastActivity = Date.now();
+		return existingClient;
+	}
+
+	// Check if another coroutine is already creating this client
+	const existingLock = clientLocks.get(key);
+	if (existingLock) {
+		return existingLock;
+	}
+
+	// Fail fast on a recent deterministic init failure instead of re-spawning
+	// a broken server (and paying its full init wait) on every call.
+	const recentFailure = initFailures.get(key);
+	if (recentFailure) {
+		if (Date.now() - recentFailure.at < INIT_FAILURE_BACKOFF_MS) {
+			throw new Error(`LSP server ${config.command} failed to initialize recently: ${recentFailure.message}`);
+		}
+		initFailures.delete(key);
+	}
+
+	// Create new client with lock
+	const clientPromise = (async () => {
+		const baseCommand = config.resolvedCommand ?? config.command;
+		const baseArgs = config.args ?? [];
+
+		// Wrap with lspmux if available and supported
+		const { command, args, env } = isLspmuxSupported(baseCommand)
+			? await getLspmuxCommand(baseCommand, baseArgs)
+			: { command: baseCommand, args: baseArgs };
+
+		const proc = ptree.spawn([command, ...args], {
+			cwd,
+			stdin: "pipe",
+			env: env ? { ...Bun.env, ...env } : undefined,
+		});
+
+		let resolveProjectLoaded!: () => void;
+		const projectLoaded = new Promise<void>(resolve => {
+			resolveProjectLoaded = resolve;
+		});
+		// Auto-resolve after timeout in case server doesn't use progress tokens
+		const projectLoadTimeout = setTimeout(resolveProjectLoaded, PROJECT_LOAD_TIMEOUT_MS);
+		const originalResolve = resolveProjectLoaded;
+		resolveProjectLoaded = () => {
+			clearTimeout(projectLoadTimeout);
+			originalResolve();
+		};
+
+		const client: LspClient = {
+			name: key,
+			cwd,
+			proc,
+			config,
+			requestId: 0,
+			diagnostics: new Map(),
+			diagnosticsVersion: 0,
+			openFiles: new Map(),
+			pendingRequests: new Map(),
+			messageBuffer: new Uint8Array(0),
+			isReading: false,
+			status: "connecting",
+			lastActivity: Date.now(),
+			writeQueue: Promise.resolve(),
+			activeProgressTokens: new Set(),
+			projectLoaded,
+			resolveProjectLoaded,
+		};
+
+		// Register crash recovery - remove client on process exit
+		proc.exited.then(() => {
+			if (clients.get(key) === client) clients.delete(key);
+			if (clientLocks.get(key) === clientPromise) clientLocks.delete(key);
+			client.resolveProjectLoaded();
+
+			// Reject any pending requests — the server is gone, they will never complete.
+			if (client.pendingRequests.size > 0) {
+				// Strip informational log lines (e.g. marksman's [INF]/[DBG] prefix)
+				// — they are startup noise, not actionable errors.
+				const rawStderr = proc.peekStderr().trim();
+				const stderr = rawStderr
+					.split("\n")
+					.filter(line => !/^\[\d{2}:\d{2}:\d{2} (?:INF|DBG|VRB)\]/.test(line))
+					.join("\n")
+					.trim();
+				const code = proc.exitCode;
+				const err = new Error(
+					stderr ? `LSP server exited (code ${code}): ${stderr}` : `LSP server exited unexpectedly (code ${code})`,
+				);
+				for (const pending of client.pendingRequests.values()) {
+					pending.reject(err);
+				}
+				client.pendingRequests.clear();
+			}
+		});
+
+		// Start background message reader
+		startMessageReader(client);
+
+		try {
+			// Send initialize request
+			const initResult = (await sendRequest(
+				client,
+				"initialize",
+				{
+					processId: process.pid,
+					rootUri: fileToUri(cwd),
+					rootPath: cwd,
+					capabilities: CLIENT_CAPABILITIES,
+					initializationOptions: config.initOptions ?? {},
+					workspaceFolders: currentWorkspaceFolders(client),
+				},
+				undefined, // signal
+				initTimeoutMs,
+			)) as { capabilities?: unknown };
+
+			if (!initResult) {
+				throw new Error("Failed to initialize LSP: no response");
+			}
+
+			client.serverCapabilities = initResult.capabilities as LspClient["serverCapabilities"];
+
+			// Send initialized notification
+			await sendNotification(client, "initialized", {});
+
+			client.status = "ready";
+			// Publish only after init succeeds: pre-init clients are reachable
+			// solely through clientLocks, so concurrent callers (warmup vs first
+			// tool call) wait for init instead of using an unacknowledged client.
+			clients.set(key, client);
+			initFailures.delete(key);
+			return client;
+		} catch (err) {
+			// Clean up on initialization failure
+			client.status = "error";
+			if (clients.get(key) === client) clients.delete(key);
+			proc.kill();
+			const message = err instanceof Error ? err.message : String(err);
+			// Negative-cache deterministic failures. Timeouts under a
+			// caller-shortened deadline (warmup/writethrough) are not cached —
+			// the server may simply be slow and a later call with the full
+			// deadline can still succeed.
+			if (!(initTimeoutMs !== undefined && message.includes("timed out"))) {
+				initFailures.set(key, { at: Date.now(), message });
+			}
+			throw err;
+		} finally {
+			clientLocks.delete(key);
+		}
+	})();
+
+	clientLocks.set(key, clientPromise);
+	return clientPromise;
+}
+
+/**
+ * Ensure a file is opened in the LSP client.
+ * Sends didOpen notification if the file is not already tracked.
+ */
+export async function ensureFileOpen(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void> {
+	throwIfAborted(signal);
+	const uri = fileToUri(filePath);
+	const lockKey = `${client.name}:${uri}`;
+
+	// Check if file is already open
+	if (client.openFiles.has(uri)) {
+		return;
+	}
+
+	// Check if another operation is already opening this file
+	const existingLock = fileOperationLocks.get(lockKey);
+	if (existingLock) {
+		await untilAborted(signal, () => existingLock);
+		return;
+	}
+
+	// Lock and open file
+	const openPromise = (async () => {
+		throwIfAborted(signal);
+		// Double-check after acquiring lock
+		if (client.openFiles.has(uri)) {
+			return;
+		}
+
+		let content: string;
+		try {
+			content = await Bun.file(filePath).text();
+			throwIfAborted(signal);
+		} catch (err) {
+			if (isEnoent(err)) return;
+			throw err;
+		}
+		const languageId = detectLanguageId(filePath);
+		throwIfAborted(signal);
+
+		await sendNotification(client, "textDocument/didOpen", {
+			textDocument: {
+				uri,
+				languageId,
+				version: 1,
+				text: content,
+			},
+		});
+
+		client.openFiles.set(uri, { version: 1, languageId });
+		client.lastActivity = Date.now();
+	})();
+
+	fileOperationLocks.set(lockKey, openPromise);
+	try {
+		await openPromise;
+	} finally {
+		fileOperationLocks.delete(lockKey);
+	}
+}
+
+/**
+ * Wait for the server's initial project loading to complete.
+ * Races the server's $/progress tracking against the abort signal.
+ * Returns immediately if loading already completed or timed out.
+ */
+export async function waitForProjectLoaded(client: LspClient, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return;
+	await Promise.race([
+		client.projectLoaded,
+		...(signal
+			? [new Promise<void>(resolve => signal.addEventListener("abort", () => resolve(), { once: true }))]
+			: []),
+	]);
+	if (isRustAnalyzerClient(client)) {
+		await waitForRustAnalyzerWorkspace(client, signal);
+	}
+}
+
+/**
+ * Sync in-memory content to the LSP client without reading from disk.
+ * Use this to provide instant feedback during edits before the file is saved.
+ */
+export async function syncContent(
+	client: LspClient,
+	filePath: string,
+	content: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	const uri = fileToUri(filePath);
+	const lockKey = `${client.name}:${uri}`;
+	throwIfAborted(signal);
+
+	const existingLock = fileOperationLocks.get(lockKey);
+	if (existingLock) {
+		await untilAborted(signal, () => existingLock);
+	}
+
+	const syncPromise = (async () => {
+		// Clear stale diagnostics before syncing new content
+		client.diagnostics.delete(uri);
+
+		const info = client.openFiles.get(uri);
+
+		if (!info) {
+			// Open file with provided content instead of reading from disk
+			const languageId = detectLanguageId(filePath);
+			throwIfAborted(signal);
+			await sendNotification(client, "textDocument/didOpen", {
+				textDocument: {
+					uri,
+					languageId,
+					version: 1,
+					text: content,
+				},
+			});
+			client.openFiles.set(uri, { version: 1, languageId });
+			client.lastActivity = Date.now();
+			return;
+		}
+
+		const version = ++info.version;
+		throwIfAborted(signal);
+		await sendNotification(client, "textDocument/didChange", {
+			textDocument: { uri, version },
+			contentChanges: [{ text: content }],
+		});
+		client.lastActivity = Date.now();
+	})();
+
+	fileOperationLocks.set(lockKey, syncPromise);
+	try {
+		await syncPromise;
+	} finally {
+		fileOperationLocks.delete(lockKey);
+	}
+}
+
+/**
+ * Notify LSP that a file was saved.
+ * Assumes content was already synced via syncContent - just sends didSave.
+ */
+export async function notifySaved(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void> {
+	const uri = fileToUri(filePath);
+	const info = client.openFiles.get(uri);
+	if (!info) return; // File not open, nothing to notify
+
+	throwIfAborted(signal);
+	await sendNotification(client, "textDocument/didSave", {
+		textDocument: { uri },
+	});
+	client.lastActivity = Date.now();
+}
+
+/**
+ * Refresh a file in the LSP client.
+ * Increments version, sends didChange and didSave notifications.
+ */
+export async function refreshFile(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void> {
+	throwIfAborted(signal);
+	const uri = fileToUri(filePath);
+	const lockKey = `${client.name}:${uri}`;
+
+	const existingLock = fileOperationLocks.get(lockKey);
+	if (existingLock) {
+		await untilAborted(signal, () => existingLock);
+	}
+
+	const refreshPromise = (async () => {
+		throwIfAborted(signal);
+		// Drop cached diagnostics for this URI before asking the server to recompute.
+		// Otherwise an unrelated publishDiagnostics notification can advance the global
+		// diagnostics version and cause waiters to accept stale unversioned diagnostics.
+		client.diagnostics.delete(uri);
+		const info = client.openFiles.get(uri);
+
+		if (!info) {
+			await ensureFileOpen(client, filePath, signal);
+			return;
+		}
+
+		let content: string;
+		try {
+			content = await Bun.file(filePath).text();
+			throwIfAborted(signal);
+		} catch (err) {
+			if (isEnoent(err)) return;
+			throw err;
+		}
+		const version = ++info.version;
+		throwIfAborted(signal);
+
+		await sendNotification(client, "textDocument/didChange", {
+			textDocument: { uri, version },
+			contentChanges: [{ text: content }],
+		});
+		throwIfAborted(signal);
+
+		await sendNotification(client, "textDocument/didSave", {
+			textDocument: { uri },
+			text: content,
+		});
+
+		client.lastActivity = Date.now();
+	})();
+
+	fileOperationLocks.set(lockKey, refreshPromise);
+	try {
+		await refreshPromise;
+	} finally {
+		fileOperationLocks.delete(lockKey);
+	}
+}
+
+async function waitForExit(client: LspClient, timeoutMs: number): Promise<boolean> {
+	return await Promise.race([
+		client.proc.exited.then(
+			() => true,
+			() => true,
+		),
+		Bun.sleep(timeoutMs).then(() => false),
+	]);
+}
+
+/**
+ * Shutdown a specific client instance using the LSP shutdown/exit handshake.
+ */
+async function shutdownClientInstance(client: LspClient): Promise<void> {
+	const err = new Error("LSP client shutdown");
+	for (const pending of Array.from(client.pendingRequests.values())) {
+		pending.reject(err);
+	}
+	client.pendingRequests.clear();
+
+	const shutdownCompleted = await sendRequest(client, "shutdown", null, undefined, SHUTDOWN_TIMEOUT_MS).then(
+		() => true,
+		() => false,
+	);
+	if (shutdownCompleted) {
+		await sendNotification(client, "exit", undefined).catch(() => {});
+		if (await waitForExit(client, EXIT_TIMEOUT_MS)) return;
+	}
+
+	client.proc.kill();
+	await waitForExit(client, EXIT_TIMEOUT_MS);
+}
+
+/**
+ * Shutdown a specific client by key.
+ */
+export async function shutdownClient(key: string): Promise<void> {
+	const client = clients.get(key);
+	if (!client) return;
+	clients.delete(key);
+	await shutdownClientInstance(client);
+}
+
+// =============================================================================
+// LSP Protocol Methods
+// =============================================================================
+
+/** Default timeout for LSP requests when no abort signal is provided (30 seconds) */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
+/**
+ * Send an LSP request and wait for response.
+ *
+ * Timeout policy:
+ * - If `timeoutMs` is explicitly provided, that value is used.
+ * - Else, if `signal` is provided, no internal timer is installed (the caller
+ *   owns the deadline via the signal — typically a wall-clock `AbortSignal.timeout`
+ *   from the LSP tool). Installing a second hard-coded 30s timer here used to
+ *   cause "timed out after 30000ms" errors even when the caller had requested
+ *   `timeout: 60`.
+ * - Else (no signal, no explicit timeout), fall back to `DEFAULT_REQUEST_TIMEOUT_MS`
+ *   to avoid leaking pending requests forever.
+ */
+export async function sendRequest(
+	client: LspClient,
+	method: string,
+	params: unknown,
+	signal?: AbortSignal,
+	timeoutMs?: number,
+): Promise<unknown> {
+	// Atomically increment and capture request ID
+	const id = ++client.requestId;
+	if (signal?.aborted) {
+		const reason = signal.reason instanceof Error ? signal.reason : new ToolAbortError();
+		return Promise.reject(reason);
+	}
+
+	const request: LspJsonRpcRequest = {
+		jsonrpc: "2.0",
+		id,
+		method,
+		params,
+	};
+
+	client.lastActivity = Date.now();
+
+	const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+	let timeout: NodeJS.Timeout | undefined;
+	const cleanup = () => {
+		if (signal) {
+			signal.removeEventListener("abort", abortHandler);
+		}
+	};
+	const abortHandler = () => {
+		if (client.pendingRequests.has(id)) {
+			client.pendingRequests.delete(id);
+		}
+		void sendNotification(client, "$/cancelRequest", { id }).catch(() => {});
+		if (timeout) clearTimeout(timeout);
+		cleanup();
+		const reason = signal?.reason instanceof Error ? signal.reason : new ToolAbortError();
+		reject(reason);
+	};
+
+	const effectiveTimeoutMs = timeoutMs ?? (signal ? undefined : DEFAULT_REQUEST_TIMEOUT_MS);
+	if (effectiveTimeoutMs !== undefined) {
+		timeout = setTimeout(() => {
+			if (client.pendingRequests.has(id)) {
+				client.pendingRequests.delete(id);
+				const err = new Error(`LSP request ${method} timed out after ${effectiveTimeoutMs}ms`);
+				cleanup();
+				reject(err);
+			}
+		}, effectiveTimeoutMs);
+	}
+	if (signal) {
+		signal.addEventListener("abort", abortHandler, { once: true });
+		if (signal.aborted) {
+			abortHandler();
+			return promise;
+		}
+	}
+
+	// Register pending request with timeout wrapper
+	client.pendingRequests.set(id, {
+		resolve: result => {
+			if (timeout) clearTimeout(timeout);
+			cleanup();
+			resolve(result);
+		},
+		reject: err => {
+			if (timeout) clearTimeout(timeout);
+			cleanup();
+			reject(err);
+		},
+		method,
+	});
+
+	// Write request
+	queueWriteMessage(client, request).catch(err => {
+		if (timeout) clearTimeout(timeout);
+		client.pendingRequests.delete(id);
+		cleanup();
+		reject(err);
+	});
+	return promise;
+}
+
+/**
+ * Send an LSP notification (no response expected).
+ */
+export async function sendNotification(client: LspClient, method: string, params: unknown): Promise<void> {
+	const notification: LspJsonRpcNotification = {
+		jsonrpc: "2.0",
+		method,
+		params,
+	};
+
+	client.lastActivity = Date.now();
+	await queueWriteMessage(client, notification);
+}
+
+/**
+ * Shutdown all LSP clients.
+ */
+export async function shutdownAll(): Promise<void> {
+	const clientsToShutdown = Array.from(clients.values());
+	clients.clear();
+	// Mid-initialize clients live only in clientLocks (publication is deferred
+	// until init succeeds) — without this, their server processes outlive
+	// shutdown. Failed init promises already cleaned up after themselves.
+	const pendingClients = Array.from(clientLocks.values());
+	clientLocks.clear();
+	const seen = new Set<LspClient>(clientsToShutdown);
+	await Promise.allSettled([
+		...clientsToShutdown.map(client => shutdownClientInstance(client)),
+		...pendingClients.map(pending =>
+			pending.then(client => {
+				if (seen.has(client)) return;
+				seen.add(client);
+				return shutdownClientInstance(client);
+			}),
+		),
+	]);
+}
+
+/** Status of an LSP server */
+export interface LspServerStatus {
+	name: string;
+	status: "connecting" | "ready" | "error";
+	fileTypes: string[];
+	error?: string;
+}
+
+/**
+ * Get status of all active LSP clients.
+ */
+export function getActiveClients(): LspServerStatus[] {
+	return Array.from(clients.values()).map(client => ({
+		name: client.config.command,
+		status: client.status,
+		fileTypes: client.config.fileTypes,
+	}));
+}
+
+// =============================================================================
+// Process Cleanup
+// =============================================================================
+
+// Register cleanup on module unload
+if (typeof process !== "undefined") {
+	process.on("beforeExit", () => {
+		void shutdownAll();
+	});
+	process.on("SIGINT", () => {
+		void (async () => {
+			await shutdownAll();
+			process.exit(0);
+		})();
+	});
+	process.on("SIGTERM", () => {
+		void (async () => {
+			await shutdownAll();
+			process.exit(0);
+		})();
+	});
+}