@mrclrchtr/supi-lsp 1.3.0 → 1.4.0

package/src/{settings-registration.ts → session/settings-registration.ts}

@@ -8,7 +8,7 @@ import {
   loadSupiConfigForScope,
   registerConfigSettings,
 } from "@mrclrchtr/supi-core/api";
-import { loadConfig } from "./config.ts";
+import { loadConfig } from "../config/config.ts";
 
 // ── Types ────────────────────────────────────────────────────
 

package/src/session/tree-persist.ts

@@ -0,0 +1,75 @@
+// LSP tree navigation persistence — restores tool activation state across /tree navigation.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { LspManager } from "../manager/manager.ts";
+import { LSP_TOOL_NAMES } from "../tool/names.ts";
+import { SessionLspService, setSessionLspServiceState } from "./service-registry.ts";
+
+/** Shape of the entry persisted via `pi.appendEntry()`. */
+export interface LspStateEntry {
+  active: boolean;
+}
+
+/** Restore LSP activation state from the current branch after /tree navigation. */
+export function registerTreePersistHandlers(
+  pi: ExtensionAPI,
+  state: { lspActive: boolean; manager?: LspManager | null },
+): void {
+  pi.on("session_tree", async (_event, ctx) => {
+    const branch = ctx.sessionManager.getBranch();
+    const isActive = findLastLspState(branch)?.active === true;
+
+    syncBranchToolActivation(pi, isActive);
+    syncBranchServiceState(state.manager, isActive);
+    state.lspActive = isActive;
+  });
+}
+
+function findLastLspState(branch: Array<{ type: string; customType?: string; data?: unknown }>) {
+  let lastEntry: LspStateEntry | undefined;
+  for (const entry of branch) {
+    if (entry.type === "custom" && entry.customType === "lsp-active") {
+      lastEntry = entry.data as LspStateEntry | undefined;
+    }
+  }
+  return lastEntry;
+}
+
+function syncBranchToolActivation(pi: ExtensionAPI, isActive: boolean): void {
+  const activeTools = pi.getActiveTools();
+  if (isActive) {
+    const missing = LSP_TOOL_NAMES.filter((toolName) => !activeTools.includes(toolName));
+    if (missing.length > 0) {
+      pi.setActiveTools([...activeTools, ...missing]);
+    }
+    return;
+  }
+
+  const nextTools = activeTools.filter(
+    (toolName) => !LSP_TOOL_NAMES.includes(toolName as (typeof LSP_TOOL_NAMES)[number]),
+  );
+  if (nextTools.length !== activeTools.length) {
+    pi.setActiveTools(nextTools);
+  }
+}
+
+function syncBranchServiceState(manager: LspManager | null | undefined, isActive: boolean): void {
+  if (!manager) return;
+
+  setSessionLspServiceState(manager.getCwd(), {
+    kind: isActive ? "ready" : "inactive",
+    service: new SessionLspService(manager),
+  });
+}
+
+/** Persist that LSP is active in the session tree. */
+export function persistLspActiveState(pi: ExtensionAPI, state: { lspActive: boolean }): void {
+  state.lspActive = true;
+  pi.appendEntry<LspStateEntry>("lsp-active", { active: true });
+}
+
+/** Persist that LSP is inactive in the session tree. */
+export function persistLspInactiveState(pi: ExtensionAPI, state: { lspActive: boolean }): void {
+  state.lspActive = false;
+  pi.appendEntry<LspStateEntry>("lsp-active", { active: false });
+}

package/src/summary.ts

@@ -84,7 +84,7 @@ export function isPathRelevant(filePath: string, relevantPaths: string[], cwd: s
   });
 }
 
-import { isFileExcludedByTsconfig } from "./tsconfig-scope.ts";
+import { isFileExcludedByTsconfig } from "./config/tsconfig-scope.ts";
 
 /** Check whether a file path is inside the project tree (within cwd, not node_modules/.pnpm/out-of-tree).
  *  Does NOT check tsconfig exclusion — use `shouldIgnoreLspPath` for diagnostics/guidance filtering. */

package/src/tool/guidance.ts

