pref: adjust the invoke chain

Author: wenytang-ms

package.json

@@ -52,7 +52,7 @@
       {
         "name": "lsp_java_getFileStructure",
         "toolReferenceName": "javaFileStructure",
-        "modelDescription": "Get the outline of a known Java file: classes, interfaces, methods, fields, symbol kinds, and line ranges.\n\nUse this after lsp_java_findSymbol returns a relevant file, or when the user already provided a Java file path. It helps choose a precise read_file range instead of reading the whole file.\n\nDo not use this for workspace-wide search. For Java class, method, or field lookup across files, use lsp_java_findSymbol first. Only pass file paths confirmed by the user or prior tool results; do not guess paths. Do not call this repeatedly for the same file unless the first result was empty or stale.",
+        "modelDescription": "Get a known Java file's outline: classes, interfaces, methods, fields, symbol kinds, and line ranges, to pick a precise read_file range instead of reading the whole file.\n\nUse after lsp_java_findSymbol returns a file, or when the user gave a Java file path; do not guess paths. Not for workspace-wide search\u2014use lsp_java_findSymbol for that. Do not re-call for the same file unless the first result was empty.",
         "displayName": "Java: Get File Structure",
         "userDescription": "Get a Java file outline with classes, methods, fields, and line ranges.",
         "tags": [
@@ -80,7 +80,7 @@
       {
         "name": "lsp_java_findSymbol",
         "toolReferenceName": "javaFindSymbol",
-        "modelDescription": "Search Java symbols across the workspace by identifier and return concise definition locations.\n\nUse for precise Java class, interface, method, or field navigation. Prefer this over grep_search, file_search, semantic_search, or search subagents when the user is looking for a Java symbol by name or partial identifier.\n\nAfter this returns relevant symbols, do not call lsp_java_findSymbol again with the same or similar query. Continue with lsp_java_getFileStructure for the returned file, or read_file only the relevant line range.\n\nDo not use for non-Java files, string literals, comments, build files, XML, natural-language concepts, or broad codebase exploration. If there are no matches, retry at most once with a shorter materially different identifier, then fall back to generic search.",
+        "modelDescription": "Find Java class, interface, method, or field definitions across the workspace by name or partial identifier. Prefer over grep_search, file_search, semantic_search, or search subagents for Java symbol lookup.\n\nOn relevant results, do not repeat with a similar query; continue with lsp_java_getFileStructure or read_file on the returned line range. The tool retries internally, so on an empty result do not re-search\u2014retry once only if it reports indexing in progress, otherwise use generic search.\n\nDo not use for non-Java files, literals, comments, build/XML files, or conceptual exploration.",
         "displayName": "Java: Find Symbol",
         "userDescription": "Find Java class, method, field, or interface definitions by name.",
         "tags": [

resources/instruments/javaLspContext.instructions.md

@@ -12,4 +12,4 @@ If these tools are not already available in the current tool list, load them wit
 
 Use `lsp_java_findSymbol` before `grep_search`, `search_subagent`, `semantic_search`, or `file_search` only when the task is to locate Java symbols by name or partial identifier. If it returns relevant symbols, do not call it again with the same or similar query; next use `lsp_java_getFileStructure` for the returned file or `read_file` on the smallest useful line range.
 
-Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. If `findSymbol` returns no matches, retry at most once with a shorter, materially different identifier before falling back to generic search.
+Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. `findSymbol` already retries internally with a normalized identifier, so do not re-issue the same search on an empty result: if it reports indexing in progress, retry once after a short pause; otherwise fall back to generic search.

resources/skills/java-lsp-tools/SKILL.md

@@ -40,6 +40,6 @@ If `findSymbol` returns relevant symbols, move forward to `getFileStructure` or
 
 ## Fallback
 
-- `findSymbol` returns empty → retry at most once with a shorter, materially different identifier, then fall back to `grep_search`
-- Path error → use `findSymbol` to discover correct path first
+- `findSymbol` returns empty → it already retried internally with a normalized identifier, so do not re-issue the same search. If the result says indexing is in progress, retry once after a short pause; otherwise fall back to `grep_search`
+- Path error (`fileNotFound`) → use `findSymbol` to discover the correct path first; do not guess paths
 - Tool error / jdtls not ready → fall back to `grep_search` + `read_file`, don't retry more than once

src/copilot/tools/javaContextTools.ts

@@ -23,6 +23,7 @@
 import * as path from "path";
 import * as vscode from "vscode";
 import { Commands } from "../../commands";
+import { languageServerApiManager } from "../../languageServerApi/languageServerApiManager";
 import { sendInfo } from "vscode-extension-telemetry-wrapper";
 
 // Hard caps to keep tool responses within the < 200 token budget.
@@ -43,6 +44,27 @@ function getResponseCharCount(data: unknown): number {
     return typeof data === "string" ? data.length : JSON.stringify(data, null, 2).length;
 }
 
+/**
+ * Normalize a workspace-symbol query for a single fallback retry.
+ * Strips a fully-qualified package prefix (com.foo.Bar -> Bar), generic parameters
+ * (List<String> -> List), and method parameter lists (foo() -> foo). jdtls already
+ * performs camel-hump matching, so the contiguous identifier is preserved.
+ */
+function normalizeSymbolQuery(query: string): string {
+    if (!query) {
+        return "";
+    }
+    let q = query.trim();
+    // Drop generic parameters and method parens: List<String> / foo(args) -> List / foo
+    q = q.replace(/[<(].*$/, "");
+    // Drop a fully-qualified package/qualifier prefix: com.foo.Bar / Foo#bar -> Bar / bar
+    const lastSep = Math.max(q.lastIndexOf("."), q.lastIndexOf("#"));
+    if (lastSep >= 0 && lastSep < q.length - 1) {
+        q = q.substring(lastSep + 1);
+    }
+    return q.trim();
+}
+
 function getToolErrorCode(error: unknown): string {
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("No workspace folder")) {
@@ -125,7 +147,12 @@ const fileStructureTool: vscode.LanguageModelTool<FileStructureInput> = {
             } catch {
                 status = "error";
                 errorCode = "fileNotFound";
-                const fileNotFoundPayload = { error: "File not found." };
+                // Most fileNotFound errors come from the model guessing a path. Return an
+                // actionable hint instead of a dead end so it can self-correct via findSymbol.
+                const fileNotFoundPayload = {
+                    error: "File not found.",
+                    hint: "Call lsp_java_findSymbol to obtain the exact workspace path before retrying. Do not guess file paths.",
+                };
                 responseCharCount = getResponseCharCount(fileNotFoundPayload);
                 return toResult(fileNotFoundPayload);
             }
@@ -134,8 +161,13 @@ const fileStructureTool: vscode.LanguageModelTool<FileStructureInput> = {
             );
             if (!symbols || symbols.length === 0) {
                 status = "empty";
-                emptyReason = "documentSymbolProviderEmpty";
-                const noSymbolsPayload = { error: "No symbols found. The file may not be recognized by the Java language server." };
+                // Separate "index not ready yet" from a genuine no-symbol result so the model
+                // (and telemetry) can tell a transient state apart from an unrecognized file.
+                const indexing = !languageServerApiManager.isFullyReady();
+                emptyReason = indexing ? "indexingInProgress" : "documentSymbolProviderEmpty";
+                const noSymbolsPayload = indexing
+                    ? { error: "Java language server is still indexing. Retry shortly." }
+                    : { error: "No symbols found. The file may not be recognized by the Java language server." };
                 responseCharCount = getResponseCharCount(noSymbolsPayload);
                 return toResult(noSymbolsPayload);
             }
@@ -214,14 +246,33 @@ const findSymbolTool: vscode.LanguageModelTool<FindSymbolInput> = {
         let errorCode = "";
         let emptyReason = "";
         let responseCharCount = 0;
+        let retried = false;
         try {
-            const symbols = await vscode.commands.executeCommand<vscode.SymbolInformation[]>(
-                "vscode.executeWorkspaceSymbolProvider", options.input.query,
+            const rawQuery = options.input.query ?? "";
+            let symbols = await vscode.commands.executeCommand<vscode.SymbolInformation[]>(
+                "vscode.executeWorkspaceSymbolProvider", rawQuery,
             );
+            // Server-side fallback: if the verbatim query misses, retry once with a
+            // normalized identifier (strip package qualifier, generics, and parameter
+            // lists) so the model does not have to chain repeated findSymbol calls itself.
+            if (!symbols || symbols.length === 0) {
+                const normalized = normalizeSymbolQuery(rawQuery);
+                if (normalized && normalized !== rawQuery) {
+                    retried = true;
+                    symbols = await vscode.commands.executeCommand<vscode.SymbolInformation[]>(
+                        "vscode.executeWorkspaceSymbolProvider", normalized,
+                    );
+                }
+            }
             if (!symbols || symbols.length === 0) {
                 status = "empty";
-                emptyReason = "workspaceSymbolNoMatch";
-                const noMatchesPayload = { results: [], message: "No symbols found." };
+                // Distinguish a transient "index not ready" state from a real no-match so the
+                // model can retry later instead of concluding the symbol does not exist.
+                const indexing = !languageServerApiManager.isFullyReady();
+                emptyReason = indexing ? "indexingInProgress" : "workspaceSymbolNoMatch";
+                const noMatchesPayload = indexing
+                    ? { results: [], message: "Java language server is still indexing. Retry shortly or use grep_search as a fallback." }
+                    : { results: [], message: "No symbols found." };
                 responseCharCount = getResponseCharCount(noMatchesPayload);
                 return toResult(noMatchesPayload);
             }
@@ -247,6 +298,7 @@ const findSymbolTool: vscode.LanguageModelTool<FindSymbolInput> = {
                 status,
                 ...(errorCode && { errorCode }),
                 ...(emptyReason && { emptyReason }),
+                retried: retried ? "true" : "false",
                 limit,
                 resultCount,
                 totalResults,