@mrclrchtr/supi-lsp 1.4.0 → 1.6.0

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,6 +64,7 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
 export { registerSettingsCommand } from "./settings/settings-command.ts";
 export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,6 +64,7 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
 export { registerSettingsCommand } from "./settings/settings-command.ts";
 export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}

package/node_modules/@mrclrchtr/supi-core/src/registry-utils.ts

@@ -5,8 +5,20 @@
 // Without this, each symlink path gets its own module copy and its own Map,
 // so registrations from one instance are invisible to consumers in another.
 
+import * as path from "node:path";
+
 const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
 
+function getGlobalRegistryMap<T>(name: string): Map<string, T> {
+  const key = Symbol.for(SYMBOL_PREFIX + name);
+  let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
+  if (!map) {
+    map = new Map<string, T>();
+    (globalThis as Record<symbol, unknown>)[key] = map;
+  }
+  return map;
+}
+
 /**
  * Create a named registry backed by `globalThis` + `Symbol.for`.
  *
@@ -18,16 +30,7 @@ const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
  * @returns An object with `register`, `getAll`, and `clear` functions.
  */
 export function createRegistry<T>(name: string) {
-  const key = Symbol.for(SYMBOL_PREFIX + name);
-
-  const getMap = (): Map<string, T> => {
-    let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
-    if (!map) {
-      map = new Map<string, T>();
-      (globalThis as Record<symbol, unknown>)[key] = map;
-    }
-    return map;
-  };
+  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
 
   return {
     /**
@@ -52,3 +55,32 @@ export function createRegistry<T>(name: string) {
     },
   };
 }
+
+/**
+ * Create a named session-state registry keyed by normalized cwd.
+ *
+ * This helper is intended for session-scoped runtime services that should be
+ * shared across duplicate jiti module instances while keeping package-specific
+ * state unions and convenience wrappers local to the calling package.
+ */
+export function createSessionStateRegistry<TState>(name: string) {
+  const getMap = (): Map<string, TState> => getGlobalRegistryMap<TState>(name);
+  const normalizeCwd = (cwd: string): string => path.resolve(cwd);
+
+  return {
+    /** Get the current state for one session cwd. */
+    get: (cwd: string): TState | undefined => {
+      return getMap().get(normalizeCwd(cwd));
+    },
+
+    /** Store the current state for one session cwd. */
+    set: (cwd: string, state: TState): void => {
+      getMap().set(normalizeCwd(cwd), state);
+    },
+
+    /** Clear the current state for one session cwd. */
+    clear: (cwd: string): void => {
+      getMap().delete(normalizeCwd(cwd));
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,8 +21,9 @@
     "!__tests__"
   ],
   "dependencies": {
+    "ignore": "^7.0.5",
     "typescript": "6.0.3",
-    "@mrclrchtr/supi-core": "1.4.0"
+    "@mrclrchtr/supi-core": "1.6.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/manager/manager-project-info.ts

@@ -1,6 +1,7 @@
 import type { LspClient } from "../client/client.ts";
 import type { ProjectServerInfo } from "../config/types.ts";
 import { displayRelativeFilePath } from "../summary.ts";
+import { getSupportedLspServerActions } from "../tool/tool-specs.ts";
 
 interface ProjectServerInfoInput {
   serverName: string;
@@ -28,22 +29,7 @@ export function buildProjectServerInfo(
     root: input.root,
     fileTypes: input.fileTypes,
     status,
-    supportedActions: getSupportedActions(input.client?.serverCapabilities),
+    supportedActions: getSupportedLspServerActions(input.client?.serverCapabilities),
     openFiles: input.client?.openFiles.map((file) => displayRelativeFilePath(file, cwd)) ?? [],
   };
 }
-
-function getSupportedActions(capabilities: LspClient["serverCapabilities"] | undefined): string[] {
-  if (!capabilities) return [];
-
-  const actions: string[] = ["diagnostics [optional file]"];
-  if (capabilities.hoverProvider) actions.push("hover(file,line,char)");
-  if (capabilities.definitionProvider) actions.push("definition(file,line,char)");
-  if (capabilities.referencesProvider) actions.push("references(file,line,char)");
-  if (capabilities.implementationProvider) actions.push("implementation(file,line,char)");
-  if (capabilities.documentSymbolProvider) actions.push("symbols(file)");
-  if (capabilities.workspaceSymbolProvider) actions.push("workspace_symbols(query)");
-  if (capabilities.renameProvider) actions.push("rename(file,line,char,newName)");
-  if (capabilities.codeActionProvider) actions.push("code_actions(file,line,char)");
-  return actions;
-}

package/src/pattern-matcher.ts

@@ -1,20 +1,15 @@
+import ignore from "ignore";
+
 /** Gitignore-style glob pattern matching for path exclusion.
  *
- * Supports:
- *  - Literal names at any depth: __tests__, build
- *  - Trailing slash directory-only: __tests__ + "/"
- *  - Leading slash root-anchored: "/" + build
- *  - Stars-star-slash recursive: e.g. `**` + "/" + fixtures
- *  - Asterisk single-segment wildcard: *.generated.ts
- *  - Literal paths: packages + "/" + legacy
- */
-
-/**
- * Normalize path separators to forward slashes and trim.
+ * Delegates to the {@link https://github.com/kaelzhang/node-ignore | ignore} package,
+ * which provides battle-tested .gitignore semantics used by ESLint, Prettier, and others.
+ *
+ * Supports full gitignore syntax: literal names, `*` / `?` wildcards, `**` recursive globs,
+ * leading `/` anchored patterns, trailing `/` directory-only patterns, and `!` negation.
+ *
+ * **Note:** Patterns that start with `#` are treated as comments unless escaped with `\#`.
  */
-function normalize(p: string): string {
-  return p.replaceAll("\\", "/").trim();
-}
 
 /**
  * Check whether a project-relative file path matches a gitignore-style glob pattern.
@@ -24,174 +19,6 @@ function normalize(p: string): string {
  * @returns `true` if the file path matches the pattern
  */
 export function isGlobMatch(filePath: string, pattern: string): boolean {
-  const fp = normalize(filePath);
-  const pat = normalize(pattern);
-  if (!fp || !pat) return false;
-
-  // Leading / → anchored to root
-  const anchored = pat.startsWith("/");
-  const noLeadingSlash = anchored ? pat.slice(1) : pat;
-
-  // Trailing / → directory-only
-  const dirOnly = noLeadingSlash.endsWith("/");
-  const cleanPat = dirOnly ? noLeadingSlash.slice(0, -1) : noLeadingSlash;
-
-  if (!cleanPat) return false;
-
-  return matchGlob(fp, cleanPat, { anchored, dirOnly });
-}
-
-interface MatchOptions {
-  anchored: boolean;
-  dirOnly: boolean;
-}
-
-/**
- * Core recursive pattern matching against a multi-segment path.
- */
-function matchGlob(filePath: string, pattern: string, opts: MatchOptions): boolean {
-  // Direct match
-  if (!opts.anchored && !opts.dirOnly && filePath === pattern) return true;
-
-  // Split into segments
-  const pathSegments = filePath.split("/");
-  const patternSegments = pattern.split("/");
-
-  // ** recursive glob
-  if (pattern.startsWith("**/")) {
-    const suffix = pattern.slice(3);
-    return (
-      matchGlob(filePath, suffix, { ...opts, anchored: false }) ||
-      starStarMatch(pathSegments, suffix)
-    );
-  }
-
-  // prefix/**/suffix bounded recursive glob
-  const dstarIdx = pattern.indexOf("/**/");
-  if (dstarIdx !== -1) {
-    const prefix = pattern.slice(0, dstarIdx);
-    const suffix = pattern.slice(dstarIdx + 4);
-    return matchBoundedStar(pathSegments, prefix, suffix);
-  }
-
-  // Single-segment patterns
-  if (patternSegments.length === 1 && !opts.anchored) {
-    return matchSingleSegment(pathSegments, patternSegments[0], opts.dirOnly);
-  }
-
-  // Multi-segment: anchored or unanchored
-  if (opts.anchored) {
-    return matchSegments(pathSegments, patternSegments, opts.dirOnly);
-  }
-
-  // Unanchored multi-segment: try at each starting position
-  return matchUnanchoredSegments(pathSegments, patternSegments, opts.dirOnly);
-}
-
-/**
- * Match a ** recursive suffix across directory levels.
- */
-function starStarMatch(segments: string[], suffix: string): boolean {
-  for (let i = 0; i < segments.length; i++) {
-    const remaining = segments.slice(i).join("/");
-    if (matchGlob(remaining, suffix, { anchored: false, dirOnly: false })) return true;
-  }
-  return false;
-}
-
-/** Match prefix plus star-star-slash plus suffix bounded recursive pattern. */
-function matchBoundedStar(segments: string[], prefix: string, suffix: string): boolean {
-  // Try to find a split point where left matches prefix and right matches suffix
-  for (let i = 1; i < segments.length; i++) {
-    const left = segments.slice(0, i).join("/");
-    const right = segments.slice(i).join("/");
-    if (
-      matchGlob(left, prefix, { anchored: false, dirOnly: false }) &&
-      matchGlob(right, suffix, { anchored: false, dirOnly: false })
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Match a single-segment pattern against path segments.
- */
-function matchSingleSegment(segments: string[], patternSeg: string, dirOnly: boolean): boolean {
-  const hasGlob = patternSeg.includes("*") || patternSeg.includes("?");
-
-  if (hasGlob) {
-    // Glob pattern matches any segment
-    return segments.some((seg) => simpleMatch(seg, patternSeg));
-  }
-
-  // Literal segment name
-  if (dirOnly) {
-    // Match as directory: any segment except the last (file) one
-    return segments.slice(0, -1).some((seg) => seg === patternSeg);
-  }
-
-  // Match any segment (file or directory)
-  return segments.some((seg) => seg === patternSeg);
-}
-
-/**
- * Try to match multi-segment pattern at each start position.
- */
-function matchUnanchoredSegments(segments: string[], pattern: string[], dirOnly: boolean): boolean {
-  for (let i = 0; i < segments.length; i++) {
-    if (matchSegments(segments.slice(i), pattern, dirOnly)) return true;
-  }
-  return false;
-}
-
-/** Match segments from start. Returns true if all pattern segments match contiguously. */
-function matchSegments(segments: string[], pattern: string[], dirOnly: boolean): boolean {
-  if (pattern.length > segments.length) return false;
-
-  for (let i = 0; i < pattern.length; i++) {
-    if (!matchSegmentAtIndex(segments, pattern, i)) return false;
-  }
-
-  // dirOnly: last matched segment must not be the last path segment
-  if (dirOnly && pattern.length === segments.length) return false;
-
-  return true;
-}
-
-/** Match a single pattern segment against the corresponding path segment. */
-function matchSegmentAtIndex(segments: string[], pattern: string[], index: number): boolean {
-  const patSeg = pattern[index];
-  const pathSeg = segments[index];
-
-  if (patSeg === "**") {
-    // ** at end matches all remaining segments
-    if (index === pattern.length - 1) return true;
-    // Try rest of pattern from various positions
-    for (let j = index; j < segments.length; j++) {
-      if (matchSegments(segments.slice(j), pattern.slice(index + 1), false)) return true;
-    }
-    return false;
-  }
-
-  return simpleMatch(pathSeg, patSeg);
-}
-
-/**
- * Match a single path segment against a single pattern segment.
- * Supports `*` (any chars except `/`) and `?` (single char).
- */
-function simpleMatch(segment: string, pattern: string): boolean {
-  if (pattern === "*") return true;
-  if (pattern === segment) return true;
-  if (!pattern.includes("*") && !pattern.includes("?")) return false;
-
-  // Convert pattern to simple regex
-  const regexStr = pattern
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replace(/\*/g, "[^/]*")
-    .replace(/\?/g, "[^/]");
-
-  return new RegExp(`^${regexStr}$`).test(segment);
+  if (!filePath || !pattern) return false;
+  return ignore().add(pattern).ignores(filePath);
 }

package/src/session/service-registry.ts

@@ -2,7 +2,7 @@
 // Peer extensions can import `getSessionLspService` from the package root
 // to reuse the active LSP runtime without starting duplicate servers.
 
-import * as path from "node:path";
+import { createSessionStateRegistry } from "@mrclrchtr/supi-core/api";
 import type {
   CodeAction,
   Diagnostic,
@@ -189,34 +189,18 @@ export class SessionLspService {
 
 // ── Registry ──────────────────────────────────────────────────────────
 
-const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-lsp/session-registry");
 const WAIT_INTERVAL_MS = 25;
-
-function getRegistry(): Map<string, SessionLspServiceState> {
-  const globalScope = globalThis as typeof globalThis & Record<symbol, unknown>;
-  const existing = globalScope[REGISTRY_KEY];
-  if (existing instanceof Map) return existing as Map<string, SessionLspServiceState>;
-
-  const registry = new Map<string, SessionLspServiceState>();
-  globalScope[REGISTRY_KEY] = registry;
-  return registry;
-}
-
-function normalizeCwd(cwd: string): string {
-  return path.resolve(cwd);
-}
-
-const registry = getRegistry();
+const registry = createSessionStateRegistry<SessionLspServiceState>("supi-lsp/session-registry");
 
 /** Publish the LSP service state for a session cwd. */
 export function setSessionLspServiceState(cwd: string, state: SessionLspServiceState): void {
-  registry.set(normalizeCwd(cwd), state);
+  registry.set(cwd, state);
 }
 
 /** Acquire the LSP service state for a session cwd. */
 export function getSessionLspService(cwd: string): SessionLspServiceState {
   return (
-    registry.get(normalizeCwd(cwd)) ?? {
+    registry.get(cwd) ?? {
       kind: "unavailable",
       reason: "No LSP session initialized for this workspace",
     }
@@ -241,5 +225,5 @@ export async function waitForSessionLspService(
 
 /** Remove the LSP service state for a session cwd. */
 export function clearSessionLspService(cwd: string): void {
-  registry.delete(normalizeCwd(cwd));
+  registry.clear(cwd);
 }

package/src/tool/guidance.ts

@@ -2,15 +2,8 @@
 
 import * as path from "node:path";
 import type { ProjectServerInfo } from "../config/types.ts";
-import {
-  LSP_DIAGNOSTICS_TOOL,
-  LSP_DOCUMENT_SYMBOLS_TOOL,
-  LSP_LOOKUP_TOOL,
-  LSP_RECOVER_TOOL,
-  LSP_REFACTOR_TOOL,
-  LSP_WORKSPACE_SYMBOLS_TOOL,
-  type LspToolName,
-} from "./names.ts";
+import { LSP_LOOKUP_TOOL, type LspToolName } from "./names.ts";
+import { LSP_TOOL_DEFINITION_SPECS } from "./tool-specs.ts";
 
 export interface LspToolPromptSurface {
   description: string;
@@ -20,33 +13,6 @@ export interface LspToolPromptSurface {
 
 export type LspToolPromptSurfaceMap = Record<LspToolName, LspToolPromptSurface>;
 
-const LOOKUP_GUIDELINES = [
-  'Use lsp_lookup with `kind: "hover"` for semantic type or symbol information at a known `file`, `line`, and `character`.',
-  'Use lsp_lookup with `kind: "definition"`, `"references"`, or `"implementation"` for semantic navigation at a known position.',
-  "Use lsp_lookup after code_intel or tree_sitter has already narrowed the target file and position.",
-];
-
-const DOCUMENT_SYMBOL_GUIDELINES = [
-  "Use lsp_document_symbols(file) for semantic declarations in one supported file.",
-];
-
-const WORKSPACE_SYMBOL_GUIDELINES = [
-  "Use lsp_workspace_symbols(query) for semantic symbol-name lookup across the current project.",
-];
-
-const DIAGNOSTICS_GUIDELINES = [
-  "Use lsp_diagnostics(file?) when you need current diagnostics for one file or a workspace-level summary.",
-];
-
-const REFACTOR_GUIDELINES = [
-  'Use lsp_refactor with `kind: "rename"` for semantic rename planning at a known `file`, `line`, and `character`.',
-  'Use lsp_refactor with `kind: "code_actions"` for semantic fixes or refactors at a known position.',
-];
-
-const RECOVER_GUIDELINES = [
-  "Use lsp_recover() when diagnostics look stale after workspace-level changes or generated-file updates.",
-];
-
 export const defaultLspToolPromptSurfaces = buildLspToolPromptSurfaces([], ".");
 
 export function buildLspToolPromptSurfaces(
@@ -55,45 +21,19 @@ export function buildLspToolPromptSurfaces(
 ): LspToolPromptSurfaceMap {
   const coverageGuidelines = buildCoverageGuidelines(servers, cwd);
 
-  return {
-    [LSP_LOOKUP_TOOL]: {
-      description:
-        "Language Server Protocol lookup tool — semantic hover, definition, references, and implementation for supported files. Use lsp_lookup when you know the file and 1-based line/character position and need semantic drill-down rather than text search.",
-      promptSnippet:
-        "lsp_lookup — semantic hover/definition/references/implementation at a known file position",
-      promptGuidelines: [...LOOKUP_GUIDELINES, ...coverageGuidelines],
-    },
-    [LSP_DOCUMENT_SYMBOLS_TOOL]: {
-      description:
-        "Language Server Protocol document symbols tool — list semantic declarations in one supported file. Use lsp_document_symbols when you need a symbol-aware outline rather than raw text structure.",
-      promptSnippet: "lsp_document_symbols — semantic declarations for one supported file",
-      promptGuidelines: DOCUMENT_SYMBOL_GUIDELINES,
-    },
-    [LSP_WORKSPACE_SYMBOLS_TOOL]: {
-      description:
-        "Language Server Protocol workspace symbols tool — semantic symbol-name lookup across the current project. Use lsp_workspace_symbols to find declarations by name before opening a specific file.",
-      promptSnippet: "lsp_workspace_symbols — semantic symbol-name lookup across the project",
-      promptGuidelines: WORKSPACE_SYMBOL_GUIDELINES,
-    },
-    [LSP_DIAGNOSTICS_TOOL]: {
-      description:
-        "Language Server Protocol diagnostics tool — current diagnostics for one file or a workspace summary. Use lsp_diagnostics for semantic compiler or language-server issues instead of guessing from text alone.",
-      promptSnippet: "lsp_diagnostics — current diagnostics for one file or the workspace",
-      promptGuidelines: DIAGNOSTICS_GUIDELINES,
-    },
-    [LSP_REFACTOR_TOOL]: {
-      description:
-        "Language Server Protocol refactor tool — semantic rename planning and code actions at a known file position. Use lsp_refactor when you need language-server-backed edits or quick-fix suggestions.",
-      promptSnippet: "lsp_refactor — semantic rename planning and code actions at a known position",
-      promptGuidelines: REFACTOR_GUIDELINES,
-    },
-    [LSP_RECOVER_TOOL]: {
-      description:
-        "Language Server Protocol recover tool — refresh diagnostics after workspace changes and stale language-server state. Use lsp_recover when new files, generated types, or config updates leave diagnostics out of sync.",
-      promptSnippet: "lsp_recover — refresh stale diagnostics after workspace changes",
-      promptGuidelines: RECOVER_GUIDELINES,
-    },
-  };
+  return Object.fromEntries(
+    LSP_TOOL_DEFINITION_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines:
+          "includeCoverageGuidelines" in spec && spec.includeCoverageGuidelines
+            ? [...spec.basePromptGuidelines, ...coverageGuidelines]
+            : [...spec.basePromptGuidelines],
+      } satisfies LspToolPromptSurface,
+    ]),
+  ) as LspToolPromptSurfaceMap;
 }
 
 function buildCoverageGuidelines(servers: ProjectServerInfo[], cwd: string): string[] {

package/src/tool/register-tools.ts

@@ -1,160 +1,22 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import { getSessionLspService } from "../session/service-registry.ts";
 import type { LspToolPromptSurfaceMap } from "./guidance.ts";
-import {
-  LSP_DIAGNOSTICS_TOOL,
-  LSP_DOCUMENT_SYMBOLS_TOOL,
-  LSP_LOOKUP_TOOL,
-  LSP_RECOVER_TOOL,
-  LSP_REFACTOR_TOOL,
-  LSP_WORKSPACE_SYMBOLS_TOOL,
-} from "./names.ts";
-import {
-  executeDiagnostics,
-  executeDocumentSymbols,
-  executeLookup,
-  executeRecover,
-  executeRefactor,
-  executeWorkspaceSymbols,
-} from "./service-actions.ts";
-
-const FileParam = Type.String({ description: "File path (relative or absolute)" });
-const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
-const CharacterParam = Type.Number({ description: "1-based column number", minimum: 1 });
-const QueryParam = Type.String({ description: "Symbol query string" });
-const NewNameParam = Type.String({ description: "New name for rename" });
-
-const LookupKindEnum = StringEnum(["hover", "definition", "references", "implementation"] as const);
-
-const RefactorKindEnum = StringEnum(["rename", "code_actions"] as const);
-
-const LookupParameters = Type.Object(
-  {
-    kind: LookupKindEnum,
-    file: FileParam,
-    line: LineParam,
-    character: CharacterParam,
-  },
-  { additionalProperties: false },
-);
-
-const DocumentSymbolsParameters = Type.Object(
-  {
-    file: FileParam,
-  },
-  { additionalProperties: false },
-);
-
-const WorkspaceSymbolsParameters = Type.Object(
-  {
-    query: QueryParam,
-  },
-  { additionalProperties: false },
-);
-
-const DiagnosticsParameters = Type.Object(
-  {
-    file: Type.Optional(FileParam),
-  },
-  { additionalProperties: false },
-);
-
-const RefactorParameters = Type.Object(
-  {
-    kind: RefactorKindEnum,
-    file: FileParam,
-    line: LineParam,
-    character: CharacterParam,
-    newName: Type.Optional(NewNameParam),
-  },
-  { additionalProperties: false },
-);
-
-const RecoverParameters = Type.Object({}, { additionalProperties: false });
+import { LSP_TOOL_DEFINITION_SPECS } from "./tool-specs.ts";
 
 /** Register the expert LSP toolset. Tools are re-registered on session_start to refresh guidance. */
 export function registerLspTools(pi: ExtensionAPI, promptSurfaces: LspToolPromptSurfaceMap): void {
-  const lookupSurface = promptSurfaces[LSP_LOOKUP_TOOL];
-  pi.registerTool({
-    name: LSP_LOOKUP_TOOL,
-    label: "LSP Lookup",
-    description: lookupSurface.description,
-    promptSnippet: lookupSurface.promptSnippet,
-    promptGuidelines: lookupSurface.promptGuidelines,
-    parameters: LookupParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeLookup(service, cwd, params as Parameters<typeof executeLookup>[2]),
-    ),
-  });
-
-  const documentSymbolsSurface = promptSurfaces[LSP_DOCUMENT_SYMBOLS_TOOL];
-  pi.registerTool({
-    name: LSP_DOCUMENT_SYMBOLS_TOOL,
-    label: "LSP Document Symbols",
-    description: documentSymbolsSurface.description,
-    promptSnippet: documentSymbolsSurface.promptSnippet,
-    promptGuidelines: documentSymbolsSurface.promptGuidelines,
-    parameters: DocumentSymbolsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeDocumentSymbols(service, cwd, params as Parameters<typeof executeDocumentSymbols>[2]),
-    ),
-  });
-
-  const workspaceSymbolsSurface = promptSurfaces[LSP_WORKSPACE_SYMBOLS_TOOL];
-  pi.registerTool({
-    name: LSP_WORKSPACE_SYMBOLS_TOOL,
-    label: "LSP Workspace Symbols",
-    description: workspaceSymbolsSurface.description,
-    promptSnippet: workspaceSymbolsSurface.promptSnippet,
-    promptGuidelines: workspaceSymbolsSurface.promptGuidelines,
-    parameters: WorkspaceSymbolsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeWorkspaceSymbols(
-        service,
-        cwd,
-        params as Parameters<typeof executeWorkspaceSymbols>[2],
-      ),
-    ),
-  });
-
-  const diagnosticsSurface = promptSurfaces[LSP_DIAGNOSTICS_TOOL];
-  pi.registerTool({
-    name: LSP_DIAGNOSTICS_TOOL,
-    label: "LSP Diagnostics",
-    description: diagnosticsSurface.description,
-    promptSnippet: diagnosticsSurface.promptSnippet,
-    promptGuidelines: diagnosticsSurface.promptGuidelines,
-    parameters: DiagnosticsParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeDiagnostics(service, cwd, params as Parameters<typeof executeDiagnostics>[2]),
-    ),
-  });
-
-  const refactorSurface = promptSurfaces[LSP_REFACTOR_TOOL];
-  pi.registerTool({
-    name: LSP_REFACTOR_TOOL,
-    label: "LSP Refactor",
-    description: refactorSurface.description,
-    promptSnippet: refactorSurface.promptSnippet,
-    promptGuidelines: refactorSurface.promptGuidelines,
-    parameters: RefactorParameters,
-    execute: createToolExecutor((service, cwd, params) =>
-      executeRefactor(service, cwd, params as Parameters<typeof executeRefactor>[2]),
-    ),
-  });
-
-  const recoverSurface = promptSurfaces[LSP_RECOVER_TOOL];
-  pi.registerTool({
-    name: LSP_RECOVER_TOOL,
-    label: "LSP Recover",
-    description: recoverSurface.description,
-    promptSnippet: recoverSurface.promptSnippet,
-    promptGuidelines: recoverSurface.promptGuidelines,
-    parameters: RecoverParameters,
-    execute: createRecoverToolExecutor(),
-  });
+  for (const spec of LSP_TOOL_DEFINITION_SPECS) {
+    const surface = promptSurfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface.description,
+      promptSnippet: surface.promptSnippet,
+      promptGuidelines: surface.promptGuidelines,
+      parameters: spec.parameters,
+      execute: createToolExecutor(spec.run),
+    });
+  }
 }
 
 function getReadyService(cwd: string) {
@@ -201,21 +63,6 @@ function createToolExecutor(
   };
 }
 
-function createRecoverToolExecutor() {
-  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-  return async (
-    _toolCallId: string,
-    _params: unknown,
-    _signal: AbortSignal | undefined,
-    _onUpdate: unknown,
-    ctx: ExtensionContext,
-  ) => {
-    const service = getReadyService(ctx.cwd);
-    const text = service ? await executeRecover(service) : describeUnavailableService(ctx.cwd);
-    return makeTextResult(text);
-  };
-}
-
 function makeTextResult(text: string) {
   return {
     content: [{ type: "text" as const, text }],

package/src/tool/tool-specs.ts

@@ -0,0 +1,248 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import type { ServerCapabilities } from "../config/types.ts";
+import type { SessionLspService } from "../session/service-registry.ts";
+import {
+  LSP_DIAGNOSTICS_TOOL,
+  LSP_DOCUMENT_SYMBOLS_TOOL,
+  LSP_LOOKUP_TOOL,
+  LSP_RECOVER_TOOL,
+  LSP_REFACTOR_TOOL,
+  LSP_WORKSPACE_SYMBOLS_TOOL,
+  type LspToolName,
+} from "./names.ts";
+import {
+  executeDiagnostics,
+  executeDocumentSymbols,
+  executeLookup,
+  executeRecover,
+  executeRefactor,
+  executeWorkspaceSymbols,
+} from "./service-actions.ts";
+
+const FileParam = Type.String({ description: "File path (relative or absolute)" });
+const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+const CharacterParam = Type.Number({ description: "1-based column number", minimum: 1 });
+const QueryParam = Type.String({ description: "Symbol query string" });
+const NewNameParam = Type.String({ description: "New name for rename" });
+
+export const LSP_LOOKUP_KIND_NAMES = [
+  "hover",
+  "definition",
+  "references",
+  "implementation",
+] as const;
+export const LSP_REFACTOR_KIND_NAMES = ["rename", "code_actions"] as const;
+
+const LookupKindEnum = StringEnum(LSP_LOOKUP_KIND_NAMES);
+const RefactorKindEnum = StringEnum(LSP_REFACTOR_KIND_NAMES);
+
+const LookupParameters = Type.Object(
+  {
+    kind: LookupKindEnum,
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+  },
+  { additionalProperties: false },
+);
+
+const DocumentSymbolsParameters = Type.Object(
+  {
+    file: FileParam,
+  },
+  { additionalProperties: false },
+);
+
+const WorkspaceSymbolsParameters = Type.Object(
+  {
+    query: QueryParam,
+  },
+  { additionalProperties: false },
+);
+
+const DiagnosticsParameters = Type.Object(
+  {
+    file: Type.Optional(FileParam),
+  },
+  { additionalProperties: false },
+);
+
+const RefactorParameters = Type.Object(
+  {
+    kind: RefactorKindEnum,
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+    newName: Type.Optional(NewNameParam),
+  },
+  { additionalProperties: false },
+);
+
+const RecoverParameters = Type.Object({}, { additionalProperties: false });
+
+export interface LspToolDefinitionSpec {
+  name: LspToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  basePromptGuidelines: string[];
+  parameters: TSchema;
+  run: (service: SessionLspService, cwd: string, params: unknown) => Promise<string>;
+  includeCoverageGuidelines?: boolean;
+}
+
+export const LSP_TOOL_DEFINITION_SPECS = [
+  {
+    name: LSP_LOOKUP_TOOL,
+    label: "LSP Lookup",
+    description:
+      "Language Server Protocol lookup tool — semantic hover, definition, references, and implementation for supported files. Use lsp_lookup when you know the file and 1-based line/character position and need semantic drill-down rather than text search.",
+    promptSnippet:
+      "lsp_lookup — semantic hover/definition/references/implementation at a known file position",
+    basePromptGuidelines: [
+      'Use lsp_lookup with `kind: "hover"` for semantic type or symbol information at a known `file`, `line`, and `character`.',
+      'Use lsp_lookup with `kind: "definition"`, `"references"`, or `"implementation"` for semantic navigation at a known position.',
+      "Use lsp_lookup after code_intel or tree_sitter has already narrowed the target file and position.",
+    ],
+    parameters: LookupParameters,
+    run: (service, cwd, params) =>
+      executeLookup(service, cwd, params as Parameters<typeof executeLookup>[2]),
+    includeCoverageGuidelines: true,
+  },
+  {
+    name: LSP_DOCUMENT_SYMBOLS_TOOL,
+    label: "LSP Document Symbols",
+    description:
+      "Language Server Protocol document symbols tool — list semantic declarations in one supported file. Use lsp_document_symbols when you need a symbol-aware outline rather than raw text structure.",
+    promptSnippet: "lsp_document_symbols — semantic declarations for one supported file",
+    basePromptGuidelines: [
+      "Use lsp_document_symbols(file) for semantic declarations in one supported file.",
+    ],
+    parameters: DocumentSymbolsParameters,
+    run: (service, cwd, params) =>
+      executeDocumentSymbols(service, cwd, params as Parameters<typeof executeDocumentSymbols>[2]),
+  },
+  {
+    name: LSP_WORKSPACE_SYMBOLS_TOOL,
+    label: "LSP Workspace Symbols",
+    description:
+      "Language Server Protocol workspace symbols tool — semantic symbol-name lookup across the current project. Use lsp_workspace_symbols to find declarations by name before opening a specific file.",
+    promptSnippet: "lsp_workspace_symbols — semantic symbol-name lookup across the project",
+    basePromptGuidelines: [
+      "Use lsp_workspace_symbols(query) for semantic symbol-name lookup across the current project.",
+    ],
+    parameters: WorkspaceSymbolsParameters,
+    run: (service, cwd, params) =>
+      executeWorkspaceSymbols(
+        service,
+        cwd,
+        params as Parameters<typeof executeWorkspaceSymbols>[2],
+      ),
+  },
+  {
+    name: LSP_DIAGNOSTICS_TOOL,
+    label: "LSP Diagnostics",
+    description:
+      "Language Server Protocol diagnostics tool — current diagnostics for one file or a workspace summary. Use lsp_diagnostics for semantic compiler or language-server issues instead of guessing from text alone.",
+    promptSnippet: "lsp_diagnostics — current diagnostics for one file or the workspace",
+    basePromptGuidelines: [
+      "Use lsp_diagnostics(file?) when you need current diagnostics for one file or a workspace-level summary.",
+    ],
+    parameters: DiagnosticsParameters,
+    run: (service, cwd, params) =>
+      executeDiagnostics(service, cwd, params as Parameters<typeof executeDiagnostics>[2]),
+  },
+  {
+    name: LSP_REFACTOR_TOOL,
+    label: "LSP Refactor",
+    description:
+      "Language Server Protocol refactor tool — semantic rename planning and code actions at a known file position. Use lsp_refactor when you need language-server-backed edits or quick-fix suggestions.",
+    promptSnippet: "lsp_refactor — semantic rename planning and code actions at a known position",
+    basePromptGuidelines: [
+      'Use lsp_refactor with `kind: "rename"` for semantic rename planning at a known `file`, `line`, and `character`.',
+      'Use lsp_refactor with `kind: "code_actions"` for semantic fixes or refactors at a known position.',
+    ],
+    parameters: RefactorParameters,
+    run: (service, cwd, params) =>
+      executeRefactor(service, cwd, params as Parameters<typeof executeRefactor>[2]),
+  },
+  {
+    name: LSP_RECOVER_TOOL,
+    label: "LSP Recover",
+    description:
+      "Language Server Protocol recover tool — refresh diagnostics after workspace changes and stale language-server state. Use lsp_recover when new files, generated types, or config updates leave diagnostics out of sync.",
+    promptSnippet: "lsp_recover — refresh stale diagnostics after workspace changes",
+    basePromptGuidelines: [
+      "Use lsp_recover() when diagnostics look stale after workspace-level changes or generated-file updates.",
+    ],
+    parameters: RecoverParameters,
+    run: (service) => executeRecover(service),
+  },
+] as const satisfies readonly LspToolDefinitionSpec[];
+
+const LSP_TOOL_SPEC_MAP = new Map<LspToolName, LspToolDefinitionSpec>(
+  LSP_TOOL_DEFINITION_SPECS.map((spec) => [spec.name, spec]),
+);
+
+export function getLspToolDefinitionSpec(toolName: LspToolName): LspToolDefinitionSpec {
+  const spec = LSP_TOOL_SPEC_MAP.get(toolName);
+  if (!spec) {
+    throw new Error(`Unknown LSP tool: ${toolName}`);
+  }
+  return spec;
+}
+
+interface LspServerSupportedActionSpec {
+  label: string;
+  isSupported: (capabilities: ServerCapabilities | null | undefined) => boolean;
+}
+
+const LSP_SERVER_SUPPORTED_ACTION_SPECS: readonly LspServerSupportedActionSpec[] = [
+  {
+    label: "diagnostics [optional file]",
+    isSupported: () => true,
+  },
+  {
+    label: "hover(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.hoverProvider),
+  },
+  {
+    label: "definition(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.definitionProvider),
+  },
+  {
+    label: "references(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.referencesProvider),
+  },
+  {
+    label: "implementation(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.implementationProvider),
+  },
+  {
+    label: "symbols(file)",
+    isSupported: (capabilities) => Boolean(capabilities?.documentSymbolProvider),
+  },
+  {
+    label: "workspace_symbols(query)",
+    isSupported: (capabilities) => Boolean(capabilities?.workspaceSymbolProvider),
+  },
+  {
+    label: "rename(file,line,char,newName)",
+    isSupported: (capabilities) => Boolean(capabilities?.renameProvider),
+  },
+  {
+    label: "code_actions(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.codeActionProvider),
+  },
+] as const;
+
+export function getSupportedLspServerActions(
+  capabilities: ServerCapabilities | null | undefined,
+): string[] {
+  if (!capabilities) return [];
+
+  return LSP_SERVER_SUPPORTED_ACTION_SPECS.filter((spec) => spec.isSupported(capabilities)).map(
+    (spec) => spec.label,
+  );
+}

package/src/utils.ts

@@ -2,41 +2,12 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-// ── URI Handling ──────────────────────────────────────────────────────
 
-/** Convert a file path to a file:// URI. */
-export function fileToUri(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  if (process.platform === "win32") {
-    return `file:///${resolved.replace(/\\/g, "/")}`;
-  }
-  return `file://${resolved}`;
-}
-
-/** Convert a file:// URI to a file path. */
-export function uriToFile(uri: string): string {
-  if (!uri.startsWith("file://")) return uri;
-  let filePath = decodeURIComponent(uri.slice(7));
-  if (
-    process.platform === "win32" &&
-    filePath.startsWith("/") &&
-    /^[A-Za-z]:/.test(filePath.slice(1))
-  ) {
-    filePath = filePath.slice(1);
-  }
-  return filePath;
-}
-
-/**
- * Resolve a tool-style file path against the active session cwd.
- *
- * Built-in pi file tools accept a leading `@` prefix in path arguments, so LSP
- * helpers strip that prefix as well before resolving relative paths.
- */
-export function resolveSessionPath(cwd: string, filePath: string): string {
-  const normalizedPath = filePath.startsWith("@") ? filePath.slice(1) : filePath;
-  return path.resolve(cwd, normalizedPath);
-}
+export {
+  fileToUri,
+  resolveToolPath as resolveSessionPath,
+  uriToFile,
+} from "@mrclrchtr/supi-core/api";
 
 // ── Language ID Detection ─────────────────────────────────────────────