@@ -0,0 +1,138 @@
+// Prompt guidance and tool descriptions for the expert LSP toolset.
+
+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";
+
+export interface LspToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+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(
+  servers: ProjectServerInfo[],
+  cwd: string,
+): 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,
+    },
+  };
+}
+
+function buildCoverageGuidelines(servers: ProjectServerInfo[], cwd: string): string[] {
+  const active = servers
+    .filter((server) => server.status === "running")
+    .map((server) => {
+      const root = displayRoot(server.root, cwd);
+      const fileTypes = server.fileTypes.map((entry) => `.${entry}`).join(",");
+      const actions = server.supportedActions.join(",");
+      const actionText = actions.length > 0 ? ` | actions: ${actions}` : "";
+      return `lsp server coverage: ${server.name} | root: ${root} | files: ${fileTypes}${actionText}`;
+    });
+
+  const unavailable = servers
+    .filter((server) => server.status !== "running")
+    .map((server) => server.name);
+
+  const dynamic = [...active];
+  if (unavailable.length > 0) {
+    dynamic.push(
+      `lsp server unavailable: ${unavailable.join(",")} — install or enable to extend semantic coverage`,
+    );
+  }
+
+  return dynamic;
+}
+
+function displayRoot(root: string, cwd: string): string {
+  const relative = path.relative(cwd, root);
+  if (relative === "") return ".";
+  if (relative.startsWith(`..${path.sep}`) || relative === "..") return root;
+  return relative.replaceAll(path.sep, "/");
+}
+
+// Compatibility exports for older internal tests and helper imports.
+export const toolDescription = defaultLspToolPromptSurfaces[LSP_LOOKUP_TOOL].description;
+export const promptSnippet = defaultLspToolPromptSurfaces[LSP_LOOKUP_TOOL].promptSnippet;
+export const promptGuidelines = defaultLspToolPromptSurfaces[LSP_LOOKUP_TOOL].promptGuidelines;
+
+export function buildProjectGuidelines(servers: ProjectServerInfo[], cwd: string): string[] {
+  return buildLspToolPromptSurfaces(servers, cwd)[LSP_LOOKUP_TOOL].promptGuidelines;
+}

package/src/tool/names.ts

@@ -0,0 +1,19 @@
+// Stable LSP tool names shared across registration, guidance, and runtime state.
+
+export const LSP_LOOKUP_TOOL = "lsp_lookup";
+export const LSP_DOCUMENT_SYMBOLS_TOOL = "lsp_document_symbols";
+export const LSP_WORKSPACE_SYMBOLS_TOOL = "lsp_workspace_symbols";
+export const LSP_DIAGNOSTICS_TOOL = "lsp_diagnostics";
+export const LSP_REFACTOR_TOOL = "lsp_refactor";
+export const LSP_RECOVER_TOOL = "lsp_recover";
+
+export const LSP_TOOL_NAMES = [
+  LSP_LOOKUP_TOOL,
+  LSP_DOCUMENT_SYMBOLS_TOOL,
+  LSP_WORKSPACE_SYMBOLS_TOOL,
+  LSP_DIAGNOSTICS_TOOL,
+  LSP_REFACTOR_TOOL,
+  LSP_RECOVER_TOOL,
+] as const;
+
+export type LspToolName = (typeof LSP_TOOL_NAMES)[number];

package/src/{overrides.ts → tool/overrides.ts}

@@ -1,15 +1,23 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  AgentToolUpdateCallback,
+  EditToolInput,
+  ExtensionAPI,
+  ExtensionContext,
+  ReadToolInput,
+  WriteToolInput,
+} from "@earendil-works/pi-coding-agent";
 import { createEditTool, createReadTool, createWriteTool } from "@earendil-works/pi-coding-agent";
