pi-lsp-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom McPhail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# pi-lsp-lite
+
+[pi](https://github.com/mariozechner/pi) extension that feeds LSP diagnostics back to the agent after every `write` and `edit`. Go, Rust, and TypeScript via `gopls`, `rust-analyzer`, and `typescript-language-server`.
+
+The agent sees errors and warnings inline on the same turn as the edit that caused them.
+
+## Install
+
+```bash
+pi install git:github.com/mcphailtom/pi-lsp-lite
+```
+
+Or from npm:
+
+```bash
+pi install npm:pi-lsp-lite
+```
+
+## Prerequisites
+
+Language servers must be on `PATH`. If missing, that language is silently disabled.
+
+| Server | Language | Install |
+|--------|----------|---------|
+| `gopls` | Go | `go install golang.org/x/tools/gopls@latest` |
+| `rust-analyzer` | Rust | `rustup component add rust-analyzer` |
+| `typescript-language-server` | TypeScript/JavaScript | `npm install -g typescript-language-server typescript` |
+
+## Usage
+
+No configuration needed. Once installed, diagnostics appear automatically after every `write` or `edit` to a supported file:
+
+```
+⚠ LSP diagnostics for main.go (2 errors):
+  error 12:5 [compiler] undefined: foo
+  error 18:2 [compiler] too many arguments in call to bar
+  + 1 diagnostic in 1 other file
+```
+
+Use `/lsp-status` to see running servers.
+
+## How it works
+
+Edits trigger `textDocument/didOpen` or `textDocument/didChange` against a long-lived language server. Diagnostics are collected within a 3-second window and appended to the tool result. Workspace roots are detected automatically (`go.mod`, `Cargo.toml`, `tsconfig.json`, `package.json`).
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for internals.
+
+## Development
+
+```bash
+git clone https://github.com/mcphailtom/pi-lsp-lite
+cd pi-lsp-lite
+npm install
+npm run check        # typecheck
+npm test             # unit tests
+npm run test:integration  # requires servers on PATH
+```
+
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for details.
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,60 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createServerManager } from "./src/server-manager.js";
+import { languageForFile, checkExtensionOverlaps } from "./src/languages.js";
+import { formatDiagnostics } from "./src/format.js";
+import { resolve, relative, isAbsolute } from "node:path";
+
+export default function (pi: ExtensionAPI) {
+  const manager = createServerManager();
+
+  for (const warning of checkExtensionOverlaps()) {
+    console.error(`[pi-lsp-lite] ${warning}`);
+  }
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.toolName !== "write" && event.toolName !== "edit") return;
+
+    const rawPath = event.input?.path;
+    const filePath = typeof rawPath === "string" ? rawPath : undefined;
+    if (!filePath) return;
+
+    const absolutePath = resolve(ctx.cwd, filePath);
+    const rel = relative(ctx.cwd, absolutePath);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) return;
+    const config = languageForFile(absolutePath);
+    if (!config) return;
+
+    try {
+      const result = await manager.handleEdit(absolutePath, config, ctx.cwd);
+      const formatted = formatDiagnostics(filePath, result);
+      if (!formatted) return;
+
+      return {
+        content: [...event.content, { type: "text" as const, text: formatted }],
+      };
+    } catch (err) {
+      console.error("[pi-lsp-lite]", err);
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    await manager.shutdownAll();
+  });
+
+  pi.registerCommand("lsp-status", {
+    description: "Show running LSP servers and recent diagnostic counts",
+    handler: async (_args, ctx) => {
+      const servers = manager.status();
+      if (servers.length === 0) {
+        ctx.ui.notify("pi-lsp-lite: no servers running", "info");
+        return;
+      }
+      const lines = servers.map((s) => {
+        const idle = Math.round((Date.now() - s.lastActivity) / 1000);
+        const up = Math.round(s.uptime / 1000);
+        return `${s.id} (pid ${s.pid}) root=${s.root} — ${s.openDocuments} open files, up ${up}s, idle ${idle}s`;
+      });
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-lsp-lite",
+  "version": "0.1.0",
+  "description": "pi extension: feeds LSP diagnostics back to the agent after every write/edit. Go, Rust, and TypeScript.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "lsp",
+    "gopls",
+    "rust-analyzer",
+    "typescript-language-server"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "vscode-languageserver-protocol": "^3.17.5"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:integration": "INTEGRATION=1 tsx --test test/*.test.ts test/integration/*.test.ts"
+  }
+}

package/src/client.ts

@@ -0,0 +1,228 @@
+import {
+  createProtocolConnection,
+  StreamMessageReader,
+  StreamMessageWriter,
+  InitializeRequest,
+  InitializedNotification,
+  DidOpenTextDocumentNotification,
+  DidChangeTextDocumentNotification,
+  DidCloseTextDocumentNotification,
+  ShutdownRequest,
+  ExitNotification,
+  PublishDiagnosticsNotification,
+  DiagnosticSeverity,
+  type InitializeParams,
+  type Diagnostic,
+} from "vscode-languageserver-protocol/node.js";
+import type { ChildProcess } from "node:child_process";
+import { fileUri } from "./util.js";
+
+export interface OtherFileDiagnostics {
+  uri: string;
+  errorCount: number;
+  warningCount: number;
+}
+
+export interface DiagnosticResult {
+  status: "ok" | "timeout" | "unavailable";
+  diagnostics: Diagnostic[];
+  otherFiles: OtherFileDiagnostics[];
+}
+
+export interface LspClient {
+  initialize(workspaceRoot: string): Promise<void>;
+  didOpen(uri: string, languageId: string, content: string): void;
+  didChange(uri: string, content: string): void;
+  didClose(uri: string): void;
+  waitForDiagnostics(uri: string, timeoutMs: number): Promise<DiagnosticResult>;
+  shutdown(): Promise<void>;
+}
+
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+
+function countDiagnostics(diags: Diagnostic[]): { errors: number; warnings: number } {
+  let errors = 0;
+  let warnings = 0;
+  for (const d of diags) {
+    if (d.severity === DiagnosticSeverity.Error) errors++;
+    else if (d.severity === DiagnosticSeverity.Warning) warnings++;
+  }
+  return { errors, warnings };
+}
+
+export function createLspClient(child: ChildProcess): LspClient {
+  if (!child.stdout || !child.stdin) {
+    throw new Error("LSP child process must be spawned with stdio: pipe");
+  }
+
+  const connection = createProtocolConnection(
+    new StreamMessageReader(child.stdout),
+    new StreamMessageWriter(child.stdin),
+  );
+
+  interface DiagnosticEntry {
+    diagnostics: Diagnostic[];
+    generation: number;
+    received: boolean;
+    resolve?: () => void;
+  }
+
+  const diagnosticsMap = new Map<string, DiagnosticEntry>();
+  const documentVersion = new Map<string, number>();
+  const uriGeneration = new Map<string, number>();
+
+  connection.onNotification(PublishDiagnosticsNotification.type, (params) => {
+    const entry = diagnosticsMap.get(params.uri);
+    if (entry) {
+      // only accept diagnostics for the current generation of this URI
+      const currentGen = uriGeneration.get(params.uri) ?? 0;
+      if (entry.generation !== currentGen) return;
+      entry.diagnostics = params.diagnostics;
+      entry.received = true;
+      entry.resolve?.();
+    } else {
+      // cross-file diagnostics for URIs we haven't opened — accept them
+      const gen = uriGeneration.get(params.uri) ?? 0;
+      diagnosticsMap.set(params.uri, { diagnostics: params.diagnostics, generation: gen, received: true });
+    }
+  });
+
+  connection.listen();
+
+  return {
+    async initialize(workspaceRoot: string) {
+      const params: InitializeParams = {
+        processId: child.pid ?? null,
+        rootUri: fileUri(workspaceRoot),
+        capabilities: {
+          textDocument: {
+            synchronization: {
+              dynamicRegistration: false,
+              willSave: false,
+              willSaveWaitUntil: false,
+              didSave: false,
+            },
+            publishDiagnostics: {
+              relatedInformation: false,
+            },
+          },
+        },
+        workspaceFolders: [{ uri: fileUri(workspaceRoot), name: "workspace" }],
+      };
+
+      await connection.sendRequest(InitializeRequest.type, params);
+      connection.sendNotification(InitializedNotification.type, {});
+    },
+
+    didOpen(uri: string, languageId: string, content: string) {
+      const gen = (uriGeneration.get(uri) ?? 0) + 1;
+      uriGeneration.set(uri, gen);
+      documentVersion.set(uri, 1);
+      diagnosticsMap.set(uri, { diagnostics: [], generation: gen, received: false });
+      connection.sendNotification(DidOpenTextDocumentNotification.type, {
+        textDocument: { uri, languageId, version: 1, text: content },
+      });
+    },
+
+    didChange(uri: string, content: string) {
+      const version = (documentVersion.get(uri) ?? 1) + 1;
+      const gen = (uriGeneration.get(uri) ?? 0) + 1;
+      uriGeneration.set(uri, gen);
+      documentVersion.set(uri, version);
+      diagnosticsMap.set(uri, { diagnostics: [], generation: gen, received: false });
+      connection.sendNotification(DidChangeTextDocumentNotification.type, {
+        textDocument: { uri, version },
+        contentChanges: [{ text: content }],
+      });
+    },
+
+    didClose(uri: string) {
+      // bump generation so any in-flight diagnostics for the old open are rejected
+      const gen = (uriGeneration.get(uri) ?? 0) + 1;
+      uriGeneration.set(uri, gen);
+      connection.sendNotification(DidCloseTextDocumentNotification.type, {
+        textDocument: { uri },
+      });
+      diagnosticsMap.delete(uri);
+      documentVersion.delete(uri);
+    },
+
+    async waitForDiagnostics(uri: string, timeoutMs: number): Promise<DiagnosticResult> {
+      const targetGen = uriGeneration.get(uri) ?? 0;
+
+      // snapshot diagnostic counts for all other tracked URIs before the edit settles
+      const preSnapshot = new Map<string, { errors: number; warnings: number }>();
+      for (const [trackedUri, entry] of diagnosticsMap) {
+        if (trackedUri !== uri) {
+          preSnapshot.set(trackedUri, countDiagnostics(entry.diagnostics));
+        }
+      }
+
+      const collectOtherFiles = (): OtherFileDiagnostics[] => {
+        const result: OtherFileDiagnostics[] = [];
+        for (const [trackedUri, entry] of diagnosticsMap) {
+          if (trackedUri === uri) continue;
+          const post = countDiagnostics(entry.diagnostics);
+          const pre = preSnapshot.get(trackedUri) ?? { errors: 0, warnings: 0 };
+          const newErrors = post.errors - pre.errors;
+          const newWarnings = post.warnings - pre.warnings;
+          if (newErrors > 0 || newWarnings > 0) {
+            result.push({ uri: trackedUri, errorCount: newErrors, warningCount: newWarnings });
+          }
+        }
+        return result;
+      };
+
+      return new Promise<DiagnosticResult>((resolve) => {
+        const SETTLE_MS = 50;
+        let settled = false;
+
+        const settle = (status: "ok" | "timeout") => {
+          if (settled) return;
+          settled = true;
+          setTimeout(() => {
+            resolve({
+              status,
+              diagnostics: diagnosticsMap.get(uri)?.diagnostics ?? [],
+              otherFiles: collectOtherFiles(),
+            });
+          }, SETTLE_MS);
+        };
+
+        const timeout = setTimeout(() => {
+          settle("timeout");
+        }, timeoutMs);
+
+        const entry = diagnosticsMap.get(uri) ?? { diagnostics: [], generation: targetGen, received: false };
+        if (entry.received) {
+          clearTimeout(timeout);
+          settle("ok");
+        } else {
+          entry.resolve = () => {
+            clearTimeout(timeout);
+            settle("ok");
+          };
+          diagnosticsMap.set(uri, entry);
+        }
+      });
+    },
+
+    async shutdown() {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await Promise.race([
+          connection.sendRequest(ShutdownRequest.type),
+          new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new Error("shutdown timed out")), SHUTDOWN_TIMEOUT_MS);
+          }),
+        ]);
+        connection.sendNotification(ExitNotification.type);
+      } catch {
+        // timed out or server already exited
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+      connection.dispose();
+    },
+  };
+}

package/src/format.ts

@@ -0,0 +1,43 @@
+import { DiagnosticSeverity } from "vscode-languageserver-protocol";
+import type { DiagnosticResult } from "./client.js";
+
+export function formatDiagnostics(filePath: string, result: DiagnosticResult): string {
+  const relevant = result.diagnostics.filter(
+    (d) => d.severity === DiagnosticSeverity.Error || d.severity === DiagnosticSeverity.Warning,
+  );
+
+  if (relevant.length === 0 && result.status === "ok" && result.otherFiles.length === 0) return "";
+  if (result.status === "unavailable") return "";
+
+  if (relevant.length === 0 && result.status === "ok" && result.otherFiles.length > 0) {
+    return `\n⚠ LSP diagnostics for ${filePath}: no issues${otherFilesFooter(result)}`;
+  }
+
+  const lines = relevant.map((d) => {
+    const severity = d.severity === DiagnosticSeverity.Error ? "error" : "warning";
+    const line = d.range.start.line + 1;
+    const col = d.range.start.character + 1;
+    const source = d.source ? `[${d.source}] ` : "";
+    return `  ${severity} ${line}:${col} ${source}${d.message}`;
+  });
+
+  const errorCount = relevant.filter((d) => d.severity === DiagnosticSeverity.Error).length;
+  const warnCount = relevant.length - errorCount;
+
+  const summary = [
+    errorCount > 0 ? `${errorCount} error${errorCount > 1 ? "s" : ""}` : "",
+    warnCount > 0 ? `${warnCount} warning${warnCount > 1 ? "s" : ""}` : "",
+    result.status === "timeout" ? "timed out, may be incomplete" : "",
+  ]
+    .filter(Boolean)
+    .join(", ");
+
+  return `\n⚠ LSP diagnostics for ${filePath} (${summary}):\n${lines.join("\n")}${otherFilesFooter(result)}`;
+}
+
+function otherFilesFooter(result: DiagnosticResult): string {
+  if (result.otherFiles.length === 0) return "";
+  const totalDiags = result.otherFiles.reduce((sum, f) => sum + f.errorCount + f.warningCount, 0);
+  const fileCount = result.otherFiles.length;
+  return `\n  + ${totalDiags} diagnostic${totalDiags !== 1 ? "s" : ""} in ${fileCount} other file${fileCount !== 1 ? "s" : ""}`;
+}

package/src/languages.ts

@@ -0,0 +1,52 @@
+export interface LanguageServerConfig {
+  id: string;
+  extensions: string[];
+  command: string;
+  args: string[];
+  rootPatterns: string[];
+}
+
+export const languages: LanguageServerConfig[] = [
+  {
+    id: "go",
+    extensions: [".go"],
+    command: "gopls",
+    args: ["serve"],
+    rootPatterns: ["go.mod"],
+  },
+  {
+    id: "rust",
+    extensions: [".rs"],
+    command: "rust-analyzer",
+    args: [],
+    rootPatterns: ["Cargo.toml"],
+  },
+  {
+    id: "typescript",
+    extensions: [".ts", ".tsx", ".js", ".jsx"],
+    command: "typescript-language-server",
+    args: ["--stdio"],
+    rootPatterns: ["tsconfig.json", "package.json"],
+  },
+];
+
+export function languageForFile(path: string): LanguageServerConfig | undefined {
+  const lower = path.toLowerCase();
+  return languages.find((lang) => lang.extensions.some((ext) => lower.endsWith(ext)));
+}
+
+export function checkExtensionOverlaps(): string[] {
+  const warnings: string[] = [];
+  const seen = new Map<string, string>();
+  for (const lang of languages) {
+    for (const ext of lang.extensions) {
+      const existing = seen.get(ext);
+      if (existing) {
+        warnings.push(`extension "${ext}" is claimed by both "${existing}" and "${lang.id}" — "${existing}" wins`);
+      } else {
+        seen.set(ext, lang.id);
+      }
+    }
+  }
+  return warnings;
+}

package/src/server-manager.ts

@@ -0,0 +1,240 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { which, fileUri, findWorkspaceRoot } from "./util.js";
+import { createLspClient, type LspClient, type DiagnosticResult } from "./client.js";
+import type { LanguageServerConfig } from "./languages.js";
+import { readFile } from "node:fs/promises";
+
+interface ManagedServer {
+  config: LanguageServerConfig;
+  serverKey: string;
+  root: string;
+  process: ChildProcess;
+  client: LspClient;
+  openDocuments: Map<string, number>;
+  idleTimer: ReturnType<typeof setTimeout> | null;
+  startTime: number;
+  lastActivity: number;
+  editQueue: Promise<DiagnosticResult>;
+}
+
+export interface ServerManager {
+  handleEdit(filePath: string, config: LanguageServerConfig, cwd: string): Promise<DiagnosticResult>;
+  status(): ServerStatus[];
+  shutdownAll(): Promise<void>;
+}
+
+export interface ServerStatus {
+  id: string;
+  root: string;
+  pid: number;
+  uptime: number;
+  openDocuments: number;
+  lastActivity: number;
+}
+
+const IDLE_TIMEOUT_MS = 240_000;
+const DIAGNOSTIC_TIMEOUT_MS = 3_000;
+const INIT_TIMEOUT_MS = 10_000;
+const DOCUMENT_IDLE_MS = 120_000;
+const SWEEP_INTERVAL_MS = 60_000;
+
+export function createServerManager(): ServerManager {
+  const servers = new Map<string, ManagedServer>();
+  const pending = new Map<string, Promise<ManagedServer | null>>();
+  const disabledBinaries = new Set<string>();
+  const failedRoots = new Set<string>();
+  let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  function startSweepTimer() {
+    if (sweepTimer) return;
+    sweepTimer = setInterval(() => {
+      const now = Date.now();
+      for (const server of servers.values()) {
+        const stale = [...server.openDocuments.entries()]
+          .filter(([, lastActive]) => now - lastActive > DOCUMENT_IDLE_MS);
+        for (const [docUri] of stale) {
+          server.client.didClose(docUri);
+          server.openDocuments.delete(docUri);
+        }
+      }
+    }, SWEEP_INTERVAL_MS);
+    sweepTimer.unref();
+  }
+
+  function stopSweepTimer() {
+    if (sweepTimer) {
+      clearInterval(sweepTimer);
+      sweepTimer = null;
+    }
+  }
+
+  function resetIdleTimer(server: ManagedServer) {
+    if (server.idleTimer) clearTimeout(server.idleTimer);
+    server.lastActivity = Date.now();
+    server.idleTimer = setTimeout(() => shutdownServer(server), IDLE_TIMEOUT_MS);
+  }
+
+  async function killProcess(proc: ChildProcess): Promise<void> {
+    if (proc.exitCode !== null) return;
+    proc.kill("SIGTERM");
+    await new Promise<void>((resolve) => {
+      if (proc.exitCode !== null) {
+        resolve();
+        return;
+      }
+      const killTimer = setTimeout(() => {
+        proc.kill("SIGKILL");
+      }, 2000);
+      proc.once("exit", () => {
+        clearTimeout(killTimer);
+        resolve();
+      });
+    });
+  }
+
+  async function shutdownServer(server: ManagedServer) {
+    if (server.idleTimer) clearTimeout(server.idleTimer);
+    await server.client.shutdown();
+    await killProcess(server.process);
+    if (servers.get(server.serverKey) === server) {
+      servers.delete(server.serverKey);
+    }
+    if (servers.size === 0) stopSweepTimer();
+  }
+
+  async function spawnServer(config: LanguageServerConfig, root: string, serverKey: string): Promise<ManagedServer | null> {
+    if (disabledBinaries.has(config.id)) return null;
+    if (failedRoots.has(serverKey)) return null;
+
+    const binaryPath = await which(config.command);
+    if (!binaryPath) {
+      console.error(`[pi-lsp-lite:${config.id}] ${config.command} not found on PATH, disabling ${config.id}`);
+      disabledBinaries.add(config.id);
+      return null;
+    }
+
+    const child = spawn(binaryPath, config.args, {
+      cwd: root,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      console.error(`[pi-lsp-lite:${config.id}:${root}]`, chunk.toString().trimEnd());
+    });
+
+    child.on("error", (err) => {
+      console.error(`[pi-lsp-lite:${config.id}:${root}] process error:`, err);
+    });
+
+    const client = createLspClient(child);
+
+    let initTimer: ReturnType<typeof setTimeout>;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      initTimer = setTimeout(() => reject(new Error("LSP initialize timed out")), INIT_TIMEOUT_MS);
+    });
+
+    try {
+      await Promise.race([client.initialize(root), timeoutPromise]);
+      clearTimeout(initTimer!);
+    } catch (err) {
+      clearTimeout(initTimer!);
+      console.error(`[pi-lsp-lite:${config.id}:${root}] failed to initialize:`, err);
+      await killProcess(child);
+      client.shutdown().catch(() => {});
+      failedRoots.add(serverKey);
+      return null;
+    }
+
+    const now = Date.now();
+    const server: ManagedServer = {
+      config,
+      serverKey,
+      root,
+      process: child,
+      client,
+      openDocuments: new Map(),
+      idleTimer: null,
+      startTime: now,
+      lastActivity: now,
+      editQueue: Promise.resolve({ status: "ok", diagnostics: [], otherFiles: [] }),
+    };
+
+    child.on("exit", () => {
+      if (server.idleTimer) clearTimeout(server.idleTimer);
+      if (servers.get(serverKey) === server) {
+        servers.delete(serverKey);
+      }
+      if (servers.size === 0) stopSweepTimer();
+    });
+
+    resetIdleTimer(server);
+    servers.set(serverKey, server);
+    startSweepTimer();
+    return server;
+  }
+
+  async function ensureServer(config: LanguageServerConfig, root: string): Promise<ManagedServer | null> {
+    const serverKey = `${config.id}:${root}`;
+    const existing = servers.get(serverKey);
+    if (existing) return existing;
+
+    if (disabledBinaries.has(config.id)) return null;
+    if (failedRoots.has(serverKey)) return null;
+
+    const inflight = pending.get(serverKey);
+    if (inflight) return inflight;
+
+    const promise = spawnServer(config, root, serverKey).finally(() => pending.delete(serverKey));
+    pending.set(serverKey, promise);
+    return promise;
+  }
+
+  async function doEdit(server: ManagedServer, filePath: string): Promise<DiagnosticResult> {
+    resetIdleTimer(server);
+
+    const uri = fileUri(filePath);
+    const content = await readFile(filePath, "utf-8");
+
+    if (server.openDocuments.has(uri)) {
+      server.client.didChange(uri, content);
+    } else {
+      server.client.didOpen(uri, server.config.id, content);
+    }
+    server.openDocuments.set(uri, Date.now());
+
+    return server.client.waitForDiagnostics(uri, DIAGNOSTIC_TIMEOUT_MS);
+  }
+
+  return {
+    async handleEdit(filePath: string, config: LanguageServerConfig, cwd: string): Promise<DiagnosticResult> {
+      const root = await findWorkspaceRoot(filePath, config.rootPatterns, cwd);
+      const server = await ensureServer(config, root);
+      if (!server) return { status: "unavailable" as const, diagnostics: [], otherFiles: [] };
+
+      // serialize edits per server to avoid concurrent waitForDiagnostics races
+      const result = server.editQueue.then(
+        () => doEdit(server, filePath),
+        () => doEdit(server, filePath),
+      );
+      server.editQueue = result;
+      return result;
+    },
+
+    status(): ServerStatus[] {
+      return Array.from(servers.values()).map((s) => ({
+        id: s.config.id,
+        root: s.root,
+        pid: s.process.pid ?? 0,
+        uptime: Date.now() - s.startTime,
+        openDocuments: s.openDocuments.size,
+        lastActivity: s.lastActivity,
+      }));
+    },
+
+    async shutdownAll() {
+      stopSweepTimer();
+      const shutdowns = Array.from(servers.values()).map((s) => shutdownServer(s));
+      await Promise.allSettled(shutdowns);
+    },
+  };
+}

package/src/util.ts

@@ -0,0 +1,44 @@
+import { access, constants } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function fileUri(absolutePath: string): string {
+  return pathToFileURL(absolutePath).href;
+}
+
+export async function which(command: string): Promise<string | null> {
+  if (command.includes("/")) {
+    try {
+      await access(command, constants.X_OK);
+      return command;
+    } catch {
+      return null;
+    }
+  }
+  const pathDirs = (process.env.PATH ?? "").split(":");
+  for (const dir of pathDirs) {
+    const candidate = join(dir, command);
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {}
+  }
+  return null;
+}
+
+export async function findWorkspaceRoot(filePath: string, rootPatterns: string[], cwd: string): Promise<string> {
+  let dir = dirname(filePath);
+  while (true) {
+    for (const pattern of rootPatterns) {
+      try {
+        await access(join(dir, pattern));
+        return dir;
+      } catch {}
+    }
+    if (dir === cwd) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cwd;
+}