Add proposed API for prompt files providers

[pwang347]

Overview

The goal of this change is to unify the internal prompt file provider APIs and to prepare the provider changes as a separate proposed API to allow for dynamic prompt file content registration.

The current PR provides minimal changes to include support for instructions as well as prompt files (.prompt.md). Internally, we refer to all of these categories as "prompt files".

API follow-ups

• Prompt files provider API V2 #286457 - When I was testing the extension sample, it felt extremely wonky to have only a URI property and no way to just pass content directly. This update addresses it.
• Add support for custom source grouping #286453 (v2) - this is an internal addition to allow for custom source attribution, e.g. showing Organization label for resources related to GH Organizations.
• Add extension prompt file caching #286445 (v2) - I propose we add this to the API to allow for prompt files previously discovered to be available immediately (this needs to be optional in case stale data is not acceptable).

API usage

• Add chat prompt files sample vscode-extension-samples#1259 (using V2) - samples update, including previous static files approach
• Adopt latest provider pattern for org/enterprise custom agents vscode-copilot-chat#2737 (TODO, use V2) - base PR adapting current GH org/enterprise agents to these changes
• Add support for organization custom instructions vscode-copilot-chat#2310 (TODO, use V2) - adding GH custom instructions

[Copilot]

Pull request overview

This PR adds an InstructionsProvider API to the proposed chatParticipantPrivate extension API, allowing extensions to supply instruction resources for repositories. The implementation follows the same pattern as the existing CustomAgentsProvider, adding the necessary infrastructure across the extension host, main thread, and service layers.

Key changes:

• New InstructionsProvider interface in the proposed API with provideInstructions method and optional onDidChangeInstructions event
• Service layer support for registering and managing instructions providers
• Protocol and bridge implementations to communicate between extension host and main thread

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/vscode-dts/vscode.proposed.chatParticipantPrivate.d.ts	Adds InstructionsProvider interface and registerInstructionsProvider function to proposed API
src/vs/workbench/contrib/chat/common/promptSyntax/service/promptsService.ts	Defines IExternalInstruction interface, IInstructionQueryOptions, and adds registerInstructionsProvider to IPromptsService
src/vs/workbench/contrib/chat/common/promptSyntax/service/promptsServiceImpl.ts	Implements registerInstructionsProvider method with provider registry and change event handling
src/vs/workbench/contrib/chat/test/common/mockPromptsService.ts	Adds stub implementation for registerInstructionsProvider in mock service
src/vs/workbench/api/common/extHostChatAgents2.ts	Implements extension host side of instructions provider with handle management and proxy calls
src/vs/workbench/api/common/extHost.protocol.ts	Adds protocol methods for instructions provider registration and communication
src/vs/workbench/api/common/extHost.api.impl.ts	Exposes registerInstructionsProvider in the chat namespace
src/vs/workbench/api/browser/mainThreadChatAgents2.ts	Implements main thread side with extension activation, provider registration, and URI conversion

Comments suppressed due to low confidence (1)

src/vs/workbench/contrib/chat/common/promptSyntax/service/promptsServiceImpl.ts:322

• The getExtensionPromptFiles method only retrieves provider-based files for PromptsType.agent, but not for PromptsType.instructions. This means the instructionsProviders registry is populated but never queried. Add a similar check for PromptsType.instructions and implement a listInstructionsFromProvider method following the pattern of listCustomAgentsFromProvider (lines 253-297).

	private async getExtensionPromptFiles(type: PromptsType, token: CancellationToken): Promise<IPromptPath[]> {
		await this.extensionService.whenInstalledExtensionsRegistered();
		const contributedFiles = await Promise.all(this.contributedFiles[type].values());
		if (type === PromptsType.agent) {
			const providerAgents = await this.listCustomAgentsFromProvider(token);
			return [...contributedFiles, ...providerAgents];
		}
		return contributedFiles;
	}

[aeschli]

I think we should unify the code in core
rename registerCustomAgentsProvider to registerContributionsProvider(type

[aeschli]

ChatContributionsProvider is too generic. It could be about anything related to chat.
For the public API vscode.d.ts I suggest we keep separate APIs : CustomAgentProvider, InstructionsProvider, PromptFileProvide and separate contribution points
I would only unify the classes and functions in core. There we call them promptFiles...

[aeschli]

The changes are good. Only some small suggestions

[aeschli]

Thinking about this more, we should pass type: PromptsType to $providePromptFiles and use it to know whether to use 'provideCustomAgents', 'provideInstructions' or 'providePromptFiles'. A client could implement a provider that has all these methods that would be completly ok to do.

[aeschli]

We should use a switch over 'type' to know the name of the event. A instruction provider could also have a field 'onDidChangeCustomAgents'. That would be ok to do