Chat API updates (microsoft#205184)

* api - remove unused types, add jsdoc, make request handler setable (for consistency), more readonly usage

microsoft#199908

* remove ChatMessage and Role

* fix a ton of compile errors...

* jsdoc

Author: jrieken

src/vs/workbench/api/common/extHost.api.impl.ts

@@ -1421,7 +1421,7 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
 				checkProposedApiEnabled(extension, 'mappedEditsProvider');
 				return extHostLanguageFeatures.registerMappedEditsProvider(extension, selector, provider);
 			},
-			createChatAgent(name: string, handler: vscode.ChatAgentExtendedHandler) {
+			createChatAgent(name: string, handler: vscode.ChatAgentExtendedRequestHandler) {
 				checkProposedApiEnabled(extension, 'chatAgents2');
 				return extHostChatAgents2.createChatAgent(extension, name, handler);
 			},
@@ -1460,8 +1460,6 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
 			Breakpoint: extHostTypes.Breakpoint,
 			TerminalOutputAnchor: extHostTypes.TerminalOutputAnchor,
 			ChatAgentResultFeedbackKind: extHostTypes.ChatAgentResultFeedbackKind,
-			ChatMessage: extHostTypes.ChatMessage,
-			ChatMessageRole: extHostTypes.ChatMessageRole,
 			ChatVariableLevel: extHostTypes.ChatVariableLevel,
 			ChatAgentCompletionItem: extHostTypes.ChatAgentCompletionItem,
 			CallHierarchyIncomingCall: extHostTypes.CallHierarchyIncomingCall,

src/vs/workbench/api/common/extHostChatAgents2.ts

@@ -11,6 +11,7 @@ import { Emitter } from 'vs/base/common/event';
 import { IMarkdownString, MarkdownString } from 'vs/base/common/htmlContent';
 import { DisposableMap, DisposableStore } from 'vs/base/common/lifecycle';
 import { StopWatch } from 'vs/base/common/stopwatch';
+import { assertType } from 'vs/base/common/types';
 import { URI } from 'vs/base/common/uri';
 import { localize } from 'vs/nls';
 import { IExtensionDescription } from 'vs/platform/extensions/common/extensions';
@@ -169,7 +170,7 @@ export class ExtHostChatAgents2 implements ExtHostChatAgentsShape2 {
 		this._proxy = mainContext.getProxy(MainContext.MainThreadChatAgents2);
 	}
 
-	createChatAgent(extension: IExtensionDescription, name: string, handler: vscode.ChatAgentExtendedHandler): vscode.ChatAgent2 {
+	createChatAgent(extension: IExtensionDescription, name: string, handler: vscode.ChatAgentExtendedRequestHandler): vscode.ChatAgent2 {
 		const handle = ExtHostChatAgents2._idPool++;
 		const agent = new ExtHostChatAgent(extension, name, this._proxy, handle, handler);
 		this._agents.set(handle, agent);
@@ -358,7 +359,7 @@ class ExtHostChatAgent {
 		public readonly id: string,
 		private readonly _proxy: MainThreadChatAgentsShape2,
 		private readonly _handle: number,
-		private readonly _callback: vscode.ChatAgentExtendedHandler,
+		private _requestHandler: vscode.ChatAgentExtendedRequestHandler,
 	) { }
 
 	acceptFeedback(feedback: vscode.ChatAgentResult2Feedback) {
@@ -507,6 +508,13 @@ class ExtHostChatAgent {
 				that._iconPath = v;
 				updateMetadataSoon();
 			},
+			get requestHandler() {
+				return that._requestHandler;
+			},
+			set requestHandler(v) {
+				assertType(typeof v === 'function', 'Invalid request handler');
+				that._requestHandler = v;
+			},
 			get commandProvider() {
 				return that._commandProvider;
 			},
@@ -585,6 +593,7 @@ class ExtHostChatAgent {
 				return that._onDidReceiveFeedback.event;
 			},
 			set agentVariableProvider(v) {
+				checkProposedApiEnabled(that.extension, 'chatAgents2Additions');
 				that._agentVariableProvider = v;
 				if (v) {
 					if (!v.triggerCharacters.length) {
@@ -597,13 +606,16 @@ class ExtHostChatAgent {
 				}
 			},
 			get agentVariableProvider() {
+				checkProposedApiEnabled(that.extension, 'chatAgents2Additions');
 				return that._agentVariableProvider;
 			},
 			set welcomeMessageProvider(v) {
+				checkProposedApiEnabled(that.extension, 'defaultChatAgent');
 				that._welcomeMessageProvider = v;
 				updateMetadataSoon();
 			},
 			get welcomeMessageProvider() {
+				checkProposedApiEnabled(that.extension, 'defaultChatAgent');
 				return that._welcomeMessageProvider;
 			},
 			onDidPerformAction: !isProposedApiEnabled(this.extension, 'chatAgents2Additions')
@@ -621,6 +633,6 @@ class ExtHostChatAgent {
 	}
 
 	invoke(request: vscode.ChatAgentRequest, context: vscode.ChatAgentContext, response: vscode.ChatAgentExtendedResponseStream, token: CancellationToken): vscode.ProviderResult<vscode.ChatAgentResult2> {
-		return this._callback(request, context, response, token);
+		return this._requestHandler(request, context, response, token);
 	}
 }

src/vs/workbench/api/common/extHostChatProvider.ts

@@ -149,13 +149,7 @@ export class ExtHostChatProvider implements ExtHostChatProviderShape {
 			this._proxy.$handleProgressChunk(requestId, { index: fragment.index, part: fragment.part });
 		});
 
-		if (data.provider.provideLanguageModelResponse2) {
-			return data.provider.provideLanguageModelResponse2(messages.map(typeConvert.LanguageModelMessage.to), options, ExtensionIdentifier.toKey(from), progress, token);
-		} else {
-			// TODO@jrieken remove
-			return data.provider.provideLanguageModelResponse(messages.map(typeConvert.ChatMessage.to), options, ExtensionIdentifier.toKey(from), progress, token);
-		}
-
+		return data.provider.provideLanguageModelResponse2(messages.map(typeConvert.LanguageModelMessage.to), options, ExtensionIdentifier.toKey(from), progress, token);
 	}
 
 	//#region --- making request

src/vs/workbench/api/common/extHostTypeConverters.ts

@@ -2239,12 +2239,6 @@ export namespace ChatInlineFollowup {
 	}
 }
 
-export namespace ChatMessage {
-	export function to(message: chatProvider.IChatMessage): vscode.ChatMessage {
-		return new types.ChatMessage(ChatMessageRole.to(message.role), message.content);
-	}
-}
-
 export namespace LanguageModelMessage {
 
 	export function to(message: chatProvider.IChatMessage): vscode.LanguageModelMessage {
@@ -2268,28 +2262,6 @@ export namespace LanguageModelMessage {
 	}
 }
 
-
-export namespace ChatMessageRole {
-
-	export function to(role: chatProvider.ChatMessageRole): vscode.ChatMessageRole {
-		switch (role) {
-			case chatProvider.ChatMessageRole.System: return types.ChatMessageRole.System;
-			case chatProvider.ChatMessageRole.User: return types.ChatMessageRole.User;
-			case chatProvider.ChatMessageRole.Assistant: return types.ChatMessageRole.Assistant;
-		}
-	}
-
-	export function from(role: vscode.ChatMessageRole): chatProvider.ChatMessageRole {
-		switch (role) {
-			case types.ChatMessageRole.System: return chatProvider.ChatMessageRole.System;
-			case types.ChatMessageRole.Assistant: return chatProvider.ChatMessageRole.Assistant;
-			case types.ChatMessageRole.User:
-			default:
-				return chatProvider.ChatMessageRole.User;
-		}
-	}
-}
-
 export namespace ChatVariable {
 	export function objectTo(variableObject: Record<string, IChatRequestVariableValue[]>): Record<string, vscode.ChatVariableValue[]> {
 		const result: Record<string, vscode.ChatVariableValue[]> = {};

src/vs/workbench/api/common/extHostTypes.ts

@@ -4196,24 +4196,6 @@ export enum InteractiveEditorResponseFeedbackKind {
 	Bug = 4
 }
 
-export enum ChatMessageRole {
-	System = 0,
-	User = 1,
-	Assistant = 2,
-}
-
-export class ChatMessage implements vscode.ChatMessage {
-
-	role: ChatMessageRole;
-	content: string;
-	name?: string;
-
-	constructor(role: ChatMessageRole, content: string) {
-		this.role = role;
-		this.content = content;
-	}
-}
-
 export enum ChatAgentResultFeedbackKind {
 	Unhelpful = 0,
 	Helpful = 1,

src/vscode-dts/vscode.proposed.chatAgents2.d.ts

@@ -5,26 +5,6 @@
 
 declare module 'vscode' {
 
-	/**
-	 * One request/response pair in chat history.
-	 */
-	export interface ChatAgentHistoryEntry {
-		/**
-		 * The request that was sent to the chat agent.
-		 */
-		request: ChatAgentRequest;
-
-		/**
-		 * The content that was received from the chat agent. Only the progress parts that represent actual content (not metadata) are represented.
-		 */
-		response: ReadonlyArray<ChatResponseTextPart | ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseCommandButtonPart>;
-
-		/**
-		 * The result that was received from the chat agent.
-		 */
-		result: ChatAgentResult2;
-	}
-
 	// TODO@API name: Turn?
 	export class ChatAgentRequestTurn {
 
@@ -38,15 +18,10 @@ declare module 'vscode' {
 		 */
 		readonly prompt: string;
 
-		// TODO@API NAME agent
-		// TODO@API TYPE {agent:string, extension:string}
-		/** @deprecated */
-		readonly agentId: string;
-
 		/**
 		 * The ID of the chat agent to which this request was directed.
 		 */
-		readonly agent: { extensionId: string; agentId: string };
+		readonly agent: { readonly extensionId: string; readonly agentId: string };
 
 		/**
 		 * The name of the {@link ChatAgentCommand command} that was selected for this request.
@@ -74,10 +49,7 @@ declare module 'vscode' {
 		 */
 		readonly result: ChatAgentResult2;
 
-		/** @deprecated */
-		readonly agentId: string;
-
-		readonly agent: { extensionId: string; agentId: string };
+		readonly agent: { readonly extensionId: string; readonly agentId: string };
 
 		private constructor(response: ReadonlyArray<ChatResponseTextPart | ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseCommandButtonPart>, result: ChatAgentResult2, agentId: { extensionId: string; agentId: string });
 	}
@@ -189,14 +161,15 @@ declare module 'vscode' {
 
 		/**
 		 * Returns a list of commands that its agent is capable of handling. A command
-		 * can be selected by the user and will then be passed to the {@link ChatAgentHandler handler}
+		 * can be selected by the user and will then be passed to the {@link ChatAgentRequestHandler handler}
 		 * via the {@link ChatAgentRequest.command command} property.
 		 *
 		 *
 		 * @param token A cancellation token.
 		 * @returns A list of commands. The lack of a result can be signaled by returning `undefined`, `null`, or
 		 * an empty array.
 		 */
+		// TODO@API Q: should we provide the current history or last results for extra context?
 		provideCommands(token: CancellationToken): ProviderResult<ChatAgentCommand[]>;
 	}
 
@@ -228,6 +201,7 @@ declare module 'vscode' {
 		/**
 		 * A title to show the user, when it is different than the message.
 		 */
+		// TODO@API title vs tooltip?
 		title?: string;
 	}
 
@@ -243,6 +217,12 @@ declare module 'vscode' {
 		provideFollowups(result: ChatAgentResult2, token: CancellationToken): ProviderResult<ChatAgentFollowup[]>;
 	}
 
+	/**
+	 * A chat request handler is a callback that will be invoked when a request is made to a chat agent.
+	 */
+	export type ChatAgentRequestHandler = (request: ChatAgentRequest, context: ChatAgentContext, response: ChatAgentResponseStream, token: CancellationToken) => ProviderResult<ChatAgentResult2>;
+
+
 	export interface ChatAgent2 {
 
 		/**
@@ -274,6 +254,11 @@ declare module 'vscode' {
 			dark: Uri;
 		} | ThemeIcon;
 
+		/**
+		 * The handler for requests to this agent.
+		 */
+		requestHandler: ChatAgentRequestHandler;
+
 		/**
 		 * This provider will be called to retrieve the agent's commands.
 		 */
@@ -284,16 +269,6 @@ declare module 'vscode' {
 		 */
 		followupProvider?: ChatAgentFollowupProvider;
 
-
-		// TODO@API
-		// notify(request: ChatResponsePart, reference: string): boolean;
-		// BETTER
-		// requestResponseStream(result: ChatAgentResult, callback: (stream: ChatAgentResponseStream) => void, why?: string): void;
-
-		// TODO@API
-		// clear NEVER happens
-		// onDidClearResult(value: TResult): void;
-
 		/**
 		 * When the user clicks this agent in `/help`, this text will be submitted to this command
 		 */
@@ -315,9 +290,9 @@ declare module 'vscode' {
 	}
 
 	export interface ChatAgentResolvedVariable {
-		name: string;
-		range: [start: number, end: number];
-		values: ChatVariableValue[];
+		readonly name: string;
+		readonly range: [start: number, end: number];
+		readonly values: ChatVariableValue[];
 	}
 
 	export interface ChatAgentRequest {
@@ -330,17 +305,17 @@ declare module 'vscode' {
 		 * *Note* that the {@link ChatAgent2.name name} of the agent and the {@link ChatAgentCommand.name command}
 		 * are not part of the prompt.
 		 */
-		prompt: string;
+		readonly prompt: string;
 
 		/**
 		 * The name of the {@link ChatAgentCommand command} that was selected for this request.
 		 */
-		command?: string;
+		readonly command: string | undefined;
 
 		/**
 		 * The list of variables that are referenced in the prompt.
 		 */
-		variables: ChatAgentResolvedVariable[];
+		readonly variables: readonly ChatAgentResolvedVariable[];
 	}
 
 	export interface ChatAgentResponseStream {
@@ -429,11 +404,6 @@ declare module 'vscode' {
 		push(part: ChatResponsePart): ChatAgentResponseStream;
 	}
 
-	// TODO@API
-	// support ChatResponseCommandPart
-	// support ChatResponseTextEditPart
-	// support ChatResponseCodeReferencePart
-
 	// TODO@API should the name suffix differentiate between rendered items (XYZPart)
 	// and metadata like XYZItem
 	export class ChatResponseTextPart {
@@ -482,9 +452,6 @@ declare module 'vscode' {
 		| ChatResponseProgressPart | ChatResponseReferencePart | ChatResponseCommandButtonPart;
 
 
-	// TODO@API Remove a different type of `request` so that they can
-	// evolve at their own pace
-	export type ChatAgentHandler = (request: ChatAgentRequest, context: ChatAgentContext, response: ChatAgentResponseStream, token: CancellationToken) => ProviderResult<ChatAgentResult2>;
 
 	export namespace chat {
 
@@ -495,7 +462,7 @@ declare module 'vscode' {
 		 * @param handler The reply-handler of the agent.
 		 * @returns A new chat agent
 		 */
-		export function createChatAgent(name: string, handler: ChatAgentHandler): ChatAgent2;
+		export function createChatAgent(name: string, handler: ChatAgentRequestHandler): ChatAgent2;
 
 		/**
 		 * Register a variable which can be used in a chat request to any agent.

src/vscode-dts/vscode.proposed.chatAgents2Additions.d.ts

@@ -158,13 +158,13 @@ declare module 'vscode' {
 		constructor(label: string | CompletionItemLabel, values: ChatVariableValue[]);
 	}
 
-	export type ChatAgentExtendedHandler = (request: ChatAgentRequest, context: ChatAgentContext, response: ChatAgentExtendedResponseStream, token: CancellationToken) => ProviderResult<ChatAgentResult2>;
+	export type ChatAgentExtendedRequestHandler = (request: ChatAgentRequest, context: ChatAgentContext, response: ChatAgentExtendedResponseStream, token: CancellationToken) => ProviderResult<ChatAgentResult2>;
 
 	export namespace chat {
 		/**
 		 * Create a chat agent with the extended progress type
 		 */
-		export function createChatAgent(name: string, handler: ChatAgentExtendedHandler): ChatAgent2;
+		export function createChatAgent(name: string, handler: ChatAgentExtendedRequestHandler): ChatAgent2;
 	}
 
 	/*