one-code-extension 0.1.4 → 0.3.0

package/extensions/lsp/index.ts

@@ -1,125 +1,299 @@
 /**
- * lsp extension — Claude Code's post-edit diagnostics.
+ * lsp extension — language-server diagnostics, the way Claude Code surfaces them.
  *
- * Two behaviors, no more:
- *  1. After a successful `edit` or `write`, error diagnostics for that file are
- *     appended to the tool result, so the model immediately sees what it broke.
- *  2. An `lsp_diagnostics` tool (deferred behind `tool_search`) for asking about
- *     a file on demand.
+ * Three behaviors:
+ *  1. A session-wide watcher (watcher.ts): new diagnostics — cross-file, all
+ *     severities, deduplicated against what was already delivered — ride the
+ *     tool result of the round that surfaced them as a raw `<new-diagnostics>`
+ *     block (a reminder-queue one-shot, pinned to the trailing tool result
+ *     after the `<total_tokens>` line — the exact place a Claude Code session
+ *     shows them), or the message that opens the next run when they arrived
+ *     while idle (`agent_start`, so a notification-opened run gets them too).
+ *     Until 2026-09-05 they went out as a custom steer message of their own
+ *     (a separate user turn on the wire). Editing a file clears its
+ *     delivered-set so fixed-then-reintroduced issues resurface.
+ *  2. Plugin-provided servers (plugin-servers.ts): an enabled plugin's
+ *     `.lsp.json` / manifest `lspServers` adds servers routed by file
+ *     extension, taking precedence over the built-in table — installing the
+ *     plugin is explicit intent. Built-in servers keep root-marker detection;
+ *     plugin servers root at `workspaceFolder ?? cwd`.
+ *  3. An `lsp_diagnostics` tool (deferred behind `tool_search`) for asking
+ *     about a file on demand.
  *
- * Claude Code has no other LSP tools; navigation goes through grep/find. Adding
- * hover or definition later is a small `client.request(...)` call each, if the
- * need appears.
+ * Claude Code has no other LSP tools; navigation goes through grep/find.
  */
 
