feat(ai): Enable Context Variables for Chat Requests

[planger]

What it does

This PR introduces the ability for users to add contextual information to chat requests. This allows manually passing elements such as files, symbols, or other variables, which chat agents can then utilize when generating responses.

Context Variables

To represent contextual elements, we extend the existing variables concept. Previously, variables were placeholders within chat request text (e.g., #selectedText), dynamically resolved by the chat service before processing (ResolvedAIVariable.value), replacing the occurrence of the variable directly in the user input.

With this PR, we introduce context variables (AIContextVariable), which enhance the existing variables by not only resolving a value for text replacement but also attaching a dedicated context value (ResolvedAIContextVariable.contextValue) to the chat request. This enables agents to use contextual information without making it a fixed part of the user’s input.

Key Benefits:

• Separation of concerns: Large context elements can be included without entangling them in the user’s message.
• Flexible processing strategies: Agents can use different techniques, such as summarizing or fetching context on demand.
• Persistent context: The context can remain stable across multiple requests within a conversation without having to re-add them.

Context Variable Resolution

Context variable requests (AIVariableResolutionRequest) can be passed alongside a ChatRequest to the ChatService. The chat service then resolves context variables and attaches them to the ChatRequestModel under the context property.

If a context variable is referenced in the chat request (e.g., #file:abc.txt), it serves a dual purpose:

1. Text replacement: ResolvedAIVariable.value replaces the variable in the chat text.
2. Context attachment: ResolvedAIContextVariable.contextValue is added to the chat request model.

Attaching Context Variables

Context variables can be added to a chat request in two ways:

1. Explicitly: By providing a list of AIVariableResolutionRequest objects to ChatService.sendRequest alongside the ChatRequest.
2. Implicitly: By mentioning a context variable in the chat text (e.g., #file:abc.txt). The chat service automatically parses it into a variable request and attaches it to the context.

User Interface Enhancements

To support context variables, the chat input widget now maintains a list of added context variables. This list appears below the text input and utilizes Theia’s label provider mechanism for user-friendly display (including labels, additional information, and icons). Users can add context variables through:

1. Quick Pick Dialog (+ button): Opens a selection dialog listing all registered context variables. To improve usability, the AIVariable interface now includes optional label and icon properties.
2. Inline Input (# prefix): Users can type context variables directly into the chat input. The existing code completion mechanism suggests context variables, and selecting one also adds it to the context variable list.

Variable Arguments

Variables support arguments (parameters) that influence their resolution. This PR enhances argument handling by introducing:

• AIVariableArgPicker: Invoked when users add context variables via the Quick Pick dialog (+ button).
• AIVariableArgCompletionProvider: Invoked when users type context variables manually.

With these two mechanisms, variable providers can choose how to support users in selecting the right arguments via a UI or via auto-completion.

Example: File Context Variable (#file)

To demonstrate these improvements, we introduce a new context variable #file, which accepts a file path as an argument. We also register:

• An argument picker for selecting files when adding #file via the Quick Pick dialog.
• A completion provider that allows users to type # and get file path suggestions directly.

Therefore, we've refactored existing code into a QuickFileSelectService to provide a consistent file picker experience for both argument pickers and completion providers as well as for the existing file search (Ctrl-p).

Utilizing Chat Request Context

Chat agents can determine how they process the provided context. Common approaches include:

1. Summarization: The agent summarizes the manually specified context (e.g., compiling a list) before passing it to the LLM.
2. Context Window Management: The agent dynamically decides how much context to include:
   • If the entire context fits within the model’s context limit, it is included as-is.
   • If the context is too large, the agent applies ranking and summarization mechanisms to extract the most relevant parts.
   • Advanced implementations may use a multi-turn prompt flow to refine which elements are most relevant before sending them to the LLM.
3. On-Demand Retrieval: Instead of including the full context upfront, the agent exposes tool functions to the LLM, allowing it to retrieve specific context elements dynamically as needed. This PR includes tool functions to do that.

Fixes #14839

How to test

Use the + icon to add context files

adding-context-plus.webm

Use the context variable auto complete

adding-context-auto-complete.webm

Use the context variable argument auto complete

adding-context-auto-complete-arg.webm

Use drag and drop to add files to the context

adding-context-drop.webm

Follow-ups

Breaking changes

• This PR introduces breaking changes and requires careful review. If yes, the breaking changes section in the changelog has been updated.

Attribution

Review checklist

• As an author, I have thoroughly tested my changes and carefully followed the review guidelines

Reminder for reviewers

• As a reviewer, I agree to behave in accordance with the review guidelines