Add editor_definition and editor_references tools backed by editor's LSP

New editor/getDefinition and editor/getReferences server requests let the
LLM navigate to a symbol definition/references using the editor's language
server, resolving the symbol position server-side from path + line + symbol.
Clients answer success/starting/no-server/error so the LLM gets actionable
feedback: retry while the LSP is starting, fall back to grep otherwise.
Gated by new client capabilities and toolCall.editorNav.enabled config. #351

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `editor_definition` and `editor_references` tools backed by the editor's language server, behind new client capabilities and `toolCall.editorNav.enabled` config. #351
+
 ## 0.154.2
 
 - Retry LLM requests on network failures (VPN/wifi drops: DNS, refused or timed-out connects) with "Network issues" progress, instead of failing or hanging.

docs/config.json

@@ -1188,7 +1188,21 @@
               "type": "integer",
               "description": "Maximum length of shell command summary.",
               "markdownDescription": "Maximum length of shell command summary.",
-              "default": 25
+              "default": 35
+            }
+          }
+        },
+        "editorNav": {
+          "type": "object",
+          "description": "Configuration for the editor LSP navigation tools (editor_definition and editor_references).",
+          "markdownDescription": "Configuration for the editor LSP navigation tools (`editor_definition` and `editor_references`).",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Whether to offer the editor_definition and editor_references tools when the client declares support for them.",
+              "markdownDescription": "Whether to offer the `editor_definition` and `editor_references` tools when the client declares support for them.",
+              "default": true
             }
           }
         },

docs/config/introduction.md

@@ -136,7 +136,10 @@ By default ECA consider the following as the base configuration:
           "maxLines": 2000
         },
         "shellCommand": {
-          "summaryMaxLength": 30
+          "summaryMaxLength": 35
+        },
+        "editorNav": {
+          "enabled": true
         }
       },
       "mcpTimeoutSeconds" : 60,

docs/features.md

@@ -77,6 +77,8 @@ ECA support built-in tools to avoid user extra installation and configuration, t
     Provides access to get information from editor workspaces.
 
     - `editor_diagnostics`: Ask client about the diagnostics (like LSP diagnostics).
+    - `editor_definition`: Ask client for the definition locations of a symbol (like LSP definition). Requires client capability, can be disabled via `toolCall.editorNav.enabled` config.
+    - `editor_references`: Ask client for the references of a symbol (like LSP references). Requires client capability, can be disabled via `toolCall.editorNav.enabled` config.
 
 !!! info "Custom Tools"
 

docs/protocol.md

@@ -211,6 +211,18 @@ interface ClientCapabilities {
              * server request.
              */ 
             diagnostics?: boolean;
+
+            /**
+             * Whether client supports provide the definition locations of a symbol
+             * (Ex: LSP definition) via `editor/getDefinition` server request.
+             */
+            definition?: boolean;
+
+            /**
+             * Whether client supports provide the references of a symbol
+             * (Ex: LSP references) via `editor/getReferences` server request.
+             */
+            references?: boolean;
         }
 
         /**
@@ -2390,6 +2402,143 @@ interface EditorDiagnostic {
 }
 ```
 
+### Editor definition (↪️)
+
+A server request to retrieve from the editor the definition location(s) of the symbol
+at a position in a file, typically backed by the editor's language server (LSP).
+Only sent when client declared the `codeAssistant.editor.definition` capability.
+
+All positions in request and response are 1-based and `character` offsets count
+UTF-16 code units (the LSP default encoding); clients should convert to/from
+their language server positions (LSP ones are 0-based).
+
+Clients should answer with a `status` the server can act on instead of hanging:
+
+- If no language server is attached to the file yet, clients SHOULD attempt to
+start/attach the appropriate one (e.g. opening the file in background) and answer
+`starting` while it initializes; the server retries the request periodically within
+its `lspTimeoutSeconds` budget before giving up.
+- `no-server` should be answered only when the client cannot provide a language
+server for that file at all.
+- `error` (with `message`) should be answered on failures, so the server can give
+actionable feedback to the LLM.
+
+_Request:_ 
+
+* method: `editor/getDefinition`
+* params: `EditorGetDefinitionParams` defined as follows:
+
+```typescript
+interface EditorGetDefinitionParams {
+    /**
+     * The uri of the file containing the symbol.
+     */
+    uri: string;
+
+    /**
+     * The position (1-based) of the symbol in the file.
+     */
+    position: {
+        line: number;
+        character: number;
+    };
+}
+```
+
+_Response:_
+
+```typescript
+interface EditorGetDefinitionResponse {
+    /**
+     * The outcome of the request:
+     * - 'success': locations contain the results (may be empty when symbol has no definition).
+     * - 'starting': a language server is starting/initializing for this file, server may retry.
+     * - 'no-server': no language server available for this file.
+     * - 'error': failed to compute the result, message should explain why.
+     */
+    status: 'success' | 'starting' | 'no-server' | 'error';
+
+    /**
+     * The definition locations when status is 'success'.
+     */
+    locations?: EditorLocation[];
+
+    /**
+     * Optional detail for 'no-server' and 'error' statuses.
+     */
+    message?: string;
+}
+
+interface EditorLocation {
+    /**
+     * The location file uri.
+     */
+    uri: string;
+
+    /**
+     * The location range (1-based).
+     */
+    range: Range;
+}
+```
+
+### Editor references (↪️)
+
+A server request to retrieve from the editor the references of the symbol
+at a position in a file, typically backed by the editor's language server (LSP).
+Only sent when client declared the `codeAssistant.editor.references` capability.
+
+Follows the same position conventions and `status` semantics as `editor/getDefinition`.
+
+_Request:_ 
+
+* method: `editor/getReferences`
+* params: `EditorGetReferencesParams` defined as follows:
+
+```typescript
+interface EditorGetReferencesParams {
+    /**
+     * The uri of the file containing the symbol.
+     */
+    uri: string;
+
+    /**
+     * The position (1-based) of the symbol in the file.
+     */
+    position: {
+        line: number;
+        character: number;
+    };
+
+    /**
+     * Whether to include the symbol declaration in the results.
+     * Defaults to true when absent.
+     */
+    includeDeclaration?: boolean;
+}
+```
+
+_Response:_
+
+```typescript
+interface EditorGetReferencesResponse {
+    /**
+     * Same semantics as EditorGetDefinitionResponse status.
+     */
+    status: 'success' | 'starting' | 'no-server' | 'error';
+
+    /**
+     * The reference locations when status is 'success'.
+     */
+    locations?: EditorLocation[];
+
+    /**
+     * Optional detail for 'no-server' and 'error' statuses.
+     */
+    message?: string;
+}
+```
+
 ### Chat ask question (↪️)
 
 A server request to ask the user a question and receive an answer during a chat session.
@@ -2777,8 +2926,8 @@ interface EcaServerUpdatedParams {
      * The built-in tools supported by eca.
      *
      * Built-in tools include: read_file, write_file, edit_file, move_file,
-     * directory_tree, shell_command, editor_diagnostics, compact_chat,
-     * skill, spawn_agent, and task.
+     * directory_tree, shell_command, editor_diagnostics, editor_definition,
+     * editor_references, compact_chat, skill, spawn_agent, and task.
      *
      * Note: `spawn_agent` and `task` are excluded from subagent tool sets.
      * `spawn_agent` is excluded to prevent nesting, and `task` because

integration-test/entrypoint.clj

@@ -20,6 +20,7 @@
     integration.chat.hooks-test
     integration.chat.commands-test
     integration.chat.mcp-remote-test
+    integration.chat.editor-lsp-test
     integration.chat.invalid-image-test
     integration.chat.background-jobs-test
     integration.chat.subagent-test

integration-test/integration/chat/editor_lsp_test.clj

@@ -0,0 +1,91 @@
+(ns integration.chat.editor-lsp-test
+  (:require
+   [clojure.string :as string]
+   [clojure.test :refer [deftest is testing]]
+   [integration.eca :as eca]
+   [integration.fixture :as fixture]
+   [integration.helper :as h]
+   [llm-mock.mocks :as llm.mocks]
+   [matcher-combinators.core :as mc]
+   [matcher-combinators.matchers :as m]
+   [matcher-combinators.test :refer [match?]]))
+
+(eca/clean-after-test)
+
+(defn ^:private await-content-matching
+  "Consumes chat/contentReceived notifications until one matches, returning it."
+  [chat-id role content]
+  (loop [tries 0]
+    (if (< tries 50)
+      (let [actual (eca/client-awaits-server-notification :chat/contentReceived)]
+        (if (mc/indicates-match? (mc/match {:chatId chat-id :role role :content content} actual))
+          actual
+          (recur (inc tries))))
+      (throw (ex-info "Timeout waiting for matching content" {:content content})))))
+
+(deftest editor-definition-and-references
+  (eca/start-process!)
+
+  (eca/request! (fixture/initialize-request
+                 {:initializationOptions fixture/default-init-options
+                  :capabilities {:codeAssistant {:chat {}
+                                                 :editor {:definition true
+                                                          :references true}}}}))
+  (eca/notify! (fixture/initialized-notification))
+  (let [file1-path (h/project-path->canon-path "resources/file1.md")
+        file1-uri (h/file->uri file1-path)]
+    (testing "definition found via the editor's language server"
+      (eca/mock-response :editor/getDefinition
+                         {:status "success"
+                          :locations [{:uri file1-uri
+                                       :range {:start {:line 1 :character 1}
+                                               :end {:line 1 :character 10}}}]})
+      (llm.mocks/set-case! :editor-lsp-0)
+      (let [resp (eca/request! (fixture/chat-prompt-request
+                                {:model "openai/gpt-5-mini"
+                                 :message "Where is Something defined?"}))
+            chat-id (:chatId resp)]
+        (is (match? {:chatId (m/pred string?) :status "prompting"} resp))
+        (is (match?
+             {:type "toolCalled"
+              :origin "native"
+              :name "editor_definition"
+              :summary "LSP definition: Something"
+              :error false
+              :outputs [{:type "text"
+                         :text (str file1-path ":1:1: Something here")}]}
+             (:content (await-content-matching chat-id "assistant" {:type "toolCalled"
+                                                                    :name "editor_definition"}))))
+        (testing "the server sent the resolved 1-based position to the client"
+          (is (match?
+               {:uri (m/pred #(string/ends-with? % "file1.md"))
+                :position {:line 1 :character 1}}
+               (eca/client-awaits-server-request :editor/getDefinition))))
+        (testing "capability-gated tools were offered to the LLM"
+          (is (match?
+               {:tools (m/embeds [{:name "eca__editor_definition"}
+                                  {:name "eca__editor_references"}])}
+               (llm.mocks/get-req-body :editor-lsp-0))))))
+    (testing "references failing in the editor gives actionable error to the LLM"
+      (eca/mock-response :editor/getReferences
+                         {:status "error"
+                          :message "lsp busy"})
+      (llm.mocks/set-case! :editor-lsp-1)
+      (let [resp (eca/request! (fixture/chat-prompt-request
+                                {:model "openai/gpt-5-mini"
+                                 :message "Who uses Something?"}))
+            chat-id (:chatId resp)]
+        (is (match?
+             {:type "toolCalled"
+              :origin "native"
+              :name "editor_references"
+              :error true
+              :outputs [{:type "text"
+                         :text "Editor failed to find references: lsp busy. Use eca__grep as fallback."}]}
+             (:content (await-content-matching chat-id "assistant" {:type "toolCalled"
+                                                                    :name "editor_references"}))))
+        (is (match?
+             {:uri (m/pred #(string/ends-with? % "file1.md"))
+              :position {:line 1 :character 1}
+              :includeDeclaration false}
+             (eca/client-awaits-server-request :editor/getReferences)))))))

integration-test/llm_mock/openai.clj

@@ -226,6 +226,23 @@
                            :status "completed"}})
     (hk/close ch)))
 
+(defn ^:private editor-lsp-0 [ch body]
+  (if (some #(= "function_call_output" (:type %)) (:input body))
+    (send-text-response! ch "Found it")
+    (send-function-call-response! ch "item-1" "tool-1" "eca__editor_definition"
+                                  {:path (h/project-path->canon-path "resources/file1.md")
+                                   :line 1
+                                   :symbol "Something"})))
+
+(defn ^:private editor-lsp-1 [ch body]
+  (if (some #(= "function_call_output" (:type %)) (:input body))
+    (send-text-response! ch "Could not check references")
+    (send-function-call-response! ch "item-1" "tool-1" "eca__editor_references"
+                                  {:path (h/project-path->canon-path "resources/file1.md")
+                                   :line 1
+                                   :symbol "Something"
+                                   :include_declaration false})))
+
 (defonce ^:private subagent-follow-up-attempt* (atom 0))
 
 (defn ^:private subagent-spawn-0
@@ -302,5 +319,7 @@
                        :reasoning-0 (reasoning-0 ch)
                        :reasoning-1 (reasoning-1 ch)
                        :tool-calling-0 (tool-calling-0 ch body)
+                       :editor-lsp-0 (editor-lsp-0 ch body)
+                       :editor-lsp-1 (editor-lsp-1 ch body)
                        :subagent-spawn-0 (subagent-spawn-0 ch body)
                        :subagent-retry-0 (subagent-spawn-0 ch body true)))))})))

resources/META-INF/native-image/eca/eca/native-image.properties

@@ -30,7 +30,9 @@ Args=-J-Dborkdude.dynaload.aot=true \
      -H:IncludeResources=prompts/rewrite.md \
      -H:IncludeResources=prompts/tools/directory_tree.md \
      -H:IncludeResources=prompts/tools/edit_file.md \
+     -H:IncludeResources=prompts/tools/editor_definition.md \
      -H:IncludeResources=prompts/tools/editor_diagnostics.md \
+     -H:IncludeResources=prompts/tools/editor_references.md \
      -H:IncludeResources=prompts/tools/grep.md \
      -H:IncludeResources=prompts/tools/move_file.md \
      -H:IncludeResources=prompts/tools/preview_file_change.md \

resources/prompts/code_agent.md

@@ -26,6 +26,12 @@ You have tools at your disposal to solve the coding task. Follow these rules reg
 2. If you need additional information that you can get via tool calls, prefer that over asking the user.
 3. If you are not sure about file content or codebase structure pertaining to the user's request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.
 4. You have the capability to call multiple tools in a single response, batch your tool calls together for optimal performance.
+{% if toolEnabled_eca__editor_definition %}
+When you need to know where a symbol is defined, prefer `eca__editor_definition` over text search: it uses the editor's language server, which is precise and uses fewer tokens. Fall back to `eca__grep` if it fails.
+{% endif %}
+{% if toolEnabled_eca__editor_references %}
+When you need to find usages of a symbol, prefer `eca__editor_references` over text search: it uses the editor's language server, avoiding textual false positives. Fall back to `eca__grep` if it fails.
+{% endif %}
 {% if toolEnabled_eca__task %}
 ## Task Tracking