RFC: Export API for addon companion extensions to send custom LSP requests

[emmahyde]

Background

ruby-lsp addons can register custom request handlers using create_custom_request_handler. Addon developers who want to expose these features to users via companion VS Code extensions currently have no supported way to do so.

The VS Code extension keeps the LanguageClient internal, meaning companion extensions cannot send custom requests through it.

Use Case

I'm developing an addon that provides:

• semanticSearch: Find code by meaning using vector embeddings
• impactAnalysis: "What calls this method?" dependency graphs

The addon exposes these via custom LSP methods:

create_custom_request_handler("<path>/semanticSearch") do |global_state, params|
  # ... returns search results
end

To let users invoke semantic search from VS Code (e.g., Cmd+Shift+F → input box → results), I need to send requests to the LSP server. Without access to the language client, my workaround is spawning Ruby subprocesses to query the database directly—bypassing LSP entirely.

This works but is inefficient (cold starts, memory overhead) and doesn't benefit from the already-running LSP server.

Proposal

Export a minimal API from the VS Code extension:

// Exported from extension
export interface RubyLspApi {
  sendRequest<T>(method: string, params?: any): Promise<T>;
  isReady(): boolean;
}

Usage from a companion extension:

const rubyLsp = vscode.extensions.getExtension('Shopify.ruby-lsp');
const api = rubyLsp.exports as RubyLspApi;

const results = await api.sendRequest('<path>/semanticSearch', {
  query: 'user authentication'
});

Benefits

1. Addon developers can build full-featured companion extensions
2. Server already validates/routes custom methods
3. No breaking changes, purely additive

Implementation

In vscode/src/client.ts:

export function activate(context: vscode.ExtensionContext) {
  // ... existing code ...
  
  return {
    sendRequest: async <T>(method: string, params?: any): Promise<T> => {
      if (!client || client.state !== State.Running) {
        throw new Error('Ruby LSP client is not running');
      }
      return client.sendRequest(method, params);
    },
    isReady: () => client?.state === State.Running
  };
}

Questions for Maintainers

1. Is this something the team would consider supporting?
2. Should there be any restrictions on which methods can be called (e.g., prefix requirements like addon/)?
3. Any concerns about stability/versioning of the exported API?

Happy to submit a PR if there's interest!

[vinistock]

Thank you for the RFC. This is a very interesting idea.

My immediate thought was wondering if any other language servers have attempted to do something similar or if someone already tried to formalize something like this as part of the LSP spec. Did you search https://github.com/microsoft/language-server-protocol and https://github.com/microsoft/vscode-languageserver-node for any prior art in this area?

I especially like this idea because it removes one major limitations of add-ons: they are fully constrained to what the spec allows. By allowing companion VS Code extensions, add-ons can ship custom functionality for both the server and the extension, which I'm really excited about.

There are some concerns of course, that we would need to consider:

• Versioning is one of them. What happens if the add-on gets bumped, but the companion extension doesn't? It makes sense to follow the spec's existing capability approach, but we would need to be extra strict in ensuring that add-ons adhere to this or else compatibility can be quite chaotic
• If you install a companion extension, should it also automatically add the add-on gem? What if that add-on doesn't apply to every project? As an example, an RSpec add-on running on a project that uses Minitest. Do we need activation events or checks? Probably
• We would also need to carefully design which APIs the Ruby LSP extension exposes. Some relevant aspects:
  • The Ruby LSP is not just the language server, but also contributes a debugger client, Copilot chat agents, test explorer implementation and so on. Some of these are intertwined with the intelligence on the language server, so we may need to expose APIs that go beyond the language server client
  • We should limit the API as much as possible, especially in regards to things that may break the experience. No extension should be able to tell the LSP client to stop or restart, change our Ruby environment activation, etc..

All of that said, we're about to start the adoption of our new code indexer in the LSP, which will result in many major breaking changes for add-ons. It would probably be better to explore this after that migration is complete.