-import { relative } from "node:path";
+import { mkdirSync } from "node:fs";
+import { extname, relative } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
-import { ccToolRenderers } from "../lib/tui-render.ts";
-import { LspClient } from "./client.ts";
-import { filterDiagnostics, formatDiagnostics, type SeverityFilter } from "./format.ts";
+import { defaultDiscoverRoots, discoverPlugins, pluginResources } from "../lib/plugins.ts";
+import { REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
+import { ccToolRenderers, cutPlainText } from "../lib/tui-render.ts";
+import { LspClient, type LspClientOptions, pathToUri } from "./client.ts";
+import { filterDiagnostics, formatDiagnostics, type LspDiagnostic, type SeverityFilter } from "./format.ts";
+import { describeStartFailure, INSTALL_HINTS } from "./install-hints.ts";
+import { withKeepAlive } from "./keep-alive.ts";
+import {
+	pluginLanguageId,
+	readManifestLspServers,
+	type ResolvedPluginServer,
+	resolveExtensionRouting,
+	resolvePluginServers,
+} from "./plugin-servers.ts";
 import { findProjectRoot, serverForPath, typescriptPreflight } from "./servers.ts";
+import { computeDelta, DeliveredTracker, fingerprintDiagnostic, formatNewDiagnostics, markDelivered } from "./watcher.ts";
 
-/** Only errors are pushed unasked; warnings would be noise on every edit. */
-const AUTO_APPEND_LIMIT = 10;
-
-/** The (match, project root, client-map key) triple every entry point needs; undefined when the path has no configured server. */
-function resolveServer(
-	path: string,
-	cwd: string,
-): { match: NonNullable<ReturnType<typeof serverForPath>>; root: string; key: string } | undefined {
-	const match = serverForPath(path);
-	if (!match) return undefined;
-	const root = findProjectRoot(path, match.config.rootMarkers, cwd);
-	const key = `${match.languageId}:${root}`;
-	return { match, root, key };
+/** Everything needed to spawn/reuse the server responsible for a path. */
+interface ResolvedTarget {
+	key: string;
+	root: string;
+	languageId: string;
+	command: string;
+	args: string[];
+	options: LspClientOptions;
+	/** Set when a plugin config (not the built-in table) claimed the extension. */
+	plugin?: ResolvedPluginServer;
+}
+
+interface PluginRouting {
+	byExtension: Map<string, ResolvedPluginServer>;
+	collisions: string[];
+	diagnostics: string[];
 }
 
 export default function lspExtension(pi: ExtensionAPI) {
 	const clients = new Map<string, LspClient>();
 	const startFailures = new Map<string, string>();
 	const warned = new Set<string>();
+	const tracker = new DeliveredTracker();
 
-	const clientFor = async (path: string, cwd: string): Promise<LspClient | undefined> => {
-		const resolved = resolveServer(path, cwd);
-		if (!resolved) return undefined;
-		const { match, root, key } = resolved;
+	// Built lazily on the first file touched — never at session_start
+	// (findings §15: serial session_start work delays the prompt).
+	let routing: PluginRouting | undefined;
+	const pluginRouting = (cwd: string): PluginRouting => (routing ??= buildPluginRouting(cwd));
 
-		const failure = startFailures.get(key);
-		if (failure) return undefined;
+	function buildPluginRouting(cwd: string): PluginRouting {
+		const discovered = discoverPlugins(defaultDiscoverRoots(getAgentDir(), cwd));
+		const diagnostics: string[] = [];
+		const servers: ResolvedPluginServer[] = [];
+		for (const plugin of discovered.enabledPlugins) {
+			const { lspConfig } = pluginResources(plugin);
+			const manifestServers = readManifestLspServers(plugin.path);
+			if (!lspConfig && manifestServers === undefined) continue;
+			const resolved = resolvePluginServers(
+				{ name: plugin.name, path: plugin.path, dataRoot: plugin.dataRoot },
+				lspConfig,
+				manifestServers,
+				process.env,
+			);
+			servers.push(...resolved.servers);
+			diagnostics.push(...resolved.diagnostics);
+		}
+		const routed = resolveExtensionRouting(servers);
+		return { byExtension: routed.byExtension, collisions: routed.collisions, diagnostics };
+	}
+
+	const resolveTarget = (path: string, cwd: string): ResolvedTarget | undefined => {
+		const pluginServer = pluginRouting(cwd).byExtension.get(extname(path).toLowerCase());
+		if (pluginServer) {
+			return {
+				key: pluginServer.key,
+				root: pluginServer.workspaceFolder ?? cwd,
+				languageId: pluginLanguageId(pluginServer, path),
+				command: pluginServer.command,
+				args: pluginServer.args,
+				options: {
+					env: pluginServer.env,
+					initializationOptions: pluginServer.initializationOptions,
+					settings: pluginServer.settings,
+					startupTimeoutMs: pluginServer.startupTimeoutMs,
+				},
+				plugin: pluginServer,
+			};
+		}
+		const match = serverForPath(path);
+		if (!match) return undefined;
+		const root = findProjectRoot(path, match.config.rootMarkers, cwd);
+		return {
+			key: `${match.languageId}:${root}`,
+			root,
+			languageId: match.languageId,
+			command: match.config.command,
+			args: match.config.args,
+			options: {},
+		};
+	};
+
+	/** Servers may be respawned this many times after a mid-session crash; beyond that the language is off for the session. */
+	const MAX_RESPAWNS = 2;
+	const respawns = new Map<string, number>();
+
+	const clientFor = async (target: ResolvedTarget): Promise<LspClient | undefined> => {
+		const { key } = target;
+		if (startFailures.has(key)) return undefined;
 
 		const existing = clients.get(key);
 		if (existing?.isRunning) return existing;
 		if (existing) {
-			// Crashed mid-session. Record why so downstream reports the real cause
-			// (a server that was running and died) instead of falling through to
+			// Crashed mid-session. Respawn with a short backoff, up to MAX_RESPAWNS
+			// times; after that record why so downstream reports the real cause (a
+			// server that was running and died) instead of falling through to
 			// "install <command>" advice for an already-installed server — and so
-			// the one-time post-edit warning still fires. Don't respawn in a loop.
-			startFailures.set(key, existing.error ?? "language server stopped unexpectedly");
-			return undefined;
+			// the one-time post-edit warning still fires (review T10).
+			const count = (respawns.get(key) ?? 0) + 1;
+			respawns.set(key, count);
+			if (count > MAX_RESPAWNS) {
+				startFailures.set(key, `${existing.error ?? "language server stopped unexpectedly"} (gave up after ${MAX_RESPAWNS} restarts)`);
+				return undefined;
+			}
+			clients.delete(key);
+			await new Promise((resolve) => setTimeout(resolve, 500 * count));
 		}
 
-		if (match.languageId.startsWith("typescript") || match.languageId.startsWith("javascript")) {
-			const problem = typescriptPreflight(root);
+		// Keyed on the command being spawned, not on where the config came from —
+		// a plugin configuring typescript-language-server hits the same TS7 trap.
+		if (target.command === "typescript-language-server") {
+			const problem = typescriptPreflight(target.root);
 			if (problem) {
 				startFailures.set(key, problem);
 				return undefined;
 			}
 		}
 
-		const client = new LspClient(match.languageId, match.config, root);
+		if (target.plugin) mkdirSync(target.plugin.dataDir, { recursive: true });
+
+		const client = new LspClient({ command: target.command, args: target.args }, target.root, target.options);
 		clients.set(key, client);
 		try {
 			await client.start();
 			return client;
 		} catch (error) {
-			startFailures.set(key, client.error ?? (error as Error).message);
+			// A missing binary (spawn ENOENT) is rewritten into install guidance
+			// here, once, so the warning, /lsp, and the tool all show it.
+			const raw = client.error ?? (error as Error).message;
+			startFailures.set(key, describeStartFailure(raw, target.command, target.plugin?.pluginName));
 			return undefined;
 		}
 	};
 
-	/** One-time notice per root so a missing server doesn't degrade silently. */
-	const reportFailureOnce = (path: string, cwd: string, notify: (message: string) => void) => {
-		const resolved = resolveServer(path, cwd);
-		if (!resolved) return;
-		const { match, key } = resolved;
-		const failure = startFailures.get(key);
-		if (failure && !warned.has(key)) {
-			warned.add(key);
+	/** One-time notice per server key so a missing server doesn't degrade silently. */
+	const reportFailureOnce = (target: ResolvedTarget, notify: (message: string) => void) => {
+		const failure = startFailures.get(target.key);
+		if (failure && !warned.has(target.key)) {
+			warned.add(target.key);
 			// Server errors run to paragraphs; the transcript gets one line and
-			// /lsp keeps the full status.
+			// /lsp keeps the full status. The cap leaves room for a full
+			// missing-binary line including its install command.
 			const brief = failure.split("\n")[0].replace(/\s+/g, " ").trim();
-			const capped = brief.length > 100 ? `${brief.slice(0, 99)}…` : brief;
-			notify(`LSP unavailable for ${match.languageId}: ${capped} (/lsp for status)`);
+			const capped = cutPlainText(brief, 160);
+			notify(`LSP unavailable for ${target.languageId}: ${capped} (/lsp for status)`);
 		}
 	};
 
+	/** One-time notice when plugin LSP configs were invalid or collided. */
+	const reportRoutingIssuesOnce = (ctx: ExtensionContext) => {
+		const { collisions, diagnostics } = pluginRouting(ctx.cwd);
+		if ((collisions.length === 0 && diagnostics.length === 0) || warned.has("plugin:routing")) return;
+		warned.add("plugin:routing");
+		if (!ctx.hasUI) return;
+		const lines = [...diagnostics, ...collisions].slice(0, 4);
+		ctx.ui.notify(`Plugin LSP config issues (/lsp for the full list):\n${lines.join("\n")}`, "warning");
+	};
+
+	/** All servers' current diagnostics, merged per document uri. */
+	const mergedDiagnostics = (): Map<string, LspDiagnostic[]> => {
+		const merged = new Map<string, LspDiagnostic[]>();
+		for (const client of clients.values()) {
+			for (const [uri, list] of client.allDiagnostics()) {
+				const existing = merged.get(uri);
+				merged.set(uri, existing ? [...existing, ...list] : list);
+			}
+		}
+		return merged;
+	};
+
+	// tool_result fires on EVERY tool call; re-fingerprinting all delivered
+	// diagnostics each round is pure waste when nothing republished. -1 forces
+	// a scan (used after clear-on-edit, where cached diagnostics become
+	// deliverable again without a new publish).
+	let lastPublishTally = 0;
+	const forceDeltaScan = () => {
+		lastPublishTally = -1;
+	};
+
+	/** Format the pending delta and commit it as delivered; undefined when clean. */
+	const takePendingDelta = (cwd: string): string | undefined => {
+		if (clients.size === 0) return undefined;
+		const tally = [...clients.values()].reduce((sum, client) => sum + client.publishCount, 0);
+		if (tally === lastPublishTally) return undefined;
+		lastPublishTally = tally;
+		const delta = computeDelta(mergedDiagnostics(), tracker);
+		const text = formatNewDiagnostics(delta, cwd);
+		if (!text) return undefined;
+		markDelivered(delta, tracker);
+		return text;
+	};
+
+	/**
+	 * Queue the block where the model reads next. Raw (no `<system-reminder>`
+	 * frame, as in Claude Code) and last-append: from a `tool_result` hook this
+	 * extension runs after system-reminder's, so the one-shot is pending at the
+	 * next `context` and pinned to the trailing tool result (process memory,
+	 * same mechanism as the file-tracker's per-round report); from `agent_start`
+	 * it pins to the message that opened the run.
+	 */
+	const queueNewDiagnostics = (text: string) => {
+		pi.events.emit(REMINDER_CHANNEL, { text, placement: "last-append", raw: true } satisfies ReminderPayload);
+	};
+
 	pi.on("tool_result", async (event, ctx) => {
-		if (event.isError) return;
-		if (event.toolName !== "edit" && event.toolName !== "write") return;
-
-		const path = (event.input as { path?: unknown }).path;
-		if (typeof path !== "string") return;
-
-		const client = await clientFor(path, ctx.cwd);
-		if (!client) {
-			reportFailureOnce(path, ctx.cwd, (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "warning");
-			});
-			return;
+		// An edit/write is the one place a fresh publish can be usefully provoked:
+		// sync the file, await the server's next publish, and reset the file's
+		// delivered-set so a reintroduced issue resurfaces.
+		if (!event.isError && (event.toolName === "edit" || event.toolName === "write")) {
+			const path = (event.input as { path?: unknown }).path;
+			if (typeof path === "string") {
+				const target = resolveTarget(path, ctx.cwd);
+				reportRoutingIssuesOnce(ctx);
+				if (target) {
+					// withKeepAlive: in a one-shot run this await can be the only
+					// pending work, and everything the client holds is unref'd —
+					// without a ref the loop drains and pi exits mid-tool (keep-alive.ts).
+					await withKeepAlive(async () => {
+						const client = await clientFor(target);
+						if (client) {
+							tracker.clear(pathToUri(path));
+							forceDeltaScan();
+							await client.getDiagnostics(path, target.languageId);
+						} else {
+							reportFailureOnce(target, (message) => {
+								if (ctx.hasUI) ctx.ui.notify(message, "warning");
+							});
+						}
+					});
+				}
+			}
 		}
 
-		const errors = filterDiagnostics(await client.getDiagnostics(path), "error");
-		if (errors.length === 0) return;
+		// Every tool round drains whatever is newly known — including dependents
+		// of an earlier edit whose diagnostics arrived while other tools ran.
+		// Diagnostics never wake an idle agent: a one-shot waits for the next
+		// request, whoever opens it.
+		const text = takePendingDelta(ctx.cwd);
+		if (text) queueNewDiagnostics(text);
+	});
 
-		const relPath = relative(ctx.cwd, path) || path;
-		const summary = formatDiagnostics(relPath, errors, AUTO_APPEND_LIMIT);
-		const existing = event.content ?? [];
-		return {
-			content: [...existing, { type: "text", text: `\n<diagnostics>\n${summary}\n</diagnostics>` }],
-		};
+	// Diagnostics that finished publishing while the agent was idle (session
+	// resume, a server still typechecking after the turn ended) ride the message
+	// that opens the next run. `agent_start`, not `before_agent_start`: pi emits
+	// the latter only from `prompt()`, so a run a harness notification opened
+	// (a `/loop` tick, an agent report) never fired it (STEERING-REVIEW H1).
+	pi.on("agent_start", (_event, ctx) => {
+		const text = takePendingDelta(ctx.cwd);
+		if (text) queueNewDiagnostics(text);
 	});
 
 	pi.registerTool({
@@ -127,7 +301,7 @@ export default function lspExtension(pi: ExtensionAPI) {
 		label: "Diagnostics",
 		...ccToolRenderers("Diagnostics"),
 		description:
-			"Ask the language server for diagnostics (type errors, warnings) on a file. Reflects the file's current contents. Supported: TypeScript/JavaScript, Python, Go, Rust, Java — when that language's server is installed.",
+			"Ask the language server for diagnostics (type errors, warnings) on a file. Reflects the file's current contents. Supported: TypeScript/JavaScript, Python, Go, Rust, Java — plus any language a plugin's .lsp.json configures — when that language's server is installed.",
 		parameters: Type.Object({
 			path: Type.String({ description: "File to analyse (absolute or workspace-relative)" }),
 			severity: Type.Optional(
@@ -136,19 +310,27 @@ export default function lspExtension(pi: ExtensionAPI) {
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const path = params.path.startsWith("/") ? params.path : `${ctx.cwd}/${params.path}`;
-			const client = await clientFor(path, ctx.cwd);
-			if (!client) {
-				const resolved = resolveServer(path, ctx.cwd);
-				const match = resolved?.match;
-				const failure = resolved ? startFailures.get(resolved.key) : undefined;
+			const target = resolveTarget(path, ctx.cwd);
+			// One keep-alive spans both awaits (same pattern as the tool_result hook).
+			const fetched = target
+				? await withKeepAlive(async () => {
+						const client = await clientFor(target);
+						return client && { all: await client.getDiagnostics(path, target.languageId) };
+					})
+				: undefined;
+			if (!target || !fetched) {
+				const failure = target ? startFailures.get(target.key) : undefined;
 				return {
 					content: [
 						{
 							type: "text",
 							text:
 								failure ??
-								(match
-									? `No language server available for ${match.languageId}. Install ${match.config.command}.`
+								(target
+									? `No language server available for ${target.languageId}. ` +
+										(INSTALL_HINTS[target.command]
+											? `Install it with: ${INSTALL_HINTS[target.command]}`
+											: `Install ${target.command}.`)
 									: `No language server is configured for this file type.`),
 						},
 					],
@@ -156,16 +338,19 @@ export default function lspExtension(pi: ExtensionAPI) {
 					// A language was recognised but its server is unavailable/failed —
 					// that is an error, not a clean "no diagnostics". Only a genuinely
 					// unsupported filetype (no match) is a non-error outcome.
-					isError: Boolean(match),
+					isError: Boolean(target),
 				};
 			}
 
-			const all = await client.getDiagnostics(path);
+			const { all } = fetched;
+			// The model sees these in the tool result now; don't re-deliver them
+			// as <new-diagnostics> on the next round.
+			tracker.markDelivered(pathToUri(path), all.map(fingerprintDiagnostic));
 			const filtered = filterDiagnostics(all, (params.severity ?? "all") as SeverityFilter);
 			const relPath = relative(ctx.cwd, path) || path;
 			return {
 				content: [{ type: "text", text: formatDiagnostics(relPath, filtered) }],
-				details: { count: filtered.length, languageId: client.languageId },
+				details: { count: filtered.length, languageId: target.languageId },
 			};
 		},
 	});
@@ -177,6 +362,10 @@ export default function lspExtension(pi: ExtensionAPI) {
 				([key, client]) => `${client.isRunning ? "running" : "stopped"} ${key} (${client.diagnosticsCount} diagnostics)`,
 			);
 			for (const [key, failure] of startFailures) lines.push(`failed  ${key}: ${failure}`);
+			if (routing) {
+				for (const line of routing.diagnostics) lines.push(`config  ${line}`);
+				for (const line of routing.collisions) lines.push(`routing ${line}`);
+			}
 			ctx.ui.notify(lines.length ? lines.join("\n") : "No language servers started.", "info");
 		},
 	});

package/extensions/lsp/install-hints.ts

@@ -0,0 +1,43 @@
+/**
+ * Turn a language-server spawn failure into an actionable message.
+ *
+ * A missing binary (spawn ENOENT) is the common, fixable case: the built-in
+ * table assumes its servers are on PATH, and Claude Code LSP plugins ship
+ * config only — never the binary (findings §18.3). The raw
+ * "spawn pyright-langserver ENOENT" tells the user nothing about what to do,
+ * so it is rewritten here with the install command when we know it, and with
+ * PATH/plugin guidance when we don't. Every other failure passes through
+ * unchanged. Enrichment happens once, where the failure is recorded, so the
+ * one-time warning, /lsp, and the lsp_diagnostics tool all show the same text.
+ */
+
+/** Install commands for the built-in table's servers (and their npm siblings). */
+export const INSTALL_HINTS: Record<string, string> = {
+	"typescript-language-server": "npm install -g typescript-language-server typescript",
+	"pyright-langserver": "npm install -g pyright",
+	gopls: "go install golang.org/x/tools/gopls@latest",
+	"rust-analyzer": "rustup component add rust-analyzer",
+	jdtls: "brew install jdtls",
+};
+
+/** True when the failure is a spawn ENOENT — the binary itself is absent. */
+export function isMissingBinary(failure: string): boolean {
+	return /\bENOENT\b/.test(failure);
+}
+
+/**
+ * Rewrite a missing-binary failure into install guidance; return anything
+ * else verbatim. `pluginName` is set when a plugin's config (not the built-in
+ * table) named the command.
+ */
+export function describeStartFailure(rawFailure: string, command: string, pluginName?: string): string {
+	if (!isMissingBinary(rawFailure)) return rawFailure;
+	const from = pluginName ? ` (configured by the ${pluginName} plugin)` : "";
+	const hint = INSTALL_HINTS[command];
+	if (hint) return `${command} is not installed${from}. Install it with: ${hint}`;
+	if (command.startsWith("/")) {
+		return `${command} does not exist${from}. ${pluginName ? "Check the plugin's installation." : "Check the configured path."}`;
+	}
+	const docs = pluginName ? " (the plugin's documentation should say how)" : "";
+	return `${command} is not installed${from}. Install it and make sure it is on your PATH${docs}.`;
+}

package/extensions/lsp/keep-alive.ts

@@ -0,0 +1,19 @@
+/**
+ * Hold the event loop open while language-server work is in flight. LspClient
+ * unrefs its child process, stdio pipes, and timeout timers (so a finished
+ * one-shot `pi -p` run can exit without waiting on an idle server); the flip
+ * side is that when an await on the LS is the ONLY pending work — exactly the
+ * case while a tool executes in a one-shot run — node's loop drains and the
+ * process exits 0 mid-await, silently ending the run right after
+ * tool_execution_start. Wrap each outermost LS await in this; keeping the ref
+ * at the call sites (not inside the client) preserves drain-on-idle for
+ * everything not actively awaited. docs/one-shot-lsp-event-loop-drain.md.
+ */
+export async function withKeepAlive<T>(work: () => Promise<T>): Promise<T> {
+	const keepAlive = setInterval(() => {}, 1_000);
+	try {
+		return await work();
+	} finally {
+		clearInterval(keepAlive);
+	}
+}