@workweave/router 0.2.10 → 0.2.11

package/pi-router/src/lsp-format.ts

@@ -0,0 +1,230 @@
+/**
+ * LSP result shapes to the text the model reads.
+ *
+ * Pure: the only filesystem touch (a source line for grep-style context) is an
+ * injected reader. Empty results are friendly text rather than errors, matching
+ * pi's own grep tool ("No matches found") — a model that reads "not found"
+ * moves on, a model that reads an error retries.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fromLspPosition, uriToPath, type LspPosition } from "./lsp-protocol.js";
+
+const MAX_LINE_CHARS = 500;
+const MAX_HOVER_CHARS = 8000;
+const MAX_SYMBOLS = 200;
+const MAX_DIAGNOSTICS = 50;
+
+export interface LspRange {
+	start: LspPosition;
+	end: LspPosition;
+}
+
+export interface LspLocation {
+	uri: string;
+	range: LspRange;
+}
+
+export interface LspLocationLink {
+	targetUri: string;
+	targetRange: LspRange;
+	targetSelectionRange?: LspRange;
+}
+
+export interface NormalizedLocation {
+	path: string;
+	line: number;
+	column: number;
+}
+
+export interface LspDiagnostic {
+	range: LspRange;
+	severity?: number;
+	code?: string | number;
+	source?: string;
+	message: string;
+}
+
+interface LspDocumentSymbol {
+	name: string;
+	kind: number;
+	detail?: string;
+	range?: LspRange;
+	selectionRange?: LspRange;
+	children?: LspDocumentSymbol[];
+}
+
+interface LspSymbolInformation {
+	name: string;
+	kind: number;
+	containerName?: string;
+	location: LspLocation;
+}
+
+/** LSP 3.17 SymbolKind, 1-based. */
+const SYMBOL_KINDS = [
+	"File", "Module", "Namespace", "Package", "Class", "Method", "Property", "Field", "Constructor",
+	"Enum", "Interface", "Function", "Variable", "Constant", "String", "Number", "Boolean", "Array",
+	"Object", "Key", "Null", "EnumMember", "Struct", "Event", "Operator", "TypeParameter",
+];
+
+const SEVERITY_NAMES = ["error", "warning", "info", "hint"];
+
+export type LineReader = (filePath: string, line: number) => string | undefined;
+
+/** Memoized per call: a references result routinely hits the same file dozens of times. */
+export function createLineReader(readFile: (p: string) => string = (p) => fs.readFileSync(p, "utf8")): LineReader {
+	const cache = new Map<string, string[] | undefined>();
+	return (filePath, line) => {
+		if (!cache.has(filePath)) {
+			try {
+				cache.set(filePath, readFile(filePath).split(/\r?\n/));
+			} catch {
+				cache.set(filePath, undefined);
+			}
+		}
+		return cache.get(filePath)?.[line - 1];
+	};
+}
+
+export function displayPath(target: string, cwd: string): string {
+	const relative = path.relative(cwd, target);
+	if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return target;
+	return relative;
+}
+
+function truncateLine(text: string): string {
+	const trimmed = text.trim();
+	return trimmed.length > MAX_LINE_CHARS ? `${trimmed.slice(0, MAX_LINE_CHARS)}... [truncated]` : trimmed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** `Location | Location[] | LocationLink[] | null` collapsed to one 1-based shape. */
+export function normalizeLocations(result: unknown): NormalizedLocation[] {
+	if (result === null || result === undefined) return [];
+	const items = Array.isArray(result) ? result : [result];
+	const out: NormalizedLocation[] = [];
+	for (const item of items) {
+		if (!isRecord(item)) continue;
+		// LocationLink points at targetSelectionRange (the name) rather than
+		// targetRange (the whole declaration body), which is what a reader wants.
+		const uri = typeof item.uri === "string" ? item.uri : typeof item.targetUri === "string" ? item.targetUri : undefined;
+		if (!uri) continue;
+		const range = (item.range ?? item.targetSelectionRange ?? item.targetRange) as LspRange | undefined;
+		const { line, column } = fromLspPosition(range?.start);
+		out.push({ path: uriToPath(uri), line, column });
+	}
+	return out;
+}
+
+export interface LocationListOptions {
+	cwd: string;
+	readLine: LineReader;
+	limit: number;
+	/** Plural noun for the header, e.g. "references". Omit for a bare list. */
+	label?: string;
+}
+
+export function formatLocations(locations: NormalizedLocation[], options: LocationListOptions): string {
+	const shown = locations.slice(0, Math.max(1, options.limit));
+	const lines = shown.map((location) => {
+		const source = options.readLine(location.path, location.line);
+		const suffix = source === undefined ? "" : ` ${truncateLine(source)}`;
+		return `${displayPath(location.path, options.cwd)}:${location.line}:${location.column}:${suffix}`;
+	});
+	if (!options.label) return lines.join("\n");
+	const header =
+		locations.length > shown.length
+			? `${locations.length} ${options.label} (showing first ${shown.length})`
+			: `${locations.length} ${options.label}`;
+	return [header, ...lines].join("\n");
+}
+
+export function formatHover(result: unknown): string {
+	if (!isRecord(result)) return "";
+	const rendered = renderHoverContents(result.contents).trim();
+	return rendered.length > MAX_HOVER_CHARS ? `${rendered.slice(0, MAX_HOVER_CHARS)}\n... [truncated]` : rendered;
+}
+
+function renderHoverContents(contents: unknown): string {
+	if (typeof contents === "string") return contents;
+	if (Array.isArray(contents)) return contents.map(renderHoverContents).filter(Boolean).join("\n\n");
+	if (!isRecord(contents)) return "";
+	// MarkupContent
+	if (typeof contents.value === "string" && typeof contents.kind === "string") return contents.value;
+	// MarkedString: {language, value}
+	if (typeof contents.value === "string") {
+		const language = typeof contents.language === "string" ? contents.language : "";
+		return `\`\`\`${language}\n${contents.value}\n\`\`\``;
+	}
+	return "";
+}
+
+function symbolKindName(kind: number): string {
+	return SYMBOL_KINDS[kind - 1] ?? "Symbol";
+}
+
+export function formatSymbols(result: unknown, cwd: string): string {
+	if (!Array.isArray(result) || result.length === 0) return "";
+	const lines: string[] = [];
+	let remaining = MAX_SYMBOLS;
+
+	const walk = (symbols: LspDocumentSymbol[], depth: number): void => {
+		for (const symbol of symbols) {
+			if (remaining <= 0) return;
+			remaining -= 1;
+			const { line } = fromLspPosition((symbol.selectionRange ?? symbol.range)?.start);
+			const detail = symbol.detail ? ` ${symbol.detail}` : "";
+			lines.push(`${"  ".repeat(depth)}${symbolKindName(symbol.kind)} ${symbol.name}${detail} :${line}`);
+			if (symbol.children?.length) walk(symbol.children, depth + 1);
+		}
+	};
+
+	const first = result[0] as Record<string, unknown>;
+	if (isRecord(first) && isRecord(first.location)) {
+		// Flat SymbolInformation[] — older servers, no hierarchy available.
+		for (const symbol of (result as LspSymbolInformation[]).slice(0, MAX_SYMBOLS)) {
+			const { line } = fromLspPosition(symbol.location?.range?.start);
+			const container = symbol.containerName ? ` (in ${symbol.containerName})` : "";
+			const file = displayPath(uriToPath(symbol.location?.uri ?? ""), cwd);
+			lines.push(`${symbolKindName(symbol.kind)} ${symbol.name}${container} ${file}:${line}`);
+		}
+	} else {
+		walk(result as LspDocumentSymbol[], 0);
+	}
+
+	const total = countSymbols(result as LspDocumentSymbol[]);
+	if (total > lines.length) lines.push(`... ${total - lines.length} more symbols`);
+	return lines.join("\n");
+}
+
+function countSymbols(symbols: LspDocumentSymbol[]): number {
+	let total = 0;
+	for (const symbol of symbols) {
+		total += 1 + (symbol.children ? countSymbols(symbol.children) : 0);
+	}
+	return total;
+}
+
+export function formatDiagnostics(diagnostics: LspDiagnostic[], filePath: string, cwd: string): string {
+	if (diagnostics.length === 0) return "";
+	const counts = [0, 0, 0, 0];
+	for (const diagnostic of diagnostics) counts[(diagnostic.severity ?? 1) - 1] += 1;
+	const summary = SEVERITY_NAMES.map((name, index) => (counts[index] > 0 ? `${counts[index]} ${name}${counts[index] === 1 ? "" : "s"}` : null))
+		.filter(Boolean)
+		.join(", ");
+
+	const file = displayPath(filePath, cwd);
+	const lines = diagnostics.slice(0, MAX_DIAGNOSTICS).map((diagnostic) => {
+		const { line, column } = fromLspPosition(diagnostic.range?.start);
+		const severity = SEVERITY_NAMES[(diagnostic.severity ?? 1) - 1] ?? "error";
+		const source = diagnostic.source ? ` [${diagnostic.source}]` : "";
+		return `${severity} ${file}:${line}:${column}: ${diagnostic.message.replace(/\s*\n\s*/g, " ")}${source}`;
+	});
+	if (diagnostics.length > lines.length) lines.push(`... ${diagnostics.length - lines.length} more`);
+	return [summary, ...lines].join("\n");
+}

package/pi-router/src/lsp-install.ts

@@ -0,0 +1,215 @@
+/**
+ * Opt-in language-server provisioning.
+ *
+ * Nothing here runs uninvited: the assistant is told (via a system-prompt
+ * addendum) which detected languages lack a server, offers ONCE in
+ * conversation ("I can enable Go LSP support if you'd like — just say the
+ * word!"), and only a user "yes" relayed through the lsp_enable tool triggers
+ * an install. A "no, stop asking" is persisted per language and respected
+ * across sessions.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import * as fs from "node:fs";
+import type { SpawnFn } from "./lsp-client.js";
+import {
+	defaultWhich,
+	detectMarkers,
+	installCommandText,
+	LSP_SERVERS,
+	resolveBinary,
+	type LanguageServerSpec,
+	type WhichFn,
+} from "./lsp-servers.js";
+
+const INSTALL_TIMEOUT_MS = 300_000;
+const INSTALL_KILL_GRACE_MS = 5000;
+const OUTPUT_TAIL_BYTES = 2048;
+const MAX_SCAN_ENTRIES = 50;
+const SKIPPED_SCAN_DIRS = new Set(["node_modules", "vendor", "dist", "build", "target"]);
+
+export interface DetectDeps {
+	exists?(target: string): boolean;
+	readDir?(dir: string): string[];
+	isDir?(target: string): boolean;
+}
+
+/**
+ * Which registry languages are present in a workspace: positive markers at the
+ * root or one level down (enough for common monorepo layouts, cheap enough to
+ * run at session start).
+ */
+export function detectWorkspaceServers(cwd: string, deps: DetectDeps = {}): LanguageServerSpec[] {
+	const exists = deps.exists ?? fs.existsSync;
+	const isDir = deps.isDir ?? ((target: string) => {
+		try {
+			return fs.statSync(target).isDirectory();
+		} catch {
+			return false;
+		}
+	});
+	const readDir = deps.readDir ?? ((dir: string) => {
+		try {
+			return fs.readdirSync(dir);
+		} catch {
+			return [];
+		}
+	});
+
+	const roots = [cwd];
+	for (const entry of readDir(cwd).slice(0, MAX_SCAN_ENTRIES)) {
+		if (entry.startsWith(".") || SKIPPED_SCAN_DIRS.has(entry)) continue;
+		const child = `${cwd}/${entry}`;
+		if (isDir(child)) roots.push(child);
+	}
+
+	return LSP_SERVERS.filter((spec) =>
+		roots.some((root) => detectMarkers(spec).some((marker) => exists(`${root}/${marker}`))),
+	);
+}
+
+interface LspPrefs {
+	dismissed: string[];
+}
+
+/** Tolerant read: a missing or corrupt prefs file means "nothing dismissed", never an error. */
+export function loadDismissedLanguages(prefsPath: string, readFile: (p: string) => string = (p) => fs.readFileSync(p, "utf8")): Set<string> {
+	try {
+		const parsed = JSON.parse(readFile(prefsPath)) as Partial<LspPrefs>;
+		return new Set(Array.isArray(parsed.dismissed) ? parsed.dismissed.filter((entry) => typeof entry === "string") : []);
+	} catch {
+		return new Set();
+	}
+}
+
+export function saveDismissedLanguages(
+	prefsPath: string,
+	dismissed: Set<string>,
+	writeFile: (p: string, data: string) => void = (p, data) => fs.writeFileSync(p, data),
+): void {
+	writeFile(prefsPath, `${JSON.stringify({ dismissed: [...dismissed].sort() }, null, 2)}\n`);
+}
+
+/**
+ * The system-prompt addendum that turns detection into a conversational offer.
+ * Returns undefined when there is nothing to offer (nothing detected missing,
+ * or everything relevant was dismissed).
+ */
+export function buildLspOffer(missing: LanguageServerSpec[], dismissed: Set<string>): string | undefined {
+	const offerable = missing.filter((spec) => !dismissed.has(spec.language));
+	if (offerable.length === 0) return undefined;
+	const languages = offerable.map((spec) => spec.language).join(", ");
+	return [
+		"## Code intelligence (LSP)",
+		`This workspace contains ${languages} code, but the matching language server(s) are not installed, so the \`lsp\` tool cannot serve those files yet.`,
+		`At a natural moment, offer ONCE — briefly, in your own words (e.g. "I can enable ${offerable[0].language} LSP support if you'd like — just say the word!") — to enable it.`,
+		'If the user agrees, call lsp_enable with {"language": "<language>"} for each language they want.',
+		'If they decline or ask not to be asked again, call lsp_enable with {"language": "<language>", "action": "dismiss"} and drop the subject.',
+		"Never call lsp_enable without the user's explicit go-ahead, and do not repeat the offer in this session.",
+	].join("\n");
+}
+
+export interface InstallResult {
+	ok: boolean;
+	text: string;
+}
+
+export interface InstallDeps {
+	which?: WhichFn;
+	spawnFn?: SpawnFn;
+	timeoutMs?: number;
+	killGraceMs?: number;
+}
+
+/** Run the spec's install command. Only ever called with the user's explicit consent. */
+export async function installServer(spec: LanguageServerSpec, deps: InstallDeps = {}, signal?: AbortSignal): Promise<InstallResult> {
+	const which = deps.which ?? defaultWhich;
+	const commandText = installCommandText(spec);
+
+	if (resolveBinary(spec, which)) {
+		return { ok: true, text: `The ${spec.language} language server is already installed — the lsp tool is ready for ${spec.language} files.` };
+	}
+	if (!which(spec.install.requires)) {
+		return {
+			ok: false,
+			text: `Cannot install the ${spec.language} language server: it needs \`${spec.install.requires}\` on PATH (the install command is \`${commandText}\`). The install-lsps skill covers installing the ${spec.install.requires} toolchain with the user's consent.`,
+		};
+	}
+
+	const [command, ...args] = spec.install.command;
+	const spawnFn = deps.spawnFn ?? nodeSpawn;
+	const timeoutMs = deps.timeoutMs ?? INSTALL_TIMEOUT_MS;
+	const killGraceMs = deps.killGraceMs ?? INSTALL_KILL_GRACE_MS;
+
+	const outcome = await new Promise<{ code: number | null; output: string; cancelled?: "aborted" | "timed out" }>((resolve) => {
+		const child = spawnFn(command, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+		let tail = "";
+		let settled = false;
+		let cancelled: "aborted" | "timed out" | undefined;
+		let killTimer: NodeJS.Timeout | undefined;
+		const settle = (code: number | null): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (killTimer) clearTimeout(killTimer);
+			signal?.removeEventListener("abort", onAbort);
+			resolve({ code, output: tail, cancelled });
+		};
+		const append = (chunk: Buffer): void => {
+			tail = (tail + chunk.toString("utf8")).slice(-OUTPUT_TAIL_BYTES);
+		};
+		// Cancellation must not settle before the child actually exits — an
+		// installer that shrugs off SIGTERM would keep mutating the system after
+		// we reported failure. Settle on close, escalating to SIGKILL if needed.
+		const cancel = (reason: "aborted" | "timed out"): void => {
+			if (settled || cancelled) return;
+			cancelled = reason;
+			child.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!settled) child.kill("SIGKILL");
+			}, killGraceMs);
+			killTimer.unref?.();
+		};
+		const onAbort = (): void => cancel("aborted");
+		const timer = setTimeout(() => cancel("timed out"), timeoutMs);
+		timer.unref?.();
+
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+		child.on("close", (code) => settle(code));
+		child.on("error", (error: Error) => {
+			append(Buffer.from(error.message));
+			settle(null);
+		});
+		if (signal) {
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+
+	const lastOutputLine =
+		outcome.output
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean)
+			.pop() ?? "";
+	if (outcome.cancelled) {
+		return {
+			ok: false,
+			text: `Installing the ${spec.language} language server ${outcome.cancelled} (\`${commandText}\`); the installer process was stopped. The install may be partial — re-run \`${commandText}\` to complete it.`,
+		};
+	}
+	if (outcome.code !== 0) {
+		return {
+			ok: false,
+			text: `Installing the ${spec.language} language server failed (\`${commandText}\`${outcome.code === null ? "" : `, exit ${outcome.code}`})${lastOutputLine ? `: ${lastOutputLine}` : ""}`,
+		};
+	}
+	if (!resolveBinary(spec, which)) {
+		return {
+			ok: false,
+			text: `\`${commandText}\` succeeded but its binary is still not resolvable — the install location is probably not on PATH. Ask the user to add it and restart pi.`,
+		};
+	}
+	return { ok: true, text: `Installed the ${spec.language} language server — the lsp tool now works for ${spec.language} files in this session.` };
+}

