@mrclrchtr/supi-code-intelligence 1.3.1 → 1.5.0

package/node_modules/@mrclrchtr/supi-lsp/src/{service-registry.ts → session/service-registry.ts}

@@ -2,9 +2,9 @@
 // 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 type { LspManager } from "./manager/manager.ts";
+import { createSessionStateRegistry } from "@mrclrchtr/supi-core/api";
 import type {
+  CodeAction,
   Diagnostic,
   DocumentSymbol,
   Hover,
@@ -13,11 +13,43 @@ import type {
   Position,
   ProjectServerInfo,
   SymbolInformation,
+  WorkspaceEdit,
   WorkspaceSymbol,
-} from "./types.ts";
+} from "../config/types.ts";
+import type { LspManager } from "../manager/manager.ts";
+import { resolveSessionPath } from "../utils.ts";
+
+/** Workspace diagnostic summary grouped by file. */
+export interface WorkspaceDiagnosticSummaryEntry {
+  file: string;
+  errors: number;
+  warnings: number;
+}
+
+/** Outstanding diagnostics grouped by file, including info and hint counts. */
+export interface OutstandingDiagnosticSummaryEntry {
+  file: string;
+  total: number;
+  errors: number;
+  warnings: number;
+  information: number;
+  hints: number;
+}
+
+/** Result from a workspace diagnostic recovery pass. */
+export interface RecoverDiagnosticsResult {
+  refreshedClients: number;
+  restartedClients: number;
+  staleAssessment: {
+    suspected: boolean;
+    matchedFiles: Array<{ file: string; diagnostics: Diagnostic[] }>;
+    warning: string | null;
+  };
+}
 
 export type SessionLspServiceState =
   | { kind: "ready"; service: SessionLspService }
+  | { kind: "inactive"; service: SessionLspService }
   | { kind: "pending" }
   | { kind: "disabled" }
   | { kind: "unavailable"; reason: string };
@@ -25,7 +57,9 @@ export type SessionLspServiceState =
 /**
  * Public wrapper around {@link LspManager} that exposes stable semantic operations.
  * File path inputs may be absolute or session-cwd-relative; a leading `@` is stripped
- * to match pi's built-in path-tool convention.
+ * to match pi's built-in path-tool convention. Position arguments use raw 0-based LSP
+ * coordinates; use `toLspPosition()` from `@mrclrchtr/supi-lsp/api` when starting from
+ * user-facing 1-based line and character values.
  */
 export class SessionLspService {
   constructor(private readonly manager: LspManager) {}
@@ -77,77 +111,119 @@ export class SessionLspService {
     return this.manager.workspaceSymbol(query);
   }
 
+  async rename(
+    filePath: string,
+    position: Position,
+    newName: string,
+  ): Promise<WorkspaceEdit | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath);
+    if (!client) return null;
+    return client.rename(resolvedPath, position, newName);
+  }
+
+  async codeActions(filePath: string, position: Position): Promise<CodeAction[] | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath);
+    if (!client) return null;
+
+    const range = { start: position, end: position };
+    const diagnostics = client
+      .getDiagnostics(resolvedPath)
+      .filter((diagnostic) => diagnostic.range.start.line <= position.line)
+      .filter((diagnostic) => diagnostic.range.end.line >= position.line);
+
+    return client.codeActions(resolvedPath, range, { diagnostics });
+  }
+
   // ── Project / runtime awareness ─────────────────────────────────────
 
   getProjectServers(): ProjectServerInfo[] {
     return this.manager.getKnownProjectServers([]);
   }
 
+  /** Check whether the file can be served semantically for explicit LSP operations. */
   isSupportedSourceFile(filePath: string): boolean {
-    return this.manager.isSupportedSourceFile(this.resolveFilePath(filePath));
+    return this.manager.canServeFile(this.resolveFilePath(filePath));
   }
 
   // ── Diagnostics ─────────────────────────────────────────────────────
 
