Files
waggle-os/packages/agent/src/lsp-tools.ts
Oleg Maslov b20b138fe4 moving
2026-09-02 10:14:22 +02:00

581 lines
19 KiB
TypeScript

/**
* LSP Tools — Language Server Protocol integration via typescript-language-server.
*
* Tools:
* lsp_diagnostics — Get errors/warnings for a file
* lsp_definition — Go-to-definition (file + line)
* lsp_references — Find all references (file + line for each)
* lsp_hover — Get type info and documentation
*
* The LSP client spawns typescript-language-server as a child process,
* communicating via stdio using JSON-RPC (LSP protocol). The server is
* started on first tool use and stopped on session end.
*/
import * as path from 'node:path';
import * as fs from 'node:fs';
import type { ChildProcess } from 'node:child_process';
import type { ToolDefinition } from './tools.js';
import { resolveToolCommandInvocationFromPath } from './tool-command.js';
import { createSanitizedEnv } from './system-tools-helpers.js';
import {
spawnSidecarOwnedProcess,
type SidecarOwnedProcessOptions,
} from './sidecar-owned-process.js';
// ── Minimal LSP/JSON-RPC wire shapes (only the fields we read) ──
interface LspPosition { line?: number; character?: number }
interface LspRange { start?: LspPosition; end?: LspPosition }
interface LspDiagnostic { severity?: number; range?: LspRange; message?: string }
interface LspLocation { uri?: string; targetUri?: string; range?: LspRange; targetRange?: LspRange }
interface LspMarkup { value?: string }
type LspHoverContent = string | LspMarkup;
/** A parsed JSON-RPC response body. `result` is untyped wire data. */
interface JsonRpcMessage {
id?: number;
error?: { message?: string };
result?: unknown;
}
interface PendingRequest {
resolve: (v: unknown) => void;
reject: (e: Error) => void;
}
// Module-level LSP state
let lspProcess: ChildProcess | null = null;
let lspInitialized = false;
let lspWorkspace: string = '';
let requestId = 0;
let pendingRequests = new Map<number, PendingRequest>();
let receiveBuffer = '';
export interface LspSpawnDeps {
resolveCommand?: typeof resolveToolCommandInvocationFromPath;
spawnOwned?: (
executable: string,
args: string[],
options: SidecarOwnedProcessOptions,
) => ChildProcess;
}
export async function spawnLspServerProcess(
workspacePath: string,
deps: LspSpawnDeps = {},
): Promise<ChildProcess> {
const env = createSanitizedEnv();
const invocation = await (deps.resolveCommand ?? resolveToolCommandInvocationFromPath)(
'typescript-language-server',
['--stdio'],
process.platform,
{ env },
);
return (deps.spawnOwned ?? spawnSidecarOwnedProcess)(
invocation.binary,
invocation.args,
{
cwd: workspacePath,
env,
stdio: ['pipe', 'pipe', 'pipe'],
windowsHide: true,
windowsVerbatimArguments: invocation.windowsVerbatimArguments === true,
},
);
}
export async function stopLspServerProcess(
child: ChildProcess,
timeoutMs = 6_500,
): Promise<void> {
if (child.exitCode !== null || child.signalCode !== null) return;
await new Promise<void>((resolveStop, rejectStop) => {
let settled = false;
const finish = (error?: Error): void => {
if (settled) return;
settled = true;
clearTimeout(timer);
child.removeListener('exit', onExit);
child.removeListener('error', onError);
if (error) rejectStop(error);
else resolveStop();
};
const onExit = (): void => finish();
const onError = (error: Error): void => finish(error);
const timer = setTimeout(
() => finish(new Error('Timed out while stopping the sidecar-owned LSP process tree')),
timeoutMs,
);
timer.unref();
child.once('exit', onExit);
child.once('error', onError);
if (child.exitCode !== null || child.signalCode !== null) {
finish();
return;
}
if (!child.connected || typeof child.send !== 'function') return;
try {
child.send('shutdown', (error) => {
if (error) finish(error);
});
} catch (error) {
finish(error instanceof Error ? error : new Error(String(error)));
}
});
}
/** Reset module-level state (for testing). */
export function _resetLspState(): void {
lspProcess = null;
lspInitialized = false;
lspWorkspace = '';
requestId = 0;
pendingRequests = new Map();
receiveBuffer = '';
}
/** Send a JSON-RPC message to the LSP server. */
function sendMessage(msg: object): void {
if (!lspProcess?.stdin?.writable) {
throw new Error('LSP server not running');
}
const json = JSON.stringify(msg);
const header = `Content-Length: ${Buffer.byteLength(json)}\r\n\r\n`;
lspProcess.stdin.write(header + json);
}
/** Send a request and wait for a response. The result is raw JSON-RPC wire data. */
function sendRequest(method: string, params: object): Promise<unknown> {
return new Promise((resolve, reject) => {
const id = ++requestId;
pendingRequests.set(id, { resolve, reject });
sendMessage({ jsonrpc: '2.0', id, method, params });
// Timeout after 10 seconds
setTimeout(() => {
if (pendingRequests.has(id)) {
pendingRequests.delete(id);
reject(new Error(`LSP request "${method}" timed out after 10s`));
}
}, 10_000);
});
}
/** Send a notification (no response expected). */
function sendNotification(method: string, params: object): void {
sendMessage({ jsonrpc: '2.0', method, params });
}
/** Process incoming data from the LSP server. */
function handleData(data: string): void {
receiveBuffer += data;
while (true) {
// Look for Content-Length header
const headerEnd = receiveBuffer.indexOf('\r\n\r\n');
if (headerEnd === -1) break;
const header = receiveBuffer.slice(0, headerEnd);
const match = header.match(/Content-Length:\s*(\d+)/i);
if (!match) {
// Skip malformed header
receiveBuffer = receiveBuffer.slice(headerEnd + 4);
continue;
}
const contentLength = parseInt(match[1], 10);
const bodyStart = headerEnd + 4;
if (receiveBuffer.length < bodyStart + contentLength) break; // Wait for more data
const body = receiveBuffer.slice(bodyStart, bodyStart + contentLength);
receiveBuffer = receiveBuffer.slice(bodyStart + contentLength);
try {
const msg = JSON.parse(body) as JsonRpcMessage;
if (msg.id !== undefined && pendingRequests.has(msg.id)) {
const pending = pendingRequests.get(msg.id)!;
pendingRequests.delete(msg.id);
if (msg.error) {
pending.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
} else {
pending.resolve(msg.result);
}
}
// Notifications and other messages are ignored for now
} catch {
// Malformed JSON — skip
}
}
}
/** Start the LSP server if not already running. */
async function ensureLsp(workspacePath: string): Promise<void> {
if (lspProcess && lspInitialized && lspWorkspace === workspacePath) return;
// Try to spawn
try {
lspProcess = await spawnLspServerProcess(workspacePath);
} catch {
throw new Error(
'LSP requires typescript-language-server. Install with: npm install -g typescript-language-server typescript',
);
}
lspWorkspace = workspacePath;
// Wire up data handling
lspProcess.stdout?.setEncoding('utf-8');
lspProcess.stdout?.on('data', handleData);
lspProcess.on('error', () => {
lspProcess = null;
lspInitialized = false;
});
lspProcess.on('exit', () => {
lspProcess = null;
lspInitialized = false;
});
// Send initialize request
try {
const result = await sendRequest('initialize', {
processId: process.pid,
rootUri: `file:///${workspacePath.replace(/\\/g, '/')}`,
capabilities: {
textDocument: {
hover: { contentFormat: ['plaintext', 'markdown'] },
definition: { linkSupport: false },
references: {},
publishDiagnostics: { relatedInformation: true },
},
},
workspaceFolders: [
{
uri: `file:///${workspacePath.replace(/\\/g, '/')}`,
name: path.basename(workspacePath),
},
],
});
// Send initialized notification
sendNotification('initialized', {});
lspInitialized = true;
} catch (err: unknown) {
await stopLsp();
throw new Error(
`LSP initialization failed: ${err instanceof Error ? err.message : String(err)}. Ensure typescript-language-server is installed globally.`,
);
}
}
/** Stop the LSP server. */
async function stopLsp(): Promise<void> {
if (lspProcess) {
const processToStop = lspProcess;
try {
sendNotification('shutdown', {});
sendNotification('exit', {});
} catch {
// Already dead
}
lspProcess = null;
lspInitialized = false;
await stopLspServerProcess(processToStop);
}
}
/** Convert a file path to a file:// URI. */
function fileUri(filePath: string): string {
const normalized = filePath.replace(/\\/g, '/');
if (normalized.startsWith('/')) return `file://${normalized}`;
return `file:///${normalized}`;
}
/** Notify the LSP that a file is open (required before requesting info). */
async function openFile(filePath: string): Promise<void> {
const content = fs.readFileSync(filePath, 'utf-8');
const uri = fileUri(filePath);
// Determine language ID from extension
const ext = path.extname(filePath).toLowerCase();
const languageId = ext === '.tsx' ? 'typescriptreact'
: ext === '.jsx' ? 'javascriptreact'
: ext === '.js' || ext === '.mjs' || ext === '.cjs' ? 'javascript'
: 'typescript';
sendNotification('textDocument/didOpen', {
textDocument: {
uri,
languageId,
version: 1,
text: content,
},
});
// Give the LSP a moment to process
await new Promise(resolve => setTimeout(resolve, 500));
}
// Register cleanup on process exit
process.on('exit', () => { stopLsp().catch(() => {}); });
export function createLspTools(workspacePath: string): ToolDefinition[] {
return [
// 1. lsp_diagnostics — Get errors/warnings for a file
{
name: 'lsp_diagnostics',
description:
'Get TypeScript/JavaScript errors and warnings for a file using the Language Server Protocol.',
parameters: {
type: 'object',
properties: {
file_path: {
type: 'string',
description: 'File path relative to workspace',
},
},
required: ['file_path'],
},
execute: async (args) => {
try {
const filePath = args.file_path as string;
const absPath = path.resolve(workspacePath, filePath);
if (!fs.existsSync(absPath)) {
return `Error: File not found: ${filePath}`;
}
await ensureLsp(workspacePath);
await openFile(absPath);
// Request diagnostics via textDocument/diagnostic (LSP 3.17+)
// Fallback: use textDocument/codeAction as a probe, or rely on publishDiagnostics
// For simplicity, wait a bit then request semantic tokens which triggers diagnostics
const uri = fileUri(absPath);
// Use document diagnostic request
try {
const result = (await sendRequest('textDocument/diagnostic', {
textDocument: { uri },
})) as { items?: LspDiagnostic[] } | null;
const items = result?.items ?? [];
if (items.length === 0) {
return `No diagnostics found for ${filePath}. File is clean.`;
}
return items
.map((d) => {
const severity = d.severity === 1 ? 'Error' : d.severity === 2 ? 'Warning' : d.severity === 3 ? 'Info' : 'Hint';
const line = (d.range?.start?.line ?? 0) + 1;
const col = (d.range?.start?.character ?? 0) + 1;
return `${severity} [${line}:${col}]: ${d.message}`;
})
.join('\n');
} catch {
// Fallback: just report that we tried
return `Diagnostics not available for ${filePath}. The language server may not support pull diagnostics.`;
}
} catch (err: unknown) {
return `LSP diagnostics error: ${err instanceof Error ? err.message : String(err)}`;
}
},
},
// 2. lsp_definition — Go to definition
{
name: 'lsp_definition',
description:
'Go to the definition of a symbol at a given position. Returns the file path and line number.',
parameters: {
type: 'object',
properties: {
file_path: {
type: 'string',
description: 'File path relative to workspace',
},
line: {
type: 'number',
description: 'Line number (1-based)',
},
column: {
type: 'number',
description: 'Column number (1-based)',
},
},
required: ['file_path', 'line', 'column'],
},
execute: async (args) => {
try {
const filePath = args.file_path as string;
const line = (args.line as number) - 1; // Convert to 0-based
const column = (args.column as number) - 1;
const absPath = path.resolve(workspacePath, filePath);
if (!fs.existsSync(absPath)) {
return `Error: File not found: ${filePath}`;
}
await ensureLsp(workspacePath);
await openFile(absPath);
const result = (await sendRequest('textDocument/definition', {
textDocument: { uri: fileUri(absPath) },
position: { line, character: column },
})) as LspLocation | LspLocation[] | null;
if (!result || (Array.isArray(result) && result.length === 0)) {
return `No definition found at ${filePath}:${line + 1}:${column + 1}`;
}
const locations: LspLocation[] = Array.isArray(result) ? result : [result];
return locations
.map((loc) => {
const uri = loc.uri ?? loc.targetUri ?? '';
const range = loc.range ?? loc.targetRange ?? {};
const startLine = (range.start?.line ?? 0) + 1;
// Convert file URI back to path
const defPath = uri.replace(/^file:\/\/\/?/, '').replace(/%20/g, ' ');
const relPath = path.relative(workspacePath, defPath);
return `Definition: ${relPath}:${startLine}`;
})
.join('\n');
} catch (err: unknown) {
return `LSP definition error: ${err instanceof Error ? err.message : String(err)}`;
}
},
},
// 3. lsp_references — Find all references
{
name: 'lsp_references',
description:
'Find all references to a symbol at a given position. Returns file paths and line numbers.',
parameters: {
type: 'object',
properties: {
file_path: {
type: 'string',
description: 'File path relative to workspace',
},
line: {
type: 'number',
description: 'Line number (1-based)',
},
column: {
type: 'number',
description: 'Column number (1-based)',
},
},
required: ['file_path', 'line', 'column'],
},
execute: async (args) => {
try {
const filePath = args.file_path as string;
const line = (args.line as number) - 1;
const column = (args.column as number) - 1;
const absPath = path.resolve(workspacePath, filePath);
if (!fs.existsSync(absPath)) {
return `Error: File not found: ${filePath}`;
}
await ensureLsp(workspacePath);
await openFile(absPath);
const result = (await sendRequest('textDocument/references', {
textDocument: { uri: fileUri(absPath) },
position: { line, character: column },
context: { includeDeclaration: true },
})) as LspLocation[] | null;
if (!result || result.length === 0) {
return `No references found at ${filePath}:${line + 1}:${column + 1}`;
}
const lines: string[] = [`References (${result.length}):`];
for (const ref of result) {
const uri = ref.uri ?? '';
const startLine = (ref.range?.start?.line ?? 0) + 1;
const defPath = uri.replace(/^file:\/\/\/?/, '').replace(/%20/g, ' ');
const relPath = path.relative(workspacePath, defPath);
lines.push(` ${relPath}:${startLine}`);
}
return lines.join('\n');
} catch (err: unknown) {
return `LSP references error: ${err instanceof Error ? err.message : String(err)}`;
}
},
},
// 4. lsp_hover — Get type info and documentation
{
name: 'lsp_hover',
description:
'Get type information and documentation for a symbol at a given position.',
parameters: {
type: 'object',
properties: {
file_path: {
type: 'string',
description: 'File path relative to workspace',
},
line: {
type: 'number',
description: 'Line number (1-based)',
},
column: {
type: 'number',
description: 'Column number (1-based)',
},
},
required: ['file_path', 'line', 'column'],
},
execute: async (args) => {
try {
const filePath = args.file_path as string;
const line = (args.line as number) - 1;
const column = (args.column as number) - 1;
const absPath = path.resolve(workspacePath, filePath);
if (!fs.existsSync(absPath)) {
return `Error: File not found: ${filePath}`;
}
await ensureLsp(workspacePath);
await openFile(absPath);
const result = (await sendRequest('textDocument/hover', {
textDocument: { uri: fileUri(absPath) },
position: { line, character: column },
})) as { contents?: LspHoverContent | LspHoverContent[] } | null;
if (!result || !result.contents) {
return `No hover info at ${filePath}:${line + 1}:${column + 1}`;
}
// Parse hover contents — can be string, MarkupContent, or MarkedString[]
const contents = result.contents;
if (typeof contents === 'string') return contents;
if (Array.isArray(contents)) {
return contents
.map((c) => (typeof c === 'string' ? c : c.value ?? ''))
.filter(Boolean)
.join('\n\n');
}
if (contents.value) return contents.value;
return JSON.stringify(contents, null, 2);
} catch (err: unknown) {
return `LSP hover error: ${err instanceof Error ? err.message : String(err)}`;
}
},
},
];
}
export { stopLsp };