@duckmind/dm-darwin-x64 0.66.4 → 0.66.6

package/extensions/dm-lens/dist/tools/lsp-navigation.js

@@ -0,0 +1,1249 @@
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Type } from "../clients/deps/typebox.js";
+import { logLatency } from "../clients/latency-logger.js";
+import { newLspMutationCorrelationId, recordLspMutationOutcome } from "../clients/lsp-mutation.js";
+import { uriToPath } from "../clients/path-utils.js";
+import { escapeRegExp } from "../clients/string-utils.js";
+import { isRecordableProjectPath } from "../clients/file-utils.js";
+import { compactRenderResult } from "./render-compact.js";
+import { applyWorkspaceEdit, refuseStaleWorkspaceEdit, summarizeWorkspaceEdit, workspaceEditTextPaths } from "../clients/lsp/edits.js";
+import { hashDiagnosticContent } from "../clients/lsp/diagnostic-binding.js";
+import { getLSPService } from "../clients/lsp/capabilities.js";
+import { buildLspNavigationEnvelope } from "./lsp-structured-output.js";
+import { SYMBOL_KIND_NAMES } from "../clients/lsp-document-symbols.js";
+const VALID_OPERATIONS = [
+  "definition",
+  "typeDefinition",
+  "declaration",
+  "references",
+  "hover",
+  "signatureHelp",
+  "documentSymbol",
+  "findSymbol",
+  "workspaceSymbol",
+  "codeAction",
+  "rename",
+  "rename_file",
+  "implementation",
+  "prepareCallHierarchy",
+  "incomingCalls",
+  "outgoingCalls",
+  "executeCommand",
+  "workspaceDiagnostics",
+  "capabilities"
+];
+const NAVIGABLE_SYMBOL_KINDS = new Set([
+  5,
+  6,
+  8,
+  11,
+  12,
+  13,
+  22,
+  23
+]);
+function normalizeOperation(value) {
+  if (typeof value !== "string")
+    return "";
+  return value.trim().replace(/^["']+|["']+$/g, "");
+}
+function isValidOperation(value) {
+  return VALID_OPERATIONS.includes(value);
+}
+function operationSupportStatus(operation, support) {
+  if (!support)
+    return null;
+  if (operation === "definition")
+    return support.definition;
+  if (operation === "typeDefinition")
+    return support.typeDefinition;
+  if (operation === "declaration")
+    return support.declaration;
+  if (operation === "references")
+    return support.references;
+  if (operation === "hover")
+    return support.hover;
+  if (operation === "signatureHelp")
+    return support.signatureHelp;
+  if (operation === "documentSymbol" || operation === "findSymbol")
+    return support.documentSymbol;
+  if (operation === "workspaceSymbol")
+    return support.workspaceSymbol;
+  if (operation === "codeAction")
+    return support.codeAction;
+  if (operation === "rename")
+    return support.rename;
+  if (operation === "implementation")
+    return support.implementation;
+  if (operation === "prepareCallHierarchy" || operation === "incomingCalls" || operation === "outgoingCalls")
+    return support.callHierarchy;
+  return null;
+}
+function emptyReasonForOperation(operation) {
+  if (operation === "signatureHelp")
+    return "position-sensitive-or-no-signature";
+  if (operation === "codeAction")
+    return "no-applicable-actions";
+  if (operation === "rename")
+    return "no-rename-edits-or-symbol-not-renamable";
+  if (operation === "rename_file")
+    return "no-file-rename-result";
+  if (operation === "findSymbol")
+    return "no-matching-symbols";
+  if (operation === "workspaceSymbol")
+    return "no-matching-symbols-or-server-index-unavailable";
+  if (operation === "capabilities")
+    return "no-active-lsp-servers";
+  if (operation === "executeCommand")
+    return "command-returned-no-result";
+  if (operation === "incomingCalls" || operation === "outgoingCalls")
+    return "no-call-hierarchy-results";
+  return "no-results";
+}
+function parseSymbolSelector(symbol) {
+  const trimmed = symbol.trim();
+  const match = /^([^#]*)(?:#(-?\d+))?$/.exec(trimmed);
+  const baseSymbol = (match?.[1] ?? trimmed).trim();
+  const rawOccurrence = match?.[2];
+  if (!rawOccurrence)
+    return { baseSymbol, occurrence: 1 };
+  const occurrence = Number.parseInt(rawOccurrence, 10);
+  if (!Number.isFinite(occurrence) || occurrence < 1) {
+    return {
+      baseSymbol,
+      occurrence: 1,
+      debug: `invalid occurrence selector #${rawOccurrence}; using #1`
+    };
+  }
+  return { baseSymbol, occurrence };
+}
+function findNthMatch(lineText, regex, occurrence) {
+  let seen = 0;
+  regex.lastIndex = 0;
+  let match;
+  while ((match = regex.exec(lineText)) !== null) {
+    seen += 1;
+    if (seen === occurrence)
+      return match;
+    if (match[0].length === 0)
+      regex.lastIndex += 1;
+  }
+  return null;
+}
+function firstNonWhitespaceCharacter(lineText) {
+  const match = /\S/.exec(lineText);
+  return (match?.index ?? 0) + 1;
+}
+function resolveSymbolColumn(content, line1, character, symbol) {
+  if (typeof character === "number" && character > 0) {
+    return { character, strategy: "explicit" };
+  }
+  const lineText = content.split(/\r?\n/)[line1 - 1] ?? "";
+  if (!symbol || symbol.trim().length === 0) {
+    return {
+      character: 1,
+      strategy: "fallback",
+      debug: "character omitted and no symbol supplied; using column 1"
+    };
+  }
+  const { baseSymbol, occurrence, debug } = parseSymbolSelector(symbol);
+  if (!baseSymbol) {
+    return {
+      character: firstNonWhitespaceCharacter(lineText),
+      requestedSymbol: symbol,
+      baseSymbol,
+      requestedOccurrence: occurrence,
+      usedOccurrence: 1,
+      strategy: "fallback",
+      debug: debug ?? "empty symbol selector; using first non-whitespace column"
+    };
+  }
+  const pattern = `\\b${escapeRegExp(baseSymbol)}\\b`;
+  const exactRegex = new RegExp(pattern, "g");
+  const exact = findNthMatch(lineText, exactRegex, occurrence);
+  if (exact) {
+    return {
+      character: exact.index + 1,
+      requestedSymbol: symbol,
+      baseSymbol,
+      requestedOccurrence: occurrence,
+      usedOccurrence: occurrence,
+      strategy: "word-boundary",
+      debug
+    };
+  }
+  const firstExact = findNthMatch(lineText, exactRegex, 1);
+  if (firstExact && occurrence !== 1) {
+    return {
+      character: firstExact.index + 1,
+      requestedSymbol: symbol,
+      baseSymbol,
+      requestedOccurrence: occurrence,
+      usedOccurrence: 1,
+      strategy: "word-boundary",
+      debug: `${debug ? `${debug}; ` : ""}occurrence #${occurrence} not found; using #1`
+    };
+  }
+  const insensitiveRegex = new RegExp(pattern, "gi");
+  const insensitive = findNthMatch(lineText, insensitiveRegex, occurrence);
+  if (insensitive) {
+    return {
+      character: insensitive.index + 1,
+      requestedSymbol: symbol,
+      baseSymbol,
+      requestedOccurrence: occurrence,
+      usedOccurrence: occurrence,
+      strategy: "case-insensitive",
+      debug: debug ?? "exact-case symbol not found; used case-insensitive match"
+    };
+  }
+  const firstInsensitive = findNthMatch(lineText, insensitiveRegex, 1);
+  if (firstInsensitive && occurrence !== 1) {
+    return {
+      character: firstInsensitive.index + 1,
+      requestedSymbol: symbol,
+      baseSymbol,
+      requestedOccurrence: occurrence,
+      usedOccurrence: 1,
+      strategy: "case-insensitive",
+      debug: `${debug ? `${debug}; ` : ""}occurrence #${occurrence} not found case-insensitively; using #1`
+    };
+  }
+  return {
+    character: firstNonWhitespaceCharacter(lineText),
+    requestedSymbol: symbol,
+    baseSymbol,
+    requestedOccurrence: occurrence,
+    usedOccurrence: 1,
+    strategy: "fallback",
+    debug: `${debug ? `${debug}; ` : ""}symbol not found on line; using first non-whitespace column`
+  };
+}
+function tokenAtPosition(content, line1, char1) {
+  const lines = content.split(/\r?\n/);
+  const line = lines[line1 - 1];
+  if (!line)
+    return;
+  const chars = [...line];
+  const idx = Math.max(0, Math.min(chars.length - 1, char1 - 1));
+  const isWord = (ch) => !!ch && /[A-Za-z0-9_?!]/.test(ch);
+  let left = idx;
+  let right = idx;
+  if (!isWord(chars[idx]) && isWord(chars[idx + 1])) {
+    left = idx + 1;
+    right = idx + 1;
+  }
+  while (left > 0 && isWord(chars[left - 1]))
+    left -= 1;
+  while (right < chars.length - 1 && isWord(chars[right + 1]))
+    right += 1;
+  const token = chars.slice(left, right + 1).join("").trim();
+  return token.length > 0 ? token : undefined;
+}
+function symbolKindLabel(kind) {
+  return kind == null ? "symbol" : SYMBOL_KIND_NAMES[kind] ?? "symbol";
+}
+function rangeStart(range) {
+  const start = range?.start;
+  return {
+    line: typeof start?.line === "number" ? start.line + 1 : undefined,
+    character: typeof start?.character === "number" ? start.character + 1 : undefined
+  };
+}
+function findSymbolMatches(symbols, query, options) {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery)
+    return [];
+  const matches = [];
+  const matchesText = (symbol) => {
+    const values = [symbol.name, symbol.detail].filter((value) => Boolean(value)).map((value) => value.trim().toLowerCase());
+    return options.exactMatch ? values.some((value) => value === normalizedQuery) : values.some((value) => value.includes(normalizedQuery));
+  };
+  const matchesKind = (symbol) => {
+    if (options.kinds.size === 0)
+      return true;
+    return options.kinds.has(symbolKindLabel(symbol.kind).toLowerCase());
+  };
+  const visit = (entries, depth) => {
+    for (const symbol of entries) {
+      if (symbol.name && matchesText(symbol) && matchesKind(symbol)) {
+        const preferredRange = symbol.selectionRange ?? symbol.range;
+        const start = rangeStart(preferredRange);
+        matches.push({
+          name: symbol.name,
+          kind: symbolKindLabel(symbol.kind),
+          kindCode: symbol.kind,
+          detail: symbol.detail,
+          line: start.line,
+          character: start.character,
+          depth,
+          location: symbol.location,
+          range: preferredRange
+        });
+        if (matches.length >= options.maxResults)
+          return;
+      }
+      if (!options.topLevelOnly && symbol.children?.length) {
+        visit(symbol.children, depth + 1);
+        if (matches.length >= options.maxResults)
+          return;
+      }
+    }
+  };
+  visit(symbols, 1);
+  return matches;
+}
+function flattenSymbols(symbols) {
+  const all = [];
+  for (const symbol of symbols) {
+    all.push(symbol);
+    if (symbol.children && symbol.children.length > 0) {
+      all.push(...flattenSymbols(symbol.children));
+    }
+  }
+  return all;
+}
+function pickLocalSymbolLocation(symbols, token, filePath) {
+  const flat = flattenSymbols(symbols).filter((symbol) => symbol.name === token);
+  if (flat.length === 0)
+    return [];
+  const uri = pathToFileURL(filePath).href;
+  return flat.map((symbol) => {
+    if (symbol.location?.uri && symbol.location.range) {
+      return { uri: symbol.location.uri, range: symbol.location.range };
+    }
+    if (symbol.range) {
+      return { uri, range: symbol.range };
+    }
+    return;
+  }).filter((entry) => Boolean(entry));
+}
+function workspaceSymbolDedupeKey(symbol) {
+  const location = symbol.location;
+  const start = rangeStart(location?.range ?? symbol.range ?? symbol.selectionRange);
+  return [
+    symbol.name ?? "",
+    symbol.detail ?? "",
+    symbol.kind ?? "",
+    location?.uri ?? "",
+    start.line ?? "",
+    start.character ?? ""
+  ].join(":");
+}
+function dedupeWorkspaceSymbols(symbols) {
+  const out = [];
+  const seen = new Set;
+  for (const symbol of symbols) {
+    const key = workspaceSymbolDedupeKey(symbol);
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    out.push(symbol);
+  }
+  return out;
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : undefined;
+}
+function searchReadFromUriRange(uri, range) {
+  if (typeof uri !== "string" || !uri.startsWith("file:"))
+    return;
+  const rangeLike = asRecord(range);
+  const startLine = rangeLike?.start?.line;
+  if (typeof startLine !== "number" || !Number.isFinite(startLine)) {
+    return;
+  }
+  const endLine = rangeLike?.end?.line;
+  try {
+    return {
+      file: fileURLToPath(uri),
+      startLine: Math.max(1, Math.floor(startLine) + 1),
+      endLine: typeof endLine === "number" && Number.isFinite(endLine) ? Math.max(1, Math.floor(endLine) + 1) : undefined
+    };
+  } catch {
+    return;
+  }
+}
+function pushSearchRead(out, uri, range) {
+  const loc = searchReadFromUriRange(uri, range);
+  if (loc)
+    out.push(loc);
+}
+function collectLocationSearchReads(result) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const record = asRecord(entry);
+    if (!record)
+      continue;
+    pushSearchRead(out, record.uri, record.range);
+    pushSearchRead(out, record.targetUri, record.targetSelectionRange ?? record.targetRange);
+  }
+  return out;
+}
+function collectWorkspaceSymbolSearchReads(result) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const symbol = asRecord(entry);
+    const location = asRecord(symbol?.location);
+    if (!location)
+      continue;
+    pushSearchRead(out, location.uri, location.range);
+    pushSearchRead(out, location.targetUri, location.targetSelectionRange ?? location.targetRange);
+  }
+  return out;
+}
+function collectCallHierarchySearchReads(result, operation, callHierarchyItem) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const record = asRecord(entry);
+    if (!record)
+      continue;
+    const item = asRecord(operation === "incomingCalls" ? record.from : record.to);
+    pushSearchRead(out, item?.uri, item?.selectionRange ?? item?.range);
+    const rangeUri = operation === "incomingCalls" ? item?.uri : callHierarchyItem?.uri;
+    const fromRanges = record.fromRanges;
+    if (Array.isArray(fromRanges)) {
+      for (const range of fromRanges)
+        pushSearchRead(out, rangeUri, range);
+    }
+  }
+  return out;
+}
+function collectSearchReadsForOperation(operation, result, callHierarchyItem) {
+  if ([
+    "definition",
+    "typeDefinition",
+    "declaration",
+    "references",
+    "implementation"
+  ].includes(operation)) {
+    return collectLocationSearchReads(result);
+  }
+  if (operation === "workspaceSymbol") {
+    return collectWorkspaceSymbolSearchReads(result);
+  }
+  if (operation === "incomingCalls" || operation === "outgoingCalls") {
+    return collectCallHierarchySearchReads(result, operation, callHierarchyItem);
+  }
+  return [];
+}
+function formatCapabilities(snapshots, filePath) {
+  if (snapshots.length === 0) {
+    return filePath ? `No active LSP server for ${path.basename(filePath)}. Open/touch the file first or run another LSP operation to start the server.` : "No active LSP servers in this session.";
+  }
+  const rows = [
+    ["definition", (s) => !!s.operationSupport.definition],
+    ["typeDefinition", (s) => !!s.operationSupport.typeDefinition],
+    ["declaration", (s) => !!s.operationSupport.declaration],
+    ["references", (s) => !!s.operationSupport.references],
+    ["hover", (s) => !!s.operationSupport.hover],
+    ["rename", (s) => !!s.operationSupport.rename],
+    ["codeAction", (s) => !!s.operationSupport.codeAction],
+    ["codeAction/resolve", (s) => !!s.operationSupport.codeActionResolve],
+    ["workspace/willRenameFiles", (s) => !!s.operationSupport.willRenameFiles],
+    ["workspaceSymbol", (s) => !!s.operationSupport.workspaceSymbol],
+    ["implementation", (s) => !!s.operationSupport.implementation],
+    ["signatureHelp", (s) => !!s.operationSupport.signatureHelp],
+    ["incomingCalls", (s) => !!s.operationSupport.callHierarchy],
+    ["outgoingCalls", (s) => !!s.operationSupport.callHierarchy],
+    [
+      "workspaceDiagnostics",
+      (s) => s.workspaceDiagnosticsSupport.mode === "pull",
+      "pull diagnostics"
+    ],
+    [
+      "rename_file",
+      () => true,
+      "filesystem rename; preflight support shown above"
+    ]
+  ];
+  const lines = [];
+  for (const snapshot of snapshots) {
+    const label = filePath ? `${snapshot.serverId} (${path.basename(filePath)})` : `${snapshot.serverId} (${snapshot.root})`;
+    lines.push(label);
+    for (const [name, supported, note] of rows) {
+      const suffix = note ? ` (${note})` : "";
+      lines.push(`  ${name} ${supported(snapshot) ? "✓" : "✗"}${suffix}`);
+    }
+    const commands = snapshot.advertisedCommands ?? [];
+    lines.push(`  executeCommand ${commands.length > 0 ? "✓" : "✗"} (${commands.length} advertised command(s)` + (commands.length > 0 ? `: ${commands.slice(0, 20).join(", ")}` : "") + ")");
+  }
+  return lines.join(`
+`);
+}
+function classifyCodeActions(actions) {
+  if (!actions || actions.length === 0)
+    return { quickfix: 0, refactor: 0, other: 0 };
+  let quickfix = 0;
+  let refactor = 0;
+  let other = 0;
+  for (const action of actions) {
+    const kind = action.kind ?? "";
+    if (kind.startsWith("quickfix"))
+      quickfix += 1;
+    else if (kind.startsWith("refactor"))
+      refactor += 1;
+    else
+      other += 1;
+  }
+  return { quickfix, refactor, other };
+}
+async function openFileBestEffort(lspService, filePath, waitForDiagnostics = false) {
+  let fileContent;
+  try {
+    fileContent = nodeFs.readFileSync(filePath, "utf-8");
+  } catch {
+    return;
+  }
+  if (fileContent === "")
+    return "";
+  try {
+    await lspService.touchFile(filePath, fileContent, {
+      diagnostics: waitForDiagnostics ? "document" : "none",
+      source: "lsp_navigation",
+      clientScope: waitForDiagnostics ? "all" : "primary"
+    });
+  } catch {}
+  return fileContent;
+}
+const RENAME_MTIME_MARGIN_MS = 2000;
+function captureRenameExpectedContent(lspService, edit, cwd, targetFilePath, targetContent, requestedAtMs) {
+  const expected = new Map;
+  let targetRealPath;
+  if (targetContent !== undefined) {
+    try {
+      targetRealPath = nodeFs.realpathSync.native(targetFilePath);
+    } catch {
+      targetRealPath = undefined;
+    }
+  }
+  for (const diskPath of workspaceEditTextPaths(edit)) {
+    let realPath;
+    let content;
+    let mtimeMs;
+    try {
+      realPath = nodeFs.realpathSync.native(diskPath);
+      content = nodeFs.readFileSync(realPath, "utf-8");
+      mtimeMs = nodeFs.statSync(realPath).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (targetContent !== undefined && realPath === targetRealPath) {
+      expected.set(realPath, targetContent);
+      continue;
+    }
+    const tracked = lspService.getTrackedContent(diskPath, cwd);
+    const firstOpenedAfterRequest = tracked !== undefined && (tracked.openedAtMs ?? 0) >= requestedAtMs;
+    const quietSinceClientStart = tracked?.clientStartedAtMs !== undefined && mtimeMs < tracked.clientStartedAtMs - RENAME_MTIME_MARGIN_MS;
+    const sent = firstOpenedAfterRequest && quietSinceClientStart ? undefined : tracked;
+    if (sent !== undefined) {
+      if (sent.hash !== hashDiagnosticContent(content) || (sent.changedAtMs ?? requestedAtMs) >= requestedAtMs) {
+        refuseStaleWorkspaceEdit(diskPath, "it changed after the language server computed the rename from it");
+      }
+    } else if (tracked !== undefined && (tracked.hash !== hashDiagnosticContent(content) || tracked.openedHash !== tracked.hash)) {
+      refuseStaleWorkspaceEdit(diskPath, "it changed after the language client first opened it, after the rename was requested");
+    } else if (mtimeMs >= requestedAtMs) {
+      refuseStaleWorkspaceEdit(diskPath, "it was written after the rename was requested and the language server has no open copy, so it may not have read these bytes");
+    } else if (mtimeMs >= requestedAtMs - RENAME_MTIME_MARGIN_MS) {
+      refuseStaleWorkspaceEdit(diskPath, `it was modified within ${RENAME_MTIME_MARGIN_MS / 1000} s of the rename request; retry`);
+    }
+    expected.set(realPath, content);
+  }
+  return expected;
+}
+export function createLspNavigationTool(getFlag, mutationDeps) {
+  return {
+    name: "lsp_navigation",
+    label: "LSP Navigate",
+    description: 'Navigate source with language-server operations such as definition, references, hover, and rename. Example: use `{operation: "references", path: "src/app.ts", line: 12}`.',
+    promptSnippet: "Navigate definitions and references with LSP",
+    renderResult: compactRenderResult(({ details, args, isError, text }) => {
+      const op = details?.operation ?? (typeof args.operation === "string" ? args.operation : "lsp");
+      if (isError || details?.supported === false) {
+        return `lsp_navigation ${op} — ${details?.emptyReason ?? text.split(`
+`)[0] ?? "unavailable"}`;
+      }
+      const n = details?.resultCount ?? 0;
+      if (n === 0) {
+        return `lsp_navigation ${op} — ${details?.emptyReason ?? "no results"}`;
+      }
+      return `lsp_navigation ${op} — ${n} result${n === 1 ? "" : "s"}`;
+    }),
+    parameters: Type.Object({
+      operation: Type.String({
+        description: "LSP operation to perform. Valid values: definition, typeDefinition, declaration, references, hover, signatureHelp, documentSymbol, findSymbol, workspaceSymbol, codeAction, rename, rename_file, implementation, prepareCallHierarchy, incomingCalls, outgoingCalls, executeCommand, workspaceDiagnostics, capabilities."
+      }),
+      path: Type.Optional(Type.String({
+        description: "Target file path."
+      })),
+      line: Type.Optional(Type.Number({
+        description: "1-based line number."
+      })),
+      character: Type.Optional(Type.Number({
+        description: "1-based character offset."
+      })),
+      symbol: Type.Optional(Type.String({
+        description: "Symbol for automatic character resolution."
+      })),
+      endLine: Type.Optional(Type.Number({
+        description: "1-based range end line."
+      })),
+      endCharacter: Type.Optional(Type.Number({
+        description: "1-based range end character."
+      })),
+      newName: Type.Optional(Type.String({
+        description: "New symbol name."
+      })),
+      newFilePath: Type.Optional(Type.String({
+        description: "New file path."
+      })),
+      apply: Type.Optional(Type.Boolean({
+        description: "Apply a mutation instead of previewing it."
+      })),
+      command: Type.Optional(Type.String({
+        description: "Server command identifier."
+      })),
+      commandArguments: Type.Optional(Type.Array(Type.Unknown(), {
+        description: "Arguments for the server command."
+      })),
+      query: Type.Optional(Type.String({
+        description: "Symbol search query."
+      })),
+      kinds: Type.Optional(Type.Array(Type.String(), {
+        description: "Symbol-kind filters."
+      })),
+      exactMatch: Type.Optional(Type.Boolean({
+        description: "Require an exact symbol match."
+      })),
+      topLevelOnly: Type.Optional(Type.Boolean({
+        description: "Exclude nested symbols."
+      })),
+      maxResults: Type.Optional(Type.Number({
+        description: "Maximum symbol matches."
+      })),
+      callHierarchyItem: Type.Optional(Type.Object({
+        name: Type.String(),
+        kind: Type.Number(),
+        uri: Type.String(),
+        range: Type.Object({
+          start: Type.Object({
+            line: Type.Number(),
+            character: Type.Number()
+          }),
+          end: Type.Object({
+            line: Type.Number(),
+            character: Type.Number()
+          })
+        }),
+        selectionRange: Type.Object({
+          start: Type.Object({
+            line: Type.Number(),
+            character: Type.Number()
+          }),
+          end: Type.Object({
+            line: Type.Number(),
+            character: Type.Number()
+          })
+        })
+      }, {}))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const session = mutationDeps?.runtime?.captureSessionGeneration?.();
+      const startedAt = Date.now();
+      let supported = null;
+      let diagnosticsMode = "unknown";
+      let columnResolution;
+      let openedFileContent;
+      let renameRequestedAtMs = 0;
+      let mutationContext;
+      let requestedApply = false;
+      const workspaceScopeAttribution = {};
+      const finalize = (payload, meta) => {
+        if (payload.isError && requestedApply && mutationContext && ["rename", "rename_file", "executeCommand"].includes(meta.operation)) {
+          recordLspMutationOutcome(mutationContext, "failed");
+        }
+        const normalizedFilePath = meta.filePath.replace(/\\/g, "/");
+        logLatency({
+          type: "phase",
+          phase: "lsp_navigation_result",
+          filePath: normalizedFilePath,
+          durationMs: Date.now() - startedAt,
+          metadata: {
+            operation: meta.operation,
+            failureKind: meta.failureKind,
+            resultCount: meta.resultCount,
+            supported,
+            diagnosticsMode,
+            columnResolution,
+            ...Object.keys(workspaceScopeAttribution).length > 0 ? { workspaceScopeAttribution } : {}
+          }
+        });
+        const text = payload.content[0]?.text ?? "";
+        const envelope = buildLspNavigationEnvelope({
+          operation: meta.operation,
+          filePath: meta.filePath,
+          failureKind: meta.failureKind,
+          resultCount: meta.resultCount,
+          text,
+          isError: payload.isError,
+          details: payload.details
+        });
+        return {
+          ...payload,
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(envelope)
+            }
+          ],
+          details: {
+            ...payload.details,
+            failureKind: meta.failureKind
+          }
+        };
+      };
+      if (getFlag("no-lsp", ctx.cwd)) {
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: "lsp_navigation requires LSP to be enabled. Remove --no-lsp to use LSP navigation."
+            }
+          ],
+          isError: true
+        }, {
+          operation: "precheck",
+          filePath: "(workspace)",
+          failureKind: "lsp_disabled",
+          resultCount: 0
+        });
+      }
+      const { operation: rawOperation, path: rawPath, line, character, symbol, endLine, endCharacter, newName, newFilePath, apply, command, commandArguments, query, kinds, exactMatch, topLevelOnly, maxResults, callHierarchyItem } = params;
+      const normalizedOperation = normalizeOperation(rawOperation);
+      if (!isValidOperation(normalizedOperation)) {
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `Unknown lsp_navigation operation "${normalizedOperation || String(rawOperation ?? "") || ""}". ` + `Valid operations: ${VALID_OPERATIONS.join(", ")}`
+            }
+          ],
+          isError: true,
+          details: {
+            rawOperation,
+            normalizedOperation,
+            validOperations: VALID_OPERATIONS
+          }
+        }, {
+          operation: normalizedOperation || "invalid",
+          filePath: "(workspace)",
+          failureKind: "invalid_operation",
+          resultCount: 0
+        });
+      }
+      const operation = normalizedOperation;
+      requestedApply = apply === true;
+      if (requestedApply && ["rename", "rename_file", "executeCommand"].includes(operation)) {
+        const cwd = ctx.cwd || ".";
+        const mutationSource = operation === "executeCommand" ? "lsp-execute-command" : "lsp-rename";
+        mutationContext = {
+          cwd,
+          sessionId: ctx.sessionManager?.getSessionId?.(),
+          correlationId: newLspMutationCorrelationId(_toolCallId),
+          toolCallId: _toolCallId,
+          tool: `lsp_navigation:${operation}`,
+          source: mutationSource,
+          ...mutationDeps,
+          session,
+          readGuard: getFlag("no-read-guard", cwd) ? undefined : mutationDeps?.readGuard,
+          isRecordable: (filePath) => {
+            return isRecordableProjectPath(filePath, mutationDeps?.runtime?.projectRoot ?? cwd);
+          }
+        };
+      }
+      const isCallHierarchyTraversal = operation === "incomingCalls" || operation === "outgoingCalls";
+      const needsFilePath = operation !== "workspaceDiagnostics" && operation !== "workspaceSymbol" && operation !== "executeCommand" && operation !== "capabilities" && !isCallHierarchyTraversal;
+      if (needsFilePath && (!rawPath || rawPath.trim().length === 0)) {
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `path is required for ${operation}`
+            }
+          ],
+          isError: true
+        }, {
+          operation,
+          filePath: "(workspace)",
+          failureKind: "missing_file_path",
+          resultCount: 0
+        });
+      }
+      const filePath = rawPath ? path.isAbsolute(rawPath) ? rawPath : path.resolve(ctx.cwd || ".", rawPath) : "";
+      let filePathIsDirectory = false;
+      if (filePath) {
+        try {
+          filePathIsDirectory = nodeFs.statSync(filePath).isDirectory();
+        } catch {}
+      }
+      const lspService = getLSPService();
+      if (operation === "capabilities") {
+        const snapshots = rawPath ? await lspService.getCapabilitySnapshots(filePath) : await lspService.getCapabilitySnapshots(undefined, workspaceScopeAttribution);
+        const output = formatCapabilities(snapshots, rawPath ? filePath : undefined);
+        return finalize({
+          content: [{ type: "text", text: output }],
+          details: {
+            operation,
+            resultCount: snapshots.length,
+            servers: snapshots.map((snapshot) => snapshot.serverId)
+          }
+        }, {
+          operation,
+          filePath: rawPath ? filePath : "(workspace)",
+          failureKind: snapshots.length === 0 ? "empty_result" : "success",
+          resultCount: snapshots.length
+        });
+      }
+      if (operation === "workspaceDiagnostics") {
+        const wsDiagSupport = rawPath ? await lspService.getWorkspaceDiagnosticsSupport(filePath) : await lspService.getWorkspaceDiagnosticsSupport(undefined, workspaceScopeAttribution);
+        diagnosticsMode = wsDiagSupport?.mode ?? "unknown";
+        if (rawPath && !filePathIsDirectory) {
+          const hasLSP = lspService.supportsLSP(filePath);
+          if (!hasLSP) {
+            return finalize({
+              content: [
+                {
+                  type: "text",
+                  text: `No LSP server available for ${path.basename(filePath)}. Check that the language server is installed.`
+                }
+              ],
+              isError: true
+            }, {
+              operation,
+              filePath,
+              failureKind: "no_server",
+              resultCount: 0
+            });
+          }
+          await openFileBestEffort(lspService, filePath, true);
+          const diagnostics = await lspService.getDiagnostics(filePath);
+          const result = [
+            {
+              filePath,
+              diagnostics,
+              count: diagnostics.length
+            }
+          ];
+          const noteMap = {
+            pull: "Note: path mode requests pull diagnostics for this file and returns the aggregated result",
+            "push-only": "Note: server is push-only; result depends on published diagnostics for this file"
+          };
+          const note = noteMap[diagnosticsMode] ?? "Note: workspace diagnostics mode unknown (no active capability snapshot)";
+          const resultCount = diagnostics.length;
+          return finalize({
+            content: [
+              {
+                type: "text",
+                text: `${note}
+${JSON.stringify(result)}`
+              }
+            ],
+            details: {
+              operation,
+              resultCount,
+              diagnosticsMode,
+              coverage: "requested-file"
+            }
+          }, {
+            operation,
+            filePath,
+            failureKind: resultCount === 0 ? "empty_result" : "success",
+            resultCount
+          });
+        }
+        const allDiagnostics = await lspService.getAllDiagnostics();
+        const result = Array.from(allDiagnostics.entries()).map(([trackedFile, { diags }]) => ({
+          filePath: trackedFile,
+          diagnostics: diags,
+          count: diags.length
+        }));
+        const noteMap2 = {
+          "push-only": "Note: push-only tracked diagnostics snapshot (not full workspace pull diagnostics).",
+          pull: "Note: tracked diagnostics snapshot from active clients. Provide path to force file-level diagnostics collection"
+        };
+        const note = noteMap2[diagnosticsMode] ?? "Note: workspace diagnostics mode unknown (no active capability snapshot)";
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `${note}
+${JSON.stringify(result)}`
+            }
+          ],
+          details: {
+            operation,
+            resultCount: result.length,
+            diagnosticsMode,
+            coverage: "tracked-open-files"
+          }
+        }, {
+          operation,
+          filePath: rawPath ? filePath : "(workspace)",
+          failureKind: diagnosticsMode === "push-only" ? "tracked_snapshot" : "success",
+          resultCount: result.length
+        });
+      }
+      if (needsFilePath && filePathIsDirectory) {
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `path must be a source file, got directory: ${filePath}. Pass a source file path, or omit path for workspace-level operations.`
+            }
+          ],
+          isError: true
+        }, {
+          operation,
+          filePath,
+          failureKind: "filepath_is_directory",
+          resultCount: 0
+        });
+      }
+      const hasLSP = filePath ? lspService.supportsLSP(filePath) : false;
+      if (needsFilePath && !hasLSP) {
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `No LSP server available for ${path.basename(filePath)}. Check that the language server is installed.`
+            }
+          ],
+          isError: true
+        }, {
+          operation,
+          filePath,
+          failureKind: "no_server",
+          resultCount: 0
+        });
+      }
+      if (needsFilePath) {
+        const support = await lspService.getOperationSupport(filePath);
+        supported = operationSupportStatus(operation, support);
+        if (supported === false) {
+          return finalize({
+            content: [
+              {
+                type: "text",
+                text: `LSP server for ${path.basename(filePath)} does not advertise support for ${operation}`
+              }
+            ],
+            isError: true,
+            details: {
+              operation,
+              supported: false,
+              emptyReason: "unsupported"
+            }
+          }, { operation, filePath, failureKind: "unsupported", resultCount: 0 });
+        }
+        openedFileContent = await openFileBestEffort(lspService, filePath);
+      }
+      const lspLine = (line ?? 1) - 1;
+      const needsPosition = [
+        "definition",
+        "typeDefinition",
+        "declaration",
+        "references",
+        "hover",
+        "signatureHelp",
+        "codeAction",
+        "rename",
+        "implementation",
+        "prepareCallHierarchy"
+      ].includes(operation);
+      const resolvedCharacter = needsPosition && filePath ? resolveSymbolColumn(nodeFs.existsSync(filePath) ? nodeFs.readFileSync(filePath, "utf-8") : "", line ?? 1, character, symbol) : {
+        character: character ?? 1,
+        strategy: "explicit"
+      };
+      columnResolution = resolvedCharacter;
+      const lspChar = resolvedCharacter.character - 1;
+      const lspEndLine = (endLine ?? line ?? 1) - 1;
+      const lspEndChar = (endCharacter ?? resolvedCharacter.character) - 1;
+      const runWorkspaceSymbolOperation = async () => {
+        const support = rawPath ? await lspService.getOperationSupport(filePath) : await lspService.getOperationSupport(undefined, workspaceScopeAttribution);
+        supported = operationSupportStatus(operation, support);
+        if (supported === false) {
+          throw new Error("__UNSUPPORTED__ Active LSP server does not advertise support for workspaceSymbol");
+        }
+        if (!query || query.trim().length === 0) {
+          throw new Error("__BADINPUT__ query parameter required for workspaceSymbol");
+        }
+        if (rawPath) {
+          await openFileBestEffort(lspService, filePath);
+        }
+        try {
+          const raw = rawPath ? await lspService.workspaceSymbol(query ?? "", filePath) : await lspService.workspaceSymbol(query ?? "", undefined, workspaceScopeAttribution);
+          const filtered = (Array.isArray(raw) ? raw : [raw]).filter((s) => typeof s === "object" && s !== null && (!s.kind || NAVIGABLE_SYMBOL_KINDS.has(s.kind)));
+          return dedupeWorkspaceSymbols(filtered).slice(0, 15);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (rawPath && /No Project/i.test(msg)) {
+            await openFileBestEffort(lspService, filePath);
+            await new Promise((resolve) => setTimeout(resolve, 120));
+            const retryRaw = await lspService.workspaceSymbol(query ?? "", filePath);
+            const retrySymbols = (Array.isArray(retryRaw) ? retryRaw : [retryRaw]).filter((s) => typeof s === "object" && s !== null);
+            return dedupeWorkspaceSymbols(retrySymbols);
+          }
+          throw err;
+        }
+      };
+      const runOperation = async () => {
+        switch (operation) {
+          case "definition":
+            return lspService.definition(filePath, lspLine, lspChar);
+          case "typeDefinition":
+            return lspService.typeDefinition(filePath, lspLine, lspChar);
+          case "declaration":
+            return lspService.declaration(filePath, lspLine, lspChar);
+          case "references":
+            return lspService.references(filePath, lspLine, lspChar);
+          case "hover":
+            return lspService.hover(filePath, lspLine, lspChar);
+          case "signatureHelp":
+            return lspService.signatureHelp(filePath, lspLine, lspChar);
+          case "documentSymbol":
+            return lspService.documentSymbol(filePath);
+          case "findSymbol": {
+            if (!query || query.trim().length === 0) {
+              throw new Error("__BADINPUT__ query parameter required for findSymbol");
+            }
+            const symbols = await lspService.documentSymbol(filePath);
+            return findSymbolMatches(symbols, query, {
+              maxResults: Math.max(1, Math.min(100, maxResults ?? 20)),
+              topLevelOnly: topLevelOnly ?? false,
+              exactMatch: exactMatch ?? false,
+              kinds: new Set((kinds ?? []).map((kind) => kind.trim().toLowerCase()).filter(Boolean))
+            });
+          }
+          case "workspaceSymbol":
+            return runWorkspaceSymbolOperation();
+          case "codeAction":
+            return lspService.codeAction(filePath, lspLine, lspChar, lspEndLine, lspEndChar);
+          case "rename": {
+            if (!newName || newName.trim().length === 0) {
+              throw new Error("__BADINPUT__ newName parameter required for rename");
+            }
+            renameRequestedAtMs = Date.now();
+            const edit = await lspService.rename(filePath, lspLine, lspChar, newName);
+            if (!edit)
+              return null;
+            if (!apply) {
+              return {
+                applied: false,
+                summary: summarizeWorkspaceEdit(edit, ctx.cwd || "."),
+                edit
+              };
+            }
+            const applied = await applyWorkspaceEdit(edit, ctx.cwd || ".", {
+              mutationContext,
+              expectedContent: captureRenameExpectedContent(lspService, edit, ctx.cwd || ".", filePath, openedFileContent, renameRequestedAtMs)
+            });
+            for (const touchedFile of applied.files) {
+              try {
+                await openFileBestEffort(lspService, touchedFile, false);
+              } catch {}
+            }
+            return { applied: true, ...applied };
+          }
+          case "rename_file": {
+            if (!newFilePath || newFilePath.trim().length === 0) {
+              throw new Error("__BADINPUT__ newFilePath parameter required for rename_file");
+            }
+            const resolvedNewFilePath = path.isAbsolute(newFilePath) ? newFilePath : path.resolve(ctx.cwd || ".", newFilePath);
+            const result = await lspService.renameFile(filePath, resolvedNewFilePath, {
+              cwd: ctx.cwd || ".",
+              apply: apply ?? false,
+              ...mutationContext ? { mutationContext } : {}
+            });
+            if (result.applied) {
+              for (const touchedFile of result.files ?? []) {
+                try {
+                  await openFileBestEffort(lspService, touchedFile, false);
+                } catch {}
+              }
+            }
+            return result;
+          }
+          case "implementation":
+            return lspService.implementation(filePath, lspLine, lspChar);
+          case "prepareCallHierarchy":
+            return lspService.prepareCallHierarchy(filePath, lspLine, lspChar);
+          case "executeCommand": {
+            if (!command || command.trim().length === 0) {
+              throw new Error("__BADINPUT__ command parameter required for executeCommand");
+            }
+            const advertised = rawPath ? await lspService.getAdvertisedCommands(filePath) : await lspService.getAdvertisedCommands(undefined, workspaceScopeAttribution);
+            const isAdvertised = advertised.includes(command);
+            if (apply !== true) {
+              return {
+                executed: false,
+                dryRun: true,
+                command,
+                advertised: isAdvertised,
+                advertisedCommands: advertised,
+                note: isAdvertised ? "Command is advertised. Re-run with apply:true to execute." : "Command is NOT advertised by the active server; execution would be refused."
+              };
+            }
+            if (!isAdvertised) {
+              throw new Error(`__UNSUPPORTED__ command "${command}" is not advertised by the active LSP server (advertised: ${advertised.join(", ") || "none"})`);
+            }
+            return rawPath ? lspService.executeCommand(filePath, command, commandArguments, mutationContext) : lspService.executeCommand(undefined, command, commandArguments, mutationContext, workspaceScopeAttribution);
+          }
+          case "incomingCalls": {
+            if (!callHierarchyItem) {
+              throw new Error("__BADINPUT__ callHierarchyItem parameter required for incomingCalls");
+            }
+            supported = operationSupportStatus(operation, await lspService.getOperationSupport(uriToPath(callHierarchyItem.uri)));
+            if (supported === false) {
+              throw new Error("__UNSUPPORTED__ Active LSP server does not advertise support for incomingCalls");
+            }
+            return lspService.incomingCalls(callHierarchyItem);
+          }
+          case "outgoingCalls": {
+            if (!callHierarchyItem) {
+              throw new Error("__BADINPUT__ callHierarchyItem parameter required for outgoingCalls");
+            }
+            supported = operationSupportStatus(operation, await lspService.getOperationSupport(uriToPath(callHierarchyItem.uri)));
+            if (supported === false) {
+              throw new Error("__UNSUPPORTED__ Active LSP server does not advertise support for outgoingCalls");
+            }
+            return lspService.outgoingCalls(callHierarchyItem);
+          }
+          default:
+            return [];
+        }
+      };
+      let result;
+      let usedDocumentSymbolFallback = false;
+      try {
+        result = await runOperation();
+        const isEmptyInitial = !result || Array.isArray(result) && result.length === 0;
+        const shouldRetryOnEmpty = isEmptyInitial && needsFilePath && [
+          "definition",
+          "typeDefinition",
+          "declaration",
+          "references",
+          "hover",
+          "signatureHelp",
+          "codeAction",
+          "rename",
+          "implementation"
+        ].includes(operation);
+        if (shouldRetryOnEmpty) {
+          openedFileContent = await openFileBestEffort(lspService, filePath, true);
+          result = await runOperation();
+        }
+        const stillEmpty = !result || Array.isArray(result) && result.length === 0;
+        if (stillEmpty && needsFilePath && operation === "definition") {
+          const content = nodeFs.readFileSync(filePath, "utf-8");
+          const token = line && character ? tokenAtPosition(content, line, character) : undefined;
+          if (token) {
+            const docSymbols = await lspService.documentSymbol(filePath);
+            const locations = pickLocalSymbolLocation(docSymbols, token, filePath);
+            if (locations.length > 0) {
+              result = locations;
+              usedDocumentSymbolFallback = true;
+            }
+          }
+        }
+        if (mutationContext && requestedApply && !mutationContext.summaryEmitted) {
+          const outcome = operation === "rename_file" && result && typeof result === "object" && "applied" in result && result.applied === false ? "failed" : operation === "executeCommand" && result && typeof result === "object" && ("executed" in result) && result.executed === false ? "failed" : "skipped";
+          recordLspMutationOutcome(mutationContext, outcome);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.startsWith("__UNSUPPORTED__ ")) {
+          return finalize({
+            content: [
+              {
+                type: "text",
+                text: msg.replace("__UNSUPPORTED__ ", "")
+              }
+            ],
+            isError: true,
+            details: {
+              operation,
+              supported: false,
+              emptyReason: "unsupported"
+            }
+          }, { operation, filePath, failureKind: "unsupported", resultCount: 0 });
+        }
+        if (msg.startsWith("__BADINPUT__ ")) {
+          return finalize({
+            content: [
+              {
+                type: "text",
+                text: msg.replace("__BADINPUT__ ", "")
+              }
+            ],
+            isError: true,
+            details: {}
+          }, { operation, filePath, failureKind: "bad_input", resultCount: 0 });
+        }
+        return finalize({
+          content: [
+            {
+              type: "text",
+              text: `LSP error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true,
+          details: {}
+        }, { operation, filePath, failureKind: "lsp_error", resultCount: 0 });
+      }
+      const isEmpty = !result || Array.isArray(result) && result.length === 0;
+      const fileCtx = filePath ? " at " + path.basename(filePath) : "";
+      const lineCtx = line ? ":" + line + ":" + character : "";
+      let output = isEmpty ? "No results for " + operation + fileCtx + lineCtx : JSON.stringify(result);
+      if (isEmpty && operation === "workspaceSymbol" && !rawPath) {
+        output += `
+Hint: provide path to scope workspaceSymbol to the active language server/root.`;
+      }
+      if (usedDocumentSymbolFallback) {
+        output += `
+Note: served from documentSymbol fallback due to empty primary result.`;
+      }
+      if (operation === "references" && Array.isArray(result) && result.length <= 2) {
+        output += `
+Hint: references from usage sites can be partial; retry from the symbol definition for broader cross-file results.`;
+      }
+      const actionStats = operation === "codeAction" && Array.isArray(result) ? classifyCodeActions(result) : null;
+      if (operation === "codeAction" && actionStats) {
+        if (actionStats.quickfix === 0 && actionStats.refactor > 0) {
+          output += `
+Note: no diagnostic quick fixes returned; refactor-only actions available.`;
+        }
+      }
+      const resultCount = Array.isArray(result) ? result.length : result ? 1 : 0;
+      const searchReads = collectSearchReadsForOperation(operation, result, callHierarchyItem);
+      return finalize({
+        content: [{ type: "text", text: output }],
+        details: {
+          operation,
+          supported,
+          searchReads: searchReads.length > 0 ? searchReads : undefined,
+          emptyReason: isEmpty ? emptyReasonForOperation(operation) : undefined,
+          codeActionKinds: actionStats ?? undefined,
+          columnResolution: columnResolution?.strategy === "explicit" ? undefined : columnResolution,
+          resultCount
+        }
+      }, {
+        operation,
+        filePath: rawPath ? filePath : "(workspace)",
+        failureKind: isEmpty ? "empty_result" : usedDocumentSymbolFallback ? "fallback_success" : "success",
+        resultCount
+      });
+    }
+  };
+}