+  /** Sync a file through LSP and return diagnostics up to the supplied severity threshold. */
+  async fileDiagnostics(filePath: string, maxSeverity: number = 4): Promise<Diagnostic[] | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    if (!this.manager.canServeFile(resolvedPath)) return null;
+    return this.manager.syncFileAndGetDiagnostics(resolvedPath, maxSeverity);
+  }
+
+  /** Get a lightweight workspace diagnostic summary for all tracked files. */
+  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[] {
+    return this.manager.getDiagnosticSummary();
+  }
+
+  /** Get outstanding diagnostics grouped by file at or above the supplied severity threshold. */
   getOutstandingDiagnostics(
     maxSeverity: number = 1,
   ): Array<{ file: string; diagnostics: Diagnostic[] }> {
     return this.manager.getOutstandingDiagnostics(maxSeverity);
   }
 
-  getOutstandingDiagnosticSummary(
-    maxSeverity: number = 1,
-  ): import("./manager/manager-types.ts").OutstandingDiagnosticSummaryEntry[] {
+  /** Get outstanding diagnostic counts grouped by file. */
+  getOutstandingDiagnosticSummary(maxSeverity: number = 1): OutstandingDiagnosticSummaryEntry[] {
     return this.manager.getOutstandingDiagnosticSummary(maxSeverity);
   }
 
-  /** Access the underlying manager for advanced use cases (discouraged). */
-  getManager(): LspManager {
-    return this.manager;
+  /** Trigger a workspace-wide diagnostics refresh and stale-state recovery pass. */
+  async recoverDiagnostics(options?: {
+    restartIfStillStale?: boolean;
+    maxWaitMs?: number;
+    quietMs?: number;
+  }): Promise<RecoverDiagnosticsResult> {
+    return this.manager.recoverWorkspaceDiagnostics(options);
   }
 
   private resolveFilePath(filePath: string): string {
-    const normalizedPath = filePath.startsWith("@") ? filePath.slice(1) : filePath;
-    return path.resolve(this.manager.getCwd(), normalizedPath);
+    return resolveSessionPath(this.manager.getCwd(), filePath);
   }
 }
 
 // ── Registry ──────────────────────────────────────────────────────────
 
-const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-lsp/session-registry");
-
-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 WAIT_INTERVAL_MS = 25;
+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",
     }
   );
 }
 
+/** Wait briefly for a pending session-scoped LSP service to become ready. */
+export async function waitForSessionLspService(
+  cwd: string,
+  timeoutMs: number = 250,
+): Promise<SessionLspServiceState> {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let state = getSessionLspService(cwd);
+
+  while (state.kind === "pending" && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
+    state = getSessionLspService(cwd);
+  }
+
+  return state;
+}
+
 /** Remove the LSP service state for a session cwd. */
 export function clearSessionLspService(cwd: string): void {
-  registry.delete(normalizeCwd(cwd));
+  registry.clear(cwd);
 }

package/node_modules/@mrclrchtr/supi-lsp/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/node_modules/@mrclrchtr/supi-lsp/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/node_modules/@mrclrchtr/supi-lsp/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/node_modules/@mrclrchtr/supi-lsp/src/tool/guidance.ts

@@ -0,0 +1,78 @@
+// 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_LOOKUP_TOOL, type LspToolName } from "./names.ts";
+import { LSP_TOOL_DEFINITION_SPECS } from "./tool-specs.ts";
+
+export interface LspToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+export type LspToolPromptSurfaceMap = Record<LspToolName, LspToolPromptSurface>;
+
+export const defaultLspToolPromptSurfaces = buildLspToolPromptSurfaces([], ".");
+
+export function buildLspToolPromptSurfaces(
+  servers: ProjectServerInfo[],
+  cwd: string,
+): LspToolPromptSurfaceMap {
+  const coverageGuidelines = buildCoverageGuidelines(servers, cwd);
+
+  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[] {
+  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/node_modules/@mrclrchtr/supi-lsp/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/node_modules/@mrclrchtr/supi-lsp/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/node_modules/@mrclrchtr/supi-lsp/src/tool/register-tools.ts

@@ -0,0 +1,71 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSessionLspService } from "../session/service-registry.ts";
+import type { LspToolPromptSurfaceMap } from "./guidance.ts";
+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 {
+  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) {
+  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 makeTextResult(text: string) {
+  return {
+    content: [{ type: "text" as const, text }],
+    details: {},
+  };
+}