-import { augmentDiagnostics } from "./diagnostics/diagnostic-augmentation.ts";
-import { formatGroupedDiagnostics } from "./diagnostics/diagnostics.ts";
-import { splitSuppressionDiagnostics } from "./diagnostics/suppression-diagnostics.ts";
-import type { LspManager } from "./manager/manager.ts";
-import type { Diagnostic } from "./types.ts";
+import type { Diagnostic } from "../config/types.ts";
+import { augmentDiagnostics } from "../diagnostics/diagnostic-augmentation.ts";
+import { formatGroupedDiagnostics } from "../diagnostics/diagnostics.ts";
+import { splitSuppressionDiagnostics } from "../diagnostics/suppression-diagnostics.ts";
+import type { LspManager } from "../manager/manager.ts";
+import { resolveSessionPath } from "../utils.ts";
 
 interface LspOverrideState {
   getInlineSeverity(): number;
   getManager(): LspManager | null;
-  getCwd(): string;
+  isActive(): boolean;
 }
 
 export function registerLspAwareToolOverrides(pi: ExtensionAPI, state: LspOverrideState): void {
@@ -20,11 +28,17 @@ export function registerLspAwareToolOverrides(pi: ExtensionAPI, state: LspOverri
   pi.registerTool({
     ...readMeta,
     // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(toolCallId, params, signal, onUpdate, _ctx) {
-      const cwd = state.getCwd();
-      const originalRead = createReadTool(cwd);
+    async execute(
+      toolCallId: string,
+      params: ReadToolInput,
+      signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback | undefined,
+      ctx: ExtensionContext,
+    ) {
+      const originalRead = createReadTool(ctx.cwd);
       const result = await originalRead.execute(toolCallId, params, signal, onUpdate);
-      await ensureFileOpen(state.getManager(), params.path);
+      if (!state.isActive()) return result;
+      await ensureFileOpen(state.getManager(), ctx.cwd, params.path);
       return result;
     },
   });
@@ -32,15 +46,21 @@ export function registerLspAwareToolOverrides(pi: ExtensionAPI, state: LspOverri
   pi.registerTool({
     ...writeMeta,
     // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(toolCallId, params, signal, onUpdate, _ctx) {
-      const cwd = state.getCwd();
-      const originalWrite = createWriteTool(cwd);
+    async execute(
+      toolCallId: string,
+      params: WriteToolInput,
+      signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback | undefined,
+      ctx: ExtensionContext,
+    ) {
+      const originalWrite = createWriteTool(ctx.cwd);
       const result = await originalWrite.execute(toolCallId, params, signal, onUpdate);
+      if (!state.isActive()) return result;
       return appendInlineDiagnostics({
         manager: state.getManager(),
         filePath: params.path,
         inlineSeverity: state.getInlineSeverity(),
-        cwd,
+        cwd: ctx.cwd,
         result,
       });
     },
@@ -49,15 +69,21 @@ export function registerLspAwareToolOverrides(pi: ExtensionAPI, state: LspOverri
   pi.registerTool({
     ...editMeta,
     // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(toolCallId, params, signal, onUpdate, _ctx) {
-      const cwd = state.getCwd();
-      const originalEdit = createEditTool(cwd);
+    async execute(
+      toolCallId: string,
+      params: EditToolInput,
+      signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback | undefined,
+      ctx: ExtensionContext,
+    ) {
+      const originalEdit = createEditTool(ctx.cwd);
       const result = await originalEdit.execute(toolCallId, params, signal, onUpdate);
+      if (!state.isActive()) return result;
       return appendInlineDiagnostics({
         manager: state.getManager(),
         filePath: params.path,
         inlineSeverity: state.getInlineSeverity(),
-        cwd,
+        cwd: ctx.cwd,
         result,
       });
     },
@@ -78,17 +104,18 @@ async function appendInlineDiagnostics<T extends { content: unknown[]; details:
   if (!options.manager) return options.result;
 
   try {
+    const resolvedFilePath = resolveSessionPath(options.cwd, options.filePath);
     const effectiveSeverity = Math.max(options.inlineSeverity, 2);
     const entries = await options.manager.syncFileAndGetCascadingDiagnostics(
-      options.filePath,
+      resolvedFilePath,
       effectiveSeverity,
     );
     if (entries.length === 0) return options.result;
 
     const primaryDiagnostics =
-      entries.find((entry) => entry.file === options.filePath)?.diagnostics ?? [];
+      entries.find((entry) => entry.file === resolvedFilePath)?.diagnostics ?? [];
     const augmentation = await augmentDiagnostics(
-      options.filePath,
+      resolvedFilePath,
       splitSuppressionDiagnostics(primaryDiagnostics, options.inlineSeverity).regular,
       options.manager,
       options.cwd,
@@ -162,11 +189,15 @@ export function buildInlineDiagnosticsMessage(
   return sections.join("\n\n");
 }
 
-async function ensureFileOpen(manager: LspManager | null, filePath: string): Promise<void> {
+async function ensureFileOpen(
+  manager: LspManager | null,
+  cwd: string,
+  filePath: string,
+): Promise<void> {
   if (!manager) return;
 
   try {
-    await manager.ensureFileOpen(filePath);
+    await manager.ensureFileOpen(resolveSessionPath(cwd, filePath));
   } catch {
     // Never block the agent on LSP errors
   }

package/src/tool/register-tools.ts

@@ -0,0 +1,224 @@
+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 });
+
+/** 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(),
+  });
+}
+
+function getReadyService(cwd: string) {
+  const state = getSessionLspService(cwd);
+  return state.kind === "ready" ? state.service : null;
+}
+
+function describeUnavailableService(cwd: string): string {
+  const state = getSessionLspService(cwd);
+  switch (state.kind) {
+    case "pending":
+      return "LSP is still starting for this workspace. Retry in a moment.";
+    case "inactive":
+      return `LSP is inactive on the current session branch for ${cwd}.`;
+    case "disabled":
+      return `LSP is disabled for ${cwd}.`;
+    case "unavailable":
+      return state.reason;
+    default:
+      return "LSP not initialized. Start a new session first.";
+  }
+}
+
+function createToolExecutor(
+  run: (
+    service: NonNullable<ReturnType<typeof getReadyService>>,
+    cwd: string,
+    params: unknown,
+  ) => Promise<string>,
+) {
+  // 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 run(service, ctx.cwd, params)
+      : describeUnavailableService(ctx.cwd);
+    return makeTextResult(text);
+  };
+}
+
+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 }],
+    details: {},
+  };
+}