@dreki-gg/pi-lsp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @dreki-gg/pi-lsp
 
+## 0.3.0
+
+### Minor Changes
+
+- [#43](https://github.com/dreki-gg/pi-extensions/pull/43) [`c8dc964`](https://github.com/dreki-gg/pi-extensions/commit/c8dc96448bd8cf1a594daf42a1ab0d56f932d629) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(lsp): improve reliability and LLM guidance based on real-world usage feedback
+
+  - **documentSymbol now includes column positions** — output shows `line:col` instead of just `line`, eliminating the need for a follow-up `rg --column` to get positions for other LSP operations.
+  - **Retry with backoff during server indexing** — `hover`, `definition`, `references`, `implementation`, `documentSymbol`, and `workspaceSymbol` automatically retry (up to 2 times, 2s delay) when the server was recently initialized and returns empty results.
+  - **Send `didSave` notification** — the client now sends `textDocument/didSave` after opening or updating documents, fixing diagnostics for servers like `rust-analyzer` that require save events.
+  - **Improved diagnostics wait logic** — stale cached diagnostics are cleared on document re-sync, and the arbitrary 500ms delay is removed in favor of resolving immediately when fresh diagnostics arrive.
+  - **Rewritten `promptGuidelines`** — 9 targeted guidelines that teach LLMs (especially smaller models) how to use LSP tools effectively: prefer `hover` for quick inspection, position cursor in the middle of symbols, use compiler tools for diagnostics in compiled languages, and more.
+  - **Enhanced tool description** — includes tips section and notes that `incomingCalls`/`outgoingCalls` auto-prepare the call hierarchy.
+  - **Removed unused code** — `pathToUri` export, `capabilities` getter, and `closeDocument` method removed.
+
+### Patch Changes
+
+- [`87baca4`](https://github.com/dreki-gg/pi-extensions/commit/87baca402f6afa0bba627a3c179bacf0bbbeacba) Thanks [@jalbarrang](https://github.com/jalbarrang)! - fix(lsp): Windows URI normalization and diagnostic waiter race conditions
+
+  - Add `normalizeUri()` to decode percent-encoded URIs (`%3A` → `:`) and uppercase Windows drive letters, fixing key mismatches between `pathToUri` and server responses.
+  - `pathToUri()` now always uppercases the drive letter for consistency.
+  - `uriToPath()` now applies `decodeURIComponent` so encoded URIs from the server produce valid file paths.
+  - Replace per-URI waiter arrays with a single `PendingDiagnostic` promise per URI, eliminating manual timer/splice management.
+  - Track `invalidatedUris` to distinguish first-open (empty diagnostics = clean file → resolve immediately) from re-open (empty diagnostics = server clearing stale state → wait for real results).
+
+## 0.2.1
+
+### Patch Changes
+
+- [`32797ff`](https://github.com/dreki-gg/pi-extensions/commit/32797ff18d968e22c6c44e95c46e3393d8928cef) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(plan-mode): add Windows compatibility — replace Unix shell commands with cross-platform Bun/Node APIs
+
+  Plan-mode no longer shells out to `cat`, `bash`, or `mkdir` via `pi.exec()`. File I/O now uses `Bun.file()` / `Bun.write()` and `node:fs/promises` `mkdir`, making the extension fully cross-platform. Destructive and safe command pattern lists now include Windows equivalents (`del`, `rd`, `copy`, `move`, `powershell`, `dir`, `where`, `tasklist`, etc.).
+
+  Also fixes Windows compatibility in three other packages:
+
+  - **browser-tools**: `spawn` now uses `shell: true` on Windows so `.cmd` wrappers resolve correctly; `shellEscape` uses double-quote style on Windows; install guidance is platform-aware (Homebrew shown only on macOS).
+  - **subagent**: `spawn` uses `shell: true` on Windows when the command is bare `pi`, allowing `pi.cmd` resolution.
+  - **lsp**: `globalConfigPath()` now uses `os.homedir()` on Windows instead of the unreliable `process.env.HOME`.
+
 ## 0.2.0
 
 ### Minor Changes

package/extensions/lsp/client.ts

@@ -25,20 +25,41 @@ import type {
   ResolvedServerConfig,
   SymbolInformation,
 } from './types';
+import { withRetry } from './retry';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-export function pathToUri(filePath: string): string {
+/**
+ * Normalize a file URI for consistent map-key comparison.
+ *
+ * Some LSP servers (e.g. typescript-language-server on Windows) return URIs with
+ * percent-encoded colons (`%3A`) and lowercase drive letters.  We decode and
+ * uppercase so that `file:///d%3A/…` and `file:///D:/…` resolve to the same key.
+ */
+function normalizeUri(uri: string): string {
+  let normalized = decodeURIComponent(uri);
+  // Uppercase Windows drive letter: file:///d:/… → file:///D:/…
+  normalized = normalized.replace(
+    /^file:\/\/\/([a-z]):/,
+    (_, letter: string) => `file:///${letter.toUpperCase()}:`,
+  );
+  return normalized;
+}
+
+function pathToUri(filePath: string): string {
   const abs = resolve(filePath);
   const normalized = abs.replace(/\\/g, '/');
-  // Windows paths need file:///C:/... (three slashes)
-  if (/^[A-Za-z]:/.test(normalized)) return `file:///${normalized}`;
+  // Windows paths need file:///C:/... (three slashes), always uppercase drive letter
+  if (/^[A-Za-z]:/.test(normalized)) {
+    return `file:///${normalized[0].toUpperCase()}${normalized.slice(1)}`;
+  }
   return `file://${normalized}`;
 }
 
 export function uriToPath(uri: string): string {
   if (!uri.startsWith('file://')) return uri;
-  const path = uri.slice(7);
+  const decoded = decodeURIComponent(uri);
+  const path = decoded.slice(7);
   // Remove leading slash before Windows drive letter: /C:/... → C:/...
   if (/^\/[A-Za-z]:/.test(path)) return path.slice(1);
   return path;
@@ -86,9 +107,18 @@ interface OpenDocument {
   languageId: string;
 }
 
-interface DiagnosticWaiter {
+/**
+ * A single pending diagnostic request per URI.
+ *
+ * Instead of maintaining an array of waiters with individual timers, we keep one
+ * pending promise per URI.  Non-empty `publishDiagnostics` notifications resolve
+ * it immediately; empty ones are stored but do NOT resolve the pending — this
+ * avoids the "empty-then-real" race where the server clears stale diagnostics
+ * before sending real results.  A timeout passed via `Promise.race` in
+ * `waitForDiagnostics` acts as a safety net for genuinely clean files.
+ */
+interface PendingDiagnostic {
   resolve: () => void;
-  timer: ReturnType<typeof setTimeout>;
 }
 
 // ── Client ──────────────────────────────────────────────────────────────────
@@ -99,9 +129,12 @@ export class LspClient {
   private initializePromise: Promise<void> | null = null;
   private openDocs = new Map<string, OpenDocument>();
   private diagnosticStore = new Map<string, Diagnostic[]>();
-  private diagnosticWaiters = new Map<string, DiagnosticWaiter[]>();
+  private pendingDiagnostics = new Map<string, PendingDiagnostic>();
+  /** URIs where we just sent didChange and haven't yet received non-empty diagnostics. */
+  private invalidatedUris = new Set<string>();
   private serverCapabilities: Record<string, unknown> = {};
   private stderrLog: string[] = [];
+  private initTimestamp = 0;
 
   readonly config: ResolvedServerConfig;
   private rootPath: string;
@@ -123,15 +156,26 @@ export class LspClient {
     conn.setNotificationHandler((method, params) => {
       if (method === 'textDocument/publishDiagnostics') {
         const { uri, diagnostics } = params as PublishDiagnosticsParams;
-        this.diagnosticStore.set(uri, diagnostics);
+        const normalized = normalizeUri(uri);
+        this.diagnosticStore.set(normalized, diagnostics);
+
+        // Decide whether to resolve the pending promise:
+        // • Non-empty diagnostics always resolve (real errors found).
+        // • Empty diagnostics resolve ONLY when the URI was NOT recently
+        //   invalidated by a didChange — this avoids the "empty-then-real"
+        //   race where servers clear stale diagnostics before sending real ones.
+        const shouldResolve = diagnostics.length > 0 || !this.invalidatedUris.has(normalized);
+
+        if (diagnostics.length > 0) {
+          this.invalidatedUris.delete(normalized);
+        }
 
-        const waiters = this.diagnosticWaiters.get(uri);
-        if (waiters?.length) {
-          for (const w of waiters) {
-            clearTimeout(w.timer);
-            w.resolve();
+        if (shouldResolve) {
+          const pending = this.pendingDiagnostics.get(normalized);
+          if (pending) {
+            pending.resolve();
+            this.pendingDiagnostics.delete(normalized);
           }
-          this.diagnosticWaiters.delete(uri);
         }
       }
     });
@@ -209,6 +253,24 @@ export class LspClient {
     this.serverCapabilities = result?.capabilities ?? {};
     this.connection.sendNotification('initialized', {});
     this.initialized = true;
+    this.initTimestamp = Date.now();
+  }
+
+  /** Whether the server was initialized recently (within windowMs). */
+  private isRecentlyInitialized(windowMs = 30_000): boolean {
+    return this.initTimestamp > 0 && Date.now() - this.initTimestamp < windowMs;
+  }
+
+  /**
+   * Wrap an LSP operation with retry logic when the server was recently initialized.
+   * During indexing, servers may return empty results that resolve after a short wait.
+   */
+  private async retryIfIndexing<T>(
+    operation: () => Promise<T>,
+    isEmpty: (result: T) => boolean,
+  ): Promise<T> {
+    if (!this.isRecentlyInitialized()) return operation();
+    return withRetry(operation, isEmpty, { maxRetries: 2, delayMs: 2000 });
   }
 
   async shutdown(): Promise<void> {
@@ -228,17 +290,14 @@ export class LspClient {
     this.initializePromise = null;
     this.openDocs.clear();
     this.diagnosticStore.clear();
-    this.clearAllWaiters();
+    this.invalidatedUris.clear();
+    this.clearAllPending();
   }
 
   get isInitialized(): boolean {
     return this.initialized;
   }
 
-  get capabilities(): Record<string, unknown> {
-    return this.serverCapabilities;
-  }
-
   /** Check if the server advertised a specific capability. */
   hasCapability(name: string): boolean {
     return this.serverCapabilities[name] !== undefined && this.serverCapabilities[name] !== false;
@@ -258,6 +317,8 @@ export class LspClient {
 
     if (existing) {
       existing.version++;
+      this.diagnosticStore.delete(uri); // Clear stale diagnostics before re-sync
+      this.invalidatedUris.add(uri); // Mark as invalidated until real diagnostics arrive
       this.connection.sendNotification('textDocument/didChange', {
         textDocument: { uri, version: existing.version },
         contentChanges: [{ text }],
@@ -270,19 +331,14 @@ export class LspClient {
       this.openDocs.set(uri, { uri, version, languageId });
     }
 
-    return uri;
-  }
-
-  async closeDocument(filePath: string): Promise<void> {
-    const uri = pathToUri(resolve(this.rootPath, filePath));
-    const doc = this.openDocs.get(uri);
-    if (!doc) return;
-
-    this.connection.sendNotification('textDocument/didClose', {
+    // Notify the server that the file was saved — some servers (e.g. rust-analyzer)
+    // only generate diagnostics after a didSave notification.
+    this.connection.sendNotification('textDocument/didSave', {
       textDocument: { uri },
+      text,
     });
-    this.openDocs.delete(uri);
-    this.diagnosticStore.delete(uri);
+
+    return uri;
   }
 
   // ── Diagnostics ───────────────────────────────────────────────────────
@@ -293,103 +349,143 @@ export class LspClient {
     return this.diagnosticStore.get(uri) ?? [];
   }
 
-  private waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
-    return new Promise<void>((resolveWait) => {
-      const existing = this.diagnosticStore.get(uri);
-      if (existing !== undefined) {
-        setTimeout(resolveWait, 500);
-        return;
-      }
+  /**
+   * Wait until non-empty diagnostics arrive for `uri`, or until `timeoutMs` elapses.
+   *
+   * If non-empty diagnostics are already in the store (e.g. from a previous
+   * notification), resolves immediately.  Otherwise sets up a single pending
+   * promise that the notification handler will resolve when real diagnostics
+   * arrive.  `Promise.race` against a timeout ensures we don't wait forever
+   * for genuinely clean files.
+   */
+  private async waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
+    // Fast path: diagnostics already present and meaningful.
+    // • Non-empty → file has errors, return immediately.
+    // • Empty + not invalidated → genuinely clean file (e.g. first open), return.
+    const existing = this.diagnosticStore.get(uri);
+    if (existing !== undefined) {
+      if (existing.length > 0 || !this.invalidatedUris.has(uri)) return;
+    }
 
-      const timer = setTimeout(() => {
-        const waiters = this.diagnosticWaiters.get(uri);
-        if (waiters) {
-          const idx = waiters.findIndex((w) => w.resolve === resolveWait);
-          if (idx !== -1) waiters.splice(idx, 1);
-          if (waiters.length === 0) this.diagnosticWaiters.delete(uri);
-        }
-        resolveWait();
-      }, timeoutMs);
+    // Resolve any previous pending for this URI so it doesn't leak.
+    const prev = this.pendingDiagnostics.get(uri);
+    if (prev) prev.resolve();
 
-      const waiters = this.diagnosticWaiters.get(uri) ?? [];
-      waiters.push({ resolve: resolveWait, timer });
-      this.diagnosticWaiters.set(uri, waiters);
+    const { promise, resolve } = Promise.withResolvers<void>();
+    this.pendingDiagnostics.set(uri, { resolve });
+
+    // Safety-net timeout: resolves the race for files with zero errors.
+    let timer: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<void>((r) => {
+      timer = setTimeout(r, timeoutMs);
     });
+
+    await Promise.race([promise, timeout]);
+
+    clearTimeout(timer!);
+    this.pendingDiagnostics.delete(uri);
   }
 
-  private clearAllWaiters(): void {
-    for (const [, waiters] of this.diagnosticWaiters) {
-      for (const w of waiters) {
-        clearTimeout(w.timer);
-        w.resolve();
-      }
+  private clearAllPending(): void {
+    for (const pending of this.pendingDiagnostics.values()) {
+      pending.resolve();
     }
-    this.diagnosticWaiters.clear();
+    this.pendingDiagnostics.clear();
   }
 
   // ── Hover ─────────────────────────────────────────────────────────────
 
   async hover(filePath: string, position: Position): Promise<Hover | null> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/hover', {
-      textDocument: { uri },
-      position,
-    });
-    return (result as Hover) ?? null;
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/hover', {
+          textDocument: { uri },
+          position,
+        });
+        return (result as Hover) ?? null;
+      },
+      (result) => result === null,
+    );
   }
 
   // ── Definition ────────────────────────────────────────────────────────
 
   async definition(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/definition', {
-      textDocument: { uri },
-      position,
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/definition', {
+          textDocument: { uri },
+          position,
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── References ────────────────────────────────────────────────────────
 
   async references(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/references', {
-      textDocument: { uri },
-      position,
-      context: { includeDeclaration: true },
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/references', {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: true },
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Implementation ────────────────────────────────────────────────────
 
   async implementation(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/implementation', {
-      textDocument: { uri },
-      position,
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/implementation', {
+          textDocument: { uri },
+          position,
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Document Symbols ──────────────────────────────────────────────────
 
   async documentSymbol(filePath: string): Promise<DocumentSymbol[] | SymbolInformation[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/documentSymbol', {
-      textDocument: { uri },
-    });
-    if (!Array.isArray(result)) return [];
-    return result as DocumentSymbol[] | SymbolInformation[];
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/documentSymbol', {
+          textDocument: { uri },
+        });
+        if (!Array.isArray(result)) return [];
+        return result as DocumentSymbol[] | SymbolInformation[];
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Workspace Symbols ─────────────────────────────────────────────────
 
   async workspaceSymbol(query: string): Promise<SymbolInformation[]> {
     await this.ensureInitialized();
-    const result = await this.connection.sendRequest('workspace/symbol', { query });
-    if (!Array.isArray(result)) return [];
-    return result as SymbolInformation[];
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('workspace/symbol', { query });
+        if (!Array.isArray(result)) return [];
+        return result as SymbolInformation[];
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Call Hierarchy ────────────────────────────────────────────────────

package/extensions/lsp/config.ts

@@ -21,7 +21,8 @@ import type { LspConfigFile, LspServerUserConfig, ResolvedServerConfig } from '.
 // ── Paths ───────────────────────────────────────────────────────────────────
 
 function globalConfigPath(): string {
-  return join(process.env.HOME ?? homedir(), '.pi', 'agent', 'extensions', 'lsp', 'config.json');
+  const home = process.platform === 'win32' ? homedir() : (process.env.HOME ?? homedir());
+  return join(home, '.pi', 'agent', 'extensions', 'lsp', 'config.json');
 }
 
 function projectConfigPath(cwd: string): string {

package/extensions/lsp/formatting.ts

@@ -186,8 +186,9 @@ function formatDocSymbolTree(symbols: DocumentSymbol[], indent: number): string[
   for (const sym of symbols) {
     const kind = symbolKindLabel(sym.kind);
     const line = sym.selectionRange.start.line + 1;
+    const col = sym.selectionRange.start.character + 1;
     const detail = sym.detail ? ` — ${sym.detail}` : '';
-    lines.push(`${prefix}${sym.name} (${kind}) line ${line}${detail}`);
+    lines.push(`${prefix}${sym.name} (${kind}) line ${line}:${col}${detail}`);
     if (sym.children?.length) {
       lines.push(...formatDocSymbolTree(sym.children, indent + 1));
     }
@@ -212,8 +213,9 @@ export function formatDocumentSymbols(
     const kind = symbolKindLabel(sym.kind);
     const p = relativePath(sym.location.uri, rootPath);
     const line = sym.location.range.start.line + 1;
+    const col = sym.location.range.start.character + 1;
     const container = sym.containerName ? ` in ${sym.containerName}` : '';
-    return `${i + 1}. ${sym.name} (${kind}) ${p}:${line}${container}`;
+    return `${i + 1}. ${sym.name} (${kind}) ${p}:${line}:${col}${container}`;
   });
 
   return `Symbols in ${filePath} (${symbols.length}):\n\n${formatted.join('\n')}`;
@@ -232,8 +234,9 @@ export function formatWorkspaceSymbols(
     const kind = symbolKindLabel(sym.kind);
     const p = relativePath(sym.location.uri, rootPath);
     const line = sym.location.range.start.line + 1;
+    const col = sym.location.range.start.character + 1;
     const container = sym.containerName ? ` in ${sym.containerName}` : '';
-    return `${i + 1}. ${sym.name} (${kind}) ${p}:${line}${container}`;
+    return `${i + 1}. ${sym.name} (${kind}) ${p}:${line}:${col}${container}`;
   });
 
   const truncated = symbols.length > 50 ? `\n\n(showing 50 of ${symbols.length})` : '';

package/extensions/lsp/retry.ts

@@ -0,0 +1,39 @@
+/**
+ * Retry utility for LSP operations that may return empty results during server indexing.
+ *
+ * Only retries when the server was recently initialized (within a configurable window),
+ * avoiding unnecessary delays for servers that are already warmed up.
+ */
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts. Default: 2 */
+  maxRetries?: number;
+  /** Delay between retries in milliseconds. Default: 2000 */
+  delayMs?: number;
+}
+
+/**
+ * Retry an async operation if the result is considered "empty".
+ *
+ * Useful for LSP operations that return empty results while the server is still indexing
+ * (e.g. workspaceSymbol, hover, definition, references).
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  isEmpty: (result: T) => boolean,
+  options?: RetryOptions,
+): Promise<T> {
+  const maxRetries = options?.maxRetries ?? 2;
+  const delayMs = options?.delayMs ?? 2000;
+
+  let result = await operation();
+  let attempt = 0;
+
+  while (isEmpty(result) && attempt < maxRetries) {
+    attempt++;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    result = await operation();
+  }
+
+  return result;
+}

package/extensions/lsp/tools.ts

@@ -103,12 +103,12 @@ export function registerLspTool(pi: ExtensionAPI, mgr: ServerManager) {
       '  findReferences    — find all references to a symbol',
       '  hover             — get type info and documentation for a symbol',
       '  diagnostics       — get type errors and lint warnings for a file',
-      '  documentSymbol    — get all symbols in a file',
+      '  documentSymbol    — get all symbols in a file (with line:column positions)',
       '  workspaceSymbol   — search for symbols across the workspace',
       '  goToImplementation — find implementations of an interface/abstract method',
       '  prepareCallHierarchy — get call hierarchy item at a position',
-      '  incomingCalls     — find callers of a function/method',
-      '  outgoingCalls     — find callees of a function/method',
+      '  incomingCalls     — find callers of a function/method (auto-prepares hierarchy)',
+      '  outgoingCalls     — find callees of a function/method (auto-prepares hierarchy)',
       '  codeActions       — get quick fixes and refactoring suggestions',
       '',
       'Parameters:',
@@ -117,14 +117,24 @@ export function registerLspTool(pi: ExtensionAPI, mgr: ServerManager) {
       '  line      — line number, 1-indexed (required for position-based operations)',
       '  character — column number, 1-indexed (required for position-based operations)',
       '  query     — search string (required for workspaceSymbol)',
+      '',
+      'Tips:',
+      '  — Position the character in the middle of the symbol name for best results.',
+      '  — Use hover before goToDefinition to quickly check signatures and docs.',
+      '  — workspaceSymbol may need a retry if the server is still indexing.',
     ].join('\n'),
     promptSnippet:
       'Interact with LSP servers for code intelligence: definitions, references, hover, diagnostics, symbols, call hierarchy, code actions',
     promptGuidelines: [
-      'Use `diagnostics` after editing files to check for type errors and lint issues.',
-      'Use `hover` to understand types, `goToDefinition` to navigate, `findReferences` before refactoring.',
-      'Line and character are 1-indexed — use the line numbers shown by the read tool.',
-      'LSP servers are auto-detected by file extension. Use /lsp to check status.',
+      'lsp line and character params are 1-indexed — use the values from the read tool or rg output directly.',
+      'lsp `hover` is the fastest way to get a function signature, type params, and doc comment — prefer it over `goToDefinition` for quick type inspection.',
+      'lsp `documentSymbol` returns line:column positions for each symbol — use those values directly for follow-up lsp operations.',
+      'For lsp position-based operations, place the character in the **middle** of the symbol name, not at the first character.',
+      'lsp `incomingCalls` and `outgoingCalls` automatically prepare the call hierarchy — no need to call `prepareCallHierarchy` first.',
+      'lsp `workspaceSymbol` may return empty results while the LSP server is still indexing. If it returns nothing, wait a few seconds and retry.',
+      'lsp `diagnostics` relies on server-pushed notifications which may be slow for some servers. For compiled languages (Rust, Go, C++), prefer running the compiler directly (e.g. `cargo check`, `go build`) for reliable error checking.',
+      'Use lsp for type info, macro-generated symbols, and cross-module navigation. Use rg for simple text search and file discovery — it is faster and needs no server.',
+      'lsp servers are auto-detected by file extension. Use /lsp to check status.',
     ],
     parameters: Type.Object({
       operation: StringEnum(LSP_OPERATIONS),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-lsp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Language-agnostic LSP code intelligence for pi — diagnostics, hover, definitions, references, symbols, and call hierarchy",
   "keywords": [
     "pi-package"

package/test/formatting.test.ts

@@ -96,8 +96,8 @@ describe('formatting', () => {
       '/repo',
     );
     expect(docSymbols).toContain('Symbols in src/foo.ts');
-    expect(docSymbols).toContain('Foo (class)');
-    expect(docSymbols).toContain('bar (method)');
+    expect(docSymbols).toContain('Foo (class) line 1:7');
+    expect(docSymbols).toContain('bar (method) line 3:3');
 
     const wsSymbols = formatWorkspaceSymbols(
       [
@@ -115,7 +115,7 @@ describe('formatting', () => {
       '/repo',
     );
     expect(wsSymbols).toContain('Workspace symbols matching "Foo"');
-    expect(wsSymbols).toContain('FooService (class) src/service.ts:12 in services');
+    expect(wsSymbols).toContain('FooService (class) src/service.ts:12:1 in services');
   });
 
   test('formats call hierarchy and code actions', () => {

package/test/mock-lsp-server.ts

@@ -243,20 +243,33 @@ function handleRequest(req: JsonRpcRequest) {
   }
 }
 
-function handleNotification(msg: JsonRpcNotification) {
-  if (msg.method === 'textDocument/didOpen' || msg.method === 'textDocument/didChange') {
-    const textDocument =
-      msg.method === 'textDocument/didOpen' ? msg.params?.textDocument : msg.params?.textDocument;
-    const text =
-      msg.method === 'textDocument/didOpen'
-        ? (msg.params?.textDocument?.text ?? '')
-        : (msg.params?.contentChanges?.[0]?.text ?? '');
-    lastUri = textDocument?.uri ?? lastUri;
-    sendDiagnostics(lastUri, text);
-  }
+function handleDocSync(uri: string, text: string) {
+  lastUri = uri;
+  sendDiagnostics(lastUri, text);
+}
 
-  if (msg.method === 'exit') {
-    process.exit(0);
+function handleNotification(msg: JsonRpcNotification) {
+  switch (msg.method) {
+    case 'textDocument/didOpen':
+      handleDocSync(
+        msg.params?.textDocument?.uri ?? lastUri,
+        msg.params?.textDocument?.text ?? '',
+      );
+      break;
+    case 'textDocument/didChange':
+      handleDocSync(
+        msg.params?.textDocument?.uri ?? lastUri,
+        msg.params?.contentChanges?.[0]?.text ?? '',
+      );
+      break;
+    case 'textDocument/didSave':
+      handleDocSync(
+        msg.params?.textDocument?.uri ?? lastUri,
+        msg.params?.text ?? '',
+      );
+      break;
+    case 'exit':
+      process.exit(0);
   }
 }
 

package/test/retry.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+
+import { withRetry } from '../extensions/lsp/retry';
+
+describe('withRetry', () => {
+  test('returns immediately when result is not empty', async () => {
+    let callCount = 0;
+    const result = await withRetry(
+      async () => {
+        callCount++;
+        return [1, 2, 3];
+      },
+      (r) => r.length === 0,
+      { maxRetries: 2, delayMs: 10 },
+    );
+
+    expect(result).toEqual([1, 2, 3]);
+    expect(callCount).toBe(1);
+  });
+
+  test('retries until result is not empty', async () => {
+    let callCount = 0;
+    const result = await withRetry(
+      async () => {
+        callCount++;
+        return callCount >= 3 ? ['found'] : [];
+      },
+      (r) => r.length === 0,
+      { maxRetries: 3, delayMs: 10 },
+    );
+
+    expect(result).toEqual(['found']);
+    expect(callCount).toBe(3);
+  });
+
+  test('stops at maxRetries and returns last empty result', async () => {
+    let callCount = 0;
+    const result = await withRetry(
+      async () => {
+        callCount++;
+        return [];
+      },
+      (r) => r.length === 0,
+      { maxRetries: 2, delayMs: 10 },
+    );
+
+    expect(result).toEqual([]);
+    expect(callCount).toBe(3); // 1 initial + 2 retries
+  });
+
+  test('works with null isEmpty check', async () => {
+    let callCount = 0;
+    const result = await withRetry(
+      async () => {
+        callCount++;
+        return callCount >= 2 ? { value: 'ok' } : null;
+      },
+      (r) => r === null,
+      { maxRetries: 3, delayMs: 10 },
+    );
+
+    expect(result).toEqual({ value: 'ok' });
+    expect(callCount).toBe(2);
+  });
+
+  test('uses default options when not provided', async () => {
+    let callCount = 0;
+    const result = await withRetry(
+      async () => {
+        callCount++;
+        return 'immediate';
+      },
+      (r) => r === '',
+    );
+
+    expect(result).toBe('immediate');
+    expect(callCount).toBe(1);
+  });
+});

package/test/tools.test.ts

@@ -3,6 +3,16 @@ import { describe, expect, test } from 'bun:test';
 import { registerLspTool } from '../extensions/lsp/tools';
 import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
 
+function emptyManager(overrides?: Record<string, any>) {
+  return {
+    clientsForFile: () => [],
+    clientForFileWithCapability: () => null,
+    anyClient: () => null,
+    getRootPath: () => '/repo',
+    ...overrides,
+  };
+}
+
 function captureTool() {
   let tool: ToolDefinition<any, any> | null = null;
   const fakePi = {
@@ -20,14 +30,22 @@ function captureTool() {
 }
 
 describe('unified lsp tool dispatch', () => {
+  test('all promptGuidelines mention lsp tool by name', () => {
+    const { register } = captureTool();
+    const tool = register(emptyManager());
+
+    const guidelines = (tool as any).promptGuidelines as string[] | undefined;
+    expect(guidelines).toBeTruthy();
+    expect(guidelines!.length).toBeGreaterThan(0);
+
+    for (const guideline of guidelines!) {
+      expect(guideline.toLowerCase()).toContain('lsp');
+    }
+  });
+
   test('validates required params by operation', async () => {
     const { register } = captureTool();
-    const tool = register({
-      clientsForFile: () => [],
-      clientForFileWithCapability: () => null,
-      anyClient: () => null,
-      getRootPath: () => '/repo',
-    });
+    const tool = register(emptyManager());
 
     await expect(
       tool.execute('1', { operation: 'hover' }, undefined as any, undefined, {} as any),
@@ -40,35 +58,34 @@ describe('unified lsp tool dispatch', () => {
 
   test('aggregates diagnostics from all matching clients', async () => {
     const { register } = captureTool();
-    const tool = register({
-      clientsForFile: () => [
-        {
-          config: { name: 'ts' },
-          getDiagnostics: async () => [
-            {
-              range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } },
-              severity: 1,
-              source: 'ts',
-              message: 'Type error',
-            },
-          ],
-        },
-        {
-          config: { name: 'eslint' },
-          getDiagnostics: async () => [
-            {
-              range: { start: { line: 1, character: 0 }, end: { line: 1, character: 3 } },
-              severity: 2,
-              source: 'eslint',
-              message: 'Lint warning',
-            },
-          ],
-        },
-      ],
-      clientForFileWithCapability: () => null,
-      anyClient: () => null,
-      getRootPath: () => '/repo',
-    });
+    const tool = register(
+      emptyManager({
+        clientsForFile: () => [
+          {
+            config: { name: 'ts' },
+            getDiagnostics: async () => [
+              {
+                range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } },
+                severity: 1,
+                source: 'ts',
+                message: 'Type error',
+              },
+            ],
+          },
+          {
+            config: { name: 'eslint' },
+            getDiagnostics: async () => [
+              {
+                range: { start: { line: 1, character: 0 }, end: { line: 1, character: 3 } },
+                severity: 2,
+                source: 'eslint',
+                message: 'Lint warning',
+              },
+            ],
+          },
+        ],
+      }),
+    );
 
     const result = await tool.execute(
       '1',
@@ -91,17 +108,16 @@ describe('unified lsp tool dispatch', () => {
   test('routes hover to first capable server and converts positions to zero-indexed', async () => {
     const calls: any[] = [];
     const { register } = captureTool();
-    const tool = register({
-      clientsForFile: () => [],
-      clientForFileWithCapability: () => ({
-        hover: async (filePath: string, pos: { line: number; character: number }) => {
-          calls.push({ filePath, pos });
-          return { contents: { kind: 'markdown', value: 'mock hover' } };
-        },
+    const tool = register(
+      emptyManager({
+        clientForFileWithCapability: () => ({
+          hover: async (filePath: string, pos: { line: number; character: number }) => {
+            calls.push({ filePath, pos });
+            return { contents: { kind: 'markdown', value: 'mock hover' } };
+          },
+        }),
       }),
-      anyClient: () => null,
-      getRootPath: () => '/repo',
-    });
+    );
 
     const result = await tool.execute(
       '1',
@@ -119,11 +135,10 @@ describe('unified lsp tool dispatch', () => {
 
   test('routes workspaceSymbol through anyClient', async () => {
     const { register } = captureTool();
-    const tool = register({
-      clientsForFile: () => [],
-      clientForFileWithCapability: () => null,
-      anyClient: () => ({
-        workspaceSymbol: async (query: string) => [
+    const tool = register(
+      emptyManager({
+        anyClient: () => ({
+          workspaceSymbol: async (query: string) => [
           {
             name: `${query}Service`,
             kind: 5,
@@ -135,8 +150,8 @@ describe('unified lsp tool dispatch', () => {
           },
         ],
       }),
-      getRootPath: () => '/repo',
-    });
+      }),
+    );
 
     const result = await tool.execute(
       '1',
@@ -154,12 +169,7 @@ describe('unified lsp tool dispatch', () => {
 
   test('errors when no capable server is found', async () => {
     const { register } = captureTool();
-    const tool = register({
-      clientsForFile: () => [],
-      clientForFileWithCapability: () => null,
-      anyClient: () => null,
-      getRootPath: () => '/repo',
-    });
+    const tool = register(emptyManager());
 
     await expect(
       tool.execute(
@@ -175,29 +185,28 @@ describe('unified lsp tool dispatch', () => {
   test('codeActions filters diagnostics to the requested line', async () => {
     const { register } = captureTool();
     const seenContexts: any[] = [];
-    const tool = register({
-      clientsForFile: () => [],
-      clientForFileWithCapability: () => ({
-        getDiagnostics: async () => [
-          {
-            range: { start: { line: 2, character: 0 }, end: { line: 2, character: 10 } },
-            severity: 1,
-            message: 'line 3 issue',
-          },
-          {
-            range: { start: { line: 5, character: 0 }, end: { line: 5, character: 10 } },
-            severity: 1,
-            message: 'line 6 issue',
+    const tool = register(
+      emptyManager({
+        clientForFileWithCapability: () => ({
+          getDiagnostics: async () => [
+            {
+              range: { start: { line: 2, character: 0 }, end: { line: 2, character: 10 } },
+              severity: 1,
+              message: 'line 3 issue',
+            },
+            {
+              range: { start: { line: 5, character: 0 }, end: { line: 5, character: 10 } },
+              severity: 1,
+              message: 'line 6 issue',
+            },
+          ],
+          codeActions: async (_filePath: string, range: any, context: any) => {
+            seenContexts.push({ range, context });
+            return [{ title: 'Fix it', kind: 'quickfix' }];
           },
-        ],
-        codeActions: async (_filePath: string, range: any, context: any) => {
-          seenContexts.push({ range, context });
-          return [{ title: 'Fix it', kind: 'quickfix' }];
-        },
+        }),
       }),
-      anyClient: () => null,
-      getRootPath: () => '/repo',
-    });
+    );
 
     const result = await tool.execute(
       '1',

package/test/typescript.integration.test.ts

@@ -6,6 +6,19 @@ import { fileURLToPath } from 'node:url';
 
 import { LspClient } from '../extensions/lsp/client';
 
+/** Resolve a package bin using Node/Bun module resolution (handles hoisting). */
+function resolveBin(pkg: string): string | null {
+  try {
+    const pkgJsonPath = fileURLToPath(import.meta.resolve(`${pkg}/package.json`));
+    const pkgJson = require(pkgJsonPath);
+    const bin = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin?.[pkg];
+    if (!bin) return null;
+    return resolve(dirname(pkgJsonPath), bin);
+  } catch {
+    return null;
+  }
+}
+
 const cleanup: string[] = [];
 
 async function makeFixtureWorkspace() {
@@ -80,8 +93,11 @@ afterEach(async () => {
 describe('real TypeScript integration', () => {
   test('typescript-language-server resolves diagnostics and navigation in a fixture workspace', async () => {
     const workspace = await makeFixtureWorkspace();
-    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-    const tsServerBin = join(packageRoot, 'node_modules', '.bin', 'typescript-language-server');
+    const tsServerBin = resolveBin('typescript-language-server');
+    if (!tsServerBin) {
+      console.log('Skipping: typescript-language-server not found');
+      return;
+    }
 
     const client = new LspClient(
       {