package/pi-router/src/lsp-protocol.ts

@@ -0,0 +1,128 @@
+/**
+ * Content-Length framing and coordinate conversion.
+ *
+ * Both transports in this subsystem speak the same wire format: LSP servers
+ * over stdio, and the subagent broker over a local socket. Framing lives here
+ * so neither owns it.
+ */
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export interface JsonRpcMessage {
+	jsonrpc?: string;
+	id?: number | string | null;
+	method?: string;
+	params?: unknown;
+	result?: unknown;
+	error?: { code: number; message: string; data?: unknown };
+}
+
+const HEADER_SEPARATOR = "\r\n\r\n";
+
+/** Buffered-bytes ceiling. A peer that blows through it is malfunctioning; the owner kills it. */
+export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export function encodeFrame(message: unknown): Buffer {
+	const body = Buffer.from(JSON.stringify(message), "utf8");
+	// Content-Length counts BYTES, not characters — a UTF-8 body with any
+	// non-ASCII content would otherwise desynchronize the peer's parser.
+	return Buffer.concat([Buffer.from(`Content-Length: ${body.length}${HEADER_SEPARATOR}`, "ascii"), body]);
+}
+
+export interface FrameParser {
+	push(chunk: Buffer): void;
+}
+
+/**
+ * Incremental parser: handles several frames per chunk, one frame split across
+ * chunks, and extra headers (`Content-Type`). A body that is not JSON costs
+ * that one message; `onOverflow` fires once and the parser then stays quiet so
+ * the owner can tear the peer down.
+ */
+export function createFrameParser(onMessage: (message: JsonRpcMessage) => void, onOverflow?: (error: Error) => void): FrameParser {
+	let buffer = Buffer.alloc(0);
+	let overflowed = false;
+
+	return {
+		push(chunk: Buffer): void {
+			if (overflowed) return;
+			buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+			if (buffer.length > MAX_FRAME_BYTES) {
+				overflowed = true;
+				buffer = Buffer.alloc(0);
+				onOverflow?.(new Error(`framed message exceeded ${MAX_FRAME_BYTES} bytes`));
+				return;
+			}
+
+			while (true) {
+				const headerEnd = buffer.indexOf(HEADER_SEPARATOR);
+				if (headerEnd === -1) return;
+				const header = buffer.subarray(0, headerEnd).toString("ascii");
+				const match = /content-length:\s*(\d+)/i.exec(header);
+				if (!match) {
+					// No length means no way to find the next boundary; drop the header
+					// block and resynchronize on whatever follows it.
+					buffer = buffer.subarray(headerEnd + HEADER_SEPARATOR.length);
+					continue;
+				}
+				const bodyStart = headerEnd + HEADER_SEPARATOR.length;
+				const bodyLength = Number(match[1]);
+				if (buffer.length < bodyStart + bodyLength) return;
+				const body = buffer.subarray(bodyStart, bodyStart + bodyLength).toString("utf8");
+				buffer = buffer.subarray(bodyStart + bodyLength);
+				try {
+					onMessage(JSON.parse(body) as JsonRpcMessage);
+				} catch {
+					/* malformed body — skip this message, keep the stream */
+				}
+			}
+		},
+	};
+}
+
+export function pathToUri(filePath: string): string {
+	return pathToFileURL(filePath).toString();
+}
+
+export function uriToPath(uri: string): string {
+	if (!uri.startsWith("file:")) return uri;
+	try {
+		return fileURLToPath(uri);
+	} catch {
+		// Some servers emit non-canonical file URIs (unencoded spaces).
+		return decodeURIComponent(uri.replace(/^file:\/\//, ""));
+	}
+}
+
+/**
+ * The operation vocabulary. It lives beside the framing rather than with the pi
+ * tool because it is literally the broker's wire payload — keeping it here lets
+ * the broker stay below the tool adapter instead of importing back into it.
+ */
+export const LSP_OPERATIONS = ["definition", "references", "hover", "documentSymbol", "diagnostics"] as const;
+
+export type LspOperation = (typeof LSP_OPERATIONS)[number];
+
+/** Operations that resolve a point in a file, and so require line + column. */
+export const POSITION_OPERATIONS = new Set<LspOperation>(["definition", "references", "hover"]);
+
+export interface LspOperationParams {
+	operation: LspOperation;
+	path: string;
+	line?: number;
+	column?: number;
+}
+
+export interface LspPosition {
+	line: number;
+	character: number;
+}
+
+/** Model-facing 1-based line/column to the 0-based position LSP uses. */
+export function toLspPosition(line: number, column: number): LspPosition {
+	return { line: Math.max(0, Math.trunc(line) - 1), character: Math.max(0, Math.trunc(column) - 1) };
+}
+
+export function fromLspPosition(position: LspPosition | undefined): { line: number; column: number } {
+	return { line: (position?.line ?? 0) + 1, column: (position?.character ?? 0) + 1 };
+}