Add readonly editor context capabilities for agents

[zikajk]

To upvote this issue, give it a thumbs up. See this list for the most upvoted issues.

Add readonly editor context capabilities for agents

Summary

ECA already supports editor/getDiagnostics, where the server asks the client/editor for diagnostics and the client maps editor-specific data into ECA protocol data.

We should add a similar readonly editor/getContext request so agents can ask the editor for semantic/navigation context around the current cursor instead of relying only on raw file reads and text search.

This should be editor-agnostic. eca-emacs can implement it via Emacs APIs, while VS Code/IntelliJ clients can implement the same protocol via their own APIs.

Motivation

Agents currently infer too much from text. For example, to understand a symbol under the cursor, the agent may grep for the name and read several files. Editors already know better through xref/LSP/PSI/indexes.

Readonly editor context would let the agent ask questions like:

• what symbol is under the cursor?
• where is its definition?
• what are the top-level symbols in this file?
• what diagnostic is at/near the cursor?

This should reduce wrong file reads, bad grep matches, and hallucinated API usage.

Proposed API

Add a new client capability, ideally per feature:

{
  "editor": {
    "diagnostics": true,
    "context": {
      "symbolAtPosition": true,
      "documentSymbols": true,
      "definitions": true,
      "documentation": true,
      "references": true,
      "workspace": true,
      "enclosingSymbols": true
    }
  }
}

Add a request:

editor/getContext

Example params:

{
  "uri": "file:///repo/src/foo.clj",
  "position": { "line": 42, "character": 10 },
  "include": ["symbolAtPosition", "definitions", "documentSymbols"],
  "limit": 100
}

The response should be best-effort and support unavailable capabilities:

{
  "symbolAtPosition": { "text": "foo", "range": { "...": "..." } },
  "definitions": [],
  "documentSymbols": [],
  "unavailable": [
    { "capability": "documentation", "reason": "No provider available" }
  ]
}

Initial scope

Start small:

1. symbolAtPosition

   • Helps the agent know what the user is pointing at.
   • Emacs: thing-at-point / bounds.
   • VS Code: word range at position.
   • IntelliJ: PSI element at caret.
   • Gotcha: often textual, not fully semantic.

2. definitions

   • Replaces grep-based “find definition” with editor/language-backed resolution.
   • Emacs: xref.
   • VS Code/LSP: definition provider / textDocument/definition.
   • IntelliJ: resolve / go to declaration.
   • Gotcha: may return multiple targets or declarations instead of implementations.

3. documentSymbols

   • Gives the agent a compact outline of the current file.
   • Emacs: imenu index.
   • VS Code/LSP: document symbols.
   • IntelliJ: structure view / PSI.
   • Gotcha: Emacs imenu may provide positions but not full ranges.

Also extend editor/getDiagnostics with optional cursor/range filtering:

{
  "uri": "file:///repo/src/foo.clj",
  "position": { "line": 42, "character": 10 }
}

This should return/prioritize diagnostics at or near the cursor. Current diagnostics already include uri, range, severity, code, source, and message, so this is about relevance, not adding basic metadata.

Later additions

After the initial API is working, consider:

• documentation

  • Emacs: eldoc.
  • VS Code/LSP: hover/signature help.
  • IntelliJ: quick documentation.
  • Useful to avoid guessing APIs.

• references

  • Emacs: xref.
  • VS Code/LSP: references provider.
  • IntelliJ: find usages.
  • Useful for refactors, but can be expensive; require explicit include and limit.

• workspace

  • Return workspace roots, current file, open/visible files.
  • Avoid returning all project files by default.

• enclosingSymbols

  • Current function/class/method around cursor.
  • Best-effort only. Easy with PSI/tree-sitter or document symbol ranges; unreliable with plain Imenu if ranges are missing.

• codeActions

  • Quick fixes for diagnostics.
  • Useful but not readonly; probably separate design later.

Design constraints

• Keep editor/getDiagnostics and editor/getContext separate.
• Use per-feature capabilities; not all clients will support everything.
• Return partial results and explicit unavailable entries.
• Avoid expensive defaults (references, full workspace file list).
• Do not make this Emacs-specific.
• Treat textual and semantic results differently where needed.

Suggested first implementation for eca-emacs

• symbolAtPosition: thing-at-point / bounds-of-thing-at-point
• definitions: xref
• documentSymbols: programmatic Imenu index, not the interactive imenu command
• diagnostics near cursor: filter existing collected diagnostics by range/distance

[ericdallo]

@zikajk I like this feature, not sure we should provide all features bug most of them makes sense indeed, I just think that instead of a single editor/getContext which can return/pass lots of things, we should have one for each feature, reasons:

• I created editor namespace precisely for that, so we can have editor/getDefinition, editor/getDocumentation, editor/getReferences etc.
• In the end we spend the same amount of "tokens" / words / docs because we need to explain what is each feature in protocol or LLM usage, it's just a matter of different methods or all in a single one (which I think is harder to evolve)
  Is that ok to you?

Also, I think we should discuss the LLM API as well before setting this as ready, I believe each feature would result in a new tool to LLM right? I same reason as above I don't see a win having a single eca__editor_get_context tool with a huge description and lots of params, just harder to LLM use, but in the end we will be providing 3-4 more tools to LLM, but I think that's fine

[zikajk]

@ericdallo The idea was to have one tool that can return multiple things at once so LLM doesn't have to call multiple tools (but I wouldn't merge diagnostics and context).
I believe that we would save some tokens as those operations doesn't have to be described in details and their name is clear enough. If we would have multiple tools then we would probably have to repeat some similar stuff in tool description.

It is quite possible that dumber model would prefer to have multiple tools but I think we should decide based on required informations, If model prefers to get "symbolAtPosition", "definitions", "documentSymbols" at once, then it might be better to have only one tool. But still, hard to say what is better without testing. Let's first vibecode both and do some testing? Disabling tools based on editor functionality might be also simpler than the one-tool approach.

And yes, I agree that we can do it step by step. The ticket is just a result of a brainstorming I did with LLM to find out what is possible in each editor we support.

[zikajk]

Another question is what we actually want the 'editor' in the settings for, if it can be controlled through enabled tools (if we decide to go with multiple tools)?

[ericdallo]

makes sense, I still think the saved tokens in a single tool/method are minimal vs easy to evolve/maintain and explain/control.
Not sure I got about the editor settings, but I see settings that we may wanna control related to those features, example: we wanna control if the docs that are returned in markdown or raw in editor/getDocumentation, so a setting like editor.documentation.outputType etc

[zikajk]

What I meant is that we have editor settings now, but if I'm not mistaken, disabling the eca diagnostic tool or disabling it via the 'editor' settings leads to the same result. I haven't looked into it much further, though. But based on your note, it probably has its place (even if we won't use it to control "one big tool for everything").

And you might be right. While it seems that having too many tools can hinder the model and it's better to stay minimalist, I'm not sure if one complex and complicated tool brings any real advantages (aside from the LLM being able to request more information in a single call, which is faster and cheaper). + there is a higher risk that some models won't know how to work with it.

I was thinking we could offer things that pure LSP or Treesitter don't allow—especially in Emacs, where there are many great functions that could be leveraged. Hmm, that actually leads me to think it might be interesting if users could somehow configure the tools they are familiar with... but that is probably outside the scope of this ticket :-)