API for chat agent dynamic variable completions

[roblourens]

Thinking more about dynamic completions

Updated 11/7

declare module 'vscode' {

	/**
	 * These completions cover cases where a chat agent wants to enable variables that only appear for a query going to this agent, and can use syntax that wouldn't normally be used for variables.
	 * Not clear what happens in an intent detection scenario.
	 *
	 * We need to cover two cases here
	 * - autocomplete, after I entered an agent
	 * - parsing a full query that contains references that were not entered using autocomplete
	 * 	- pasting a query
	 *  - just typing references
	 *  - followups, generated prompts? Or, should these be in a shape so that a followup can include dynamic reference data?
	 *
	 * Why not use a normal CompletionItemProvider?
	 * - vscode needs to know that a variable was selected so it can be decorated in the UI.
	 * - vscode can decide which agent is being invoked, so extensions don't have to parse the query to determine this.
	 * - the variable may represent more data than is represented in the query string, and vscode will carry this from the completion item to the chat request.
	 * 	- this is probably not true for most cases- usually the agent will be able to parse `#docset` or `@githubuser` from the query. `#file` is a counterexample, which may not be able to use this API anyway?
	 */
	export interface ChatAgent2 {
		// completionItemProvider?: ChatAgentCompletionItemProvider;

		/**
		 * Should this bring in the full power of CompletionItemProvider and CompletionItem, or should it be limited?
		 * - Need provide + resolve?
		 * - additionalTextEdits and other CompletionItem props?
		 * - support the #file scenario?
		 * 	- set a special command property that inserts extra text
		 */
		dynamicVariableCompletionItemProvider?: ChatAgentCompletionItemProvider;
		registerCompletionItemProvider(provider: CompletionItemProvider, ...triggerCharacters: string[]): Disposable;

		dynamicVariableProvider?: ChatAgentDynamicVariableProvider;
	}

	export interface ChatAgentCompletionItemProvider {
		// triggerCharacters: string[];

		// Fork CompletionItem- Which props do we need?
		provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<CompletionItem[] | CompletionList>;
	}

	export interface ChatAgentDynamicVariableProvider {
		provideDynamicVariables(query: string, token: CancellationToken): ProviderResult<ChatAgentDynamicVariableToken[]>;
	}

	export class ChatAgentDynamicVariableToken {
		range: Range;
		tooltip?: string;

		/**
		 * This data should be part of ChatVariableValue. Type doesn't matter, because it is specific to the agent.
		 */
		data: any;
	}
}

[roblourens]

Some notes from 10/31/23 api call

• "Extractor" is really just a provider
• Should fork CompletionItemProvider
• Could operate on a string rather than full TextDocument?
• And could assume that variables are single words, as an optimization. And when one variable is a prefix of another, lets us avoid resolving too early before you're done typing
• Need more discussion on the scenarios

[roblourens]

Notes from 11/7/23 api call

• Assign the completion item provider using a tuple with triggerCharacters- a property isn't right since it's only read once
• If there was no scenario where the variable can't be parsed from text alone (the #file case) then the completion item and "variable provider" APIs would work together with the second providing support for highlighting. It's not clear what other similar scenarios exist
• Don't use a TextDocument, because that would expose the chat input to all other language features. Keep the API string-based
• Will start with a simple completion item API