Small cleanup/tweaks to chat session API

- In contribution, rename `id` -> `type`
- Cleaning up JSDoc
- Moving todos out of main comments

Author: mjbvz

src/vs/workbench/contrib/chat/browser/actions/chatActions.ts

@@ -571,8 +571,8 @@ export function registerChatActions() {
 							const providerNSessions: { providerType: string; session: IChatSessionItem }[] = [];
 
 							for (const provider of providers) {
-								const sessions = await chatSessionsService.provideChatSessionItems(provider.id, cancellationToken.token);
-								providerNSessions.push(...sessions.map(session => ({ providerType: provider.id, session })));
+								const sessions = await chatSessionsService.provideChatSessionItems(provider.type, cancellationToken.token);
+								providerNSessions.push(...sessions.map(session => ({ providerType: provider.type, session })));
 							}
 
 							for (const session of providerNSessions) {

src/vs/workbench/contrib/chat/browser/chatEditor.ts

@@ -139,7 +139,7 @@ export class ChatEditor extends EditorPane {
 			const identifier = ChatSessionUri.parse(input.resource);
 			if (identifier) {
 				const contributions = this.chatSessionsService.getChatSessionContributions();
-				const contribution = contributions.find(c => c.id === identifier.chatSessionType);
+				const contribution = contributions.find(c => c.type === identifier.chatSessionType);
 				if (contribution) {
 					this.widget.lockToCodingAgent(contribution.name);
 				}

src/vs/workbench/contrib/chat/browser/chatSessions.contribution.ts

@@ -34,8 +34,8 @@ const extensionPoint = ExtensionsRegistry.registerExtensionPoint<IChatSessionsEx
 		items: {
 			type: 'object',
 			properties: {
-				id: {
-					description: localize('chatSessionsExtPoint.id', 'A unique identifier for this item.'),
+				type: {
+					description: localize('chatSessionsExtPoint.chatSessionType', 'Unique identifier for the type of chat session.'),
 					type: 'string',
 				},
 				name: {
@@ -60,7 +60,7 @@ const extensionPoint = ExtensionsRegistry.registerExtensionPoint<IChatSessionsEx
 	},
 	activationEventsGenerator: (contribs, results) => {
 		for (const contrib of contribs) {
-			results.push(`onChatSession:${contrib.id}`);
+			results.push(`onChatSession:${contrib.type}`);
 		}
 	}
 });
@@ -82,14 +82,14 @@ export class ChatSessionsContribution extends Disposable implements IWorkbenchCo
 				}
 				for (const contribution of ext.value) {
 					const c: IChatSessionsExtensionPoint = {
-						id: contribution.id,
+						type: contribution.type,
 						name: contribution.name,
 						displayName: contribution.displayName,
 						description: contribution.description,
 						when: contribution.when,
 						extensionDescription: ext.description,
 					};
-					this.logService.info(`Registering chat session from extension contribution: ${c.displayName} (id='${c.id}' name='${c.name}')`);
+					this.logService.info(`Registering chat session from extension contribution: ${c.displayName} (id='${c.type}' name='${c.name}')`);
 					this._register(this.chatSessionsService.registerContribution(c)); // TODO: Is it for contribution to own this? I think not
 				}
 			}
@@ -146,8 +146,8 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 		}));
 	}
 	public registerContribution(contribution: IChatSessionsExtensionPoint): IDisposable {
-		if (this._contributions.has(contribution.id)) {
-			this._logService.warn(`Chat session contribution with id '${contribution.id}' is already registered.`);
+		if (this._contributions.has(contribution.type)) {
+			this._logService.warn(`Chat session contribution with id '${contribution.type}' is already registered.`);
 			return { dispose: () => { } };
 		}
 
@@ -161,15 +161,15 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 			}
 		}
 
-		this._contributions.set(contribution.id, contribution);
+		this._contributions.set(contribution.type, contribution);
 
 		// Register dynamic agent if the when condition is satisfied
 		this._registerDynamicAgentIfAvailable(contribution);
 
 		return {
 			dispose: () => {
-				this._contributions.delete(contribution.id);
-				this._disposeDynamicAgent(contribution.id);
+				this._contributions.delete(contribution.type);
+				this._disposeDynamicAgent(contribution.type);
 			}
 		};
 	}
@@ -186,7 +186,7 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 	private _registerDynamicAgentIfAvailable(contribution: IChatSessionsExtensionPoint): void {
 		if (this._isContributionAvailable(contribution)) {
 			const disposable = this._registerDynamicAgent(contribution);
-			this._dynamicAgentDisposables.set(contribution.id, disposable);
+			this._dynamicAgentDisposables.set(contribution.type, disposable);
 		}
 	}
 
@@ -202,14 +202,14 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 		let hasChanges = false;
 
 		for (const contribution of this._contributions.values()) {
-			const isCurrentlyRegistered = this._dynamicAgentDisposables.has(contribution.id);
+			const isCurrentlyRegistered = this._dynamicAgentDisposables.has(contribution.type);
 			const shouldBeRegistered = this._isContributionAvailable(contribution);
 
 			if (isCurrentlyRegistered && !shouldBeRegistered) {
 				// Should be unregistered
-				this._disposeDynamicAgent(contribution.id);
+				this._disposeDynamicAgent(contribution.type);
 				// Also dispose any cached sessions for this contribution
-				this._disposeSessionsForContribution(contribution.id);
+				this._disposeSessionsForContribution(contribution.type);
 				hasChanges = true;
 			} else if (!isCurrentlyRegistered && shouldBeRegistered) {
 				// Should be registered
@@ -230,7 +230,7 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 
 			// Notify about session items changes for all chat session types
 			for (const contribution of this._contributions.values()) {
-				this._onDidChangeSessionItems.fire(contribution.id);
+				this._onDidChangeSessionItems.fire(contribution.type);
 			}
 		}
 	}
@@ -257,7 +257,7 @@ export class ChatSessionsService extends Disposable implements IChatSessionsServ
 	}
 
 	private _registerDynamicAgent(contribution: IChatSessionsExtensionPoint): IDisposable {
-		const { id, name, displayName, description, extensionDescription } = contribution;
+		const { type: id, name, displayName, description, extensionDescription } = contribution;
 		const { identifier: extensionId, name: extensionName, displayName: extensionDisplayName, publisher: extensionPublisherId } = extensionDescription;
 		const agentData: IChatAgentData = {
 			id,
@@ -461,7 +461,7 @@ class CodingAgentChatImplementation extends Disposable implements IChatAgentImpl
 							const identifier = ChatSessionUri.parse(editor.resource);
 
 							if (identifier) {
-								chatSession = await this.chatSessionService.provideChatSessionContent(this.chatSession.id, identifier.sessionId, token);
+								chatSession = await this.chatSessionService.provideChatSessionContent(this.chatSession.type, identifier.sessionId, token);
 							}
 							break;
 						}

src/vs/workbench/contrib/chat/browser/chatSessions.ts

@@ -417,7 +417,7 @@ class ChatSessionsViewPaneContainer extends ViewPaneContainer {
 	private async updateViewRegistration(): Promise<void> {
 		// prepare all chat session providers
 		const contributions = await this.chatSessionsService.getChatSessionContributions();
-		await Promise.all(contributions.map(contrib => this.chatSessionsService.canResolveItemProvider(contrib.id)));
+		await Promise.all(contributions.map(contrib => this.chatSessionsService.canResolveItemProvider(contrib.type)));
 		const currentProviders = this.getAllChatSessionProviders();
 		const currentProviderIds = new Set(currentProviders.map(p => p.chatSessionType));
 

src/vs/workbench/contrib/chat/common/chatSessionsService.ts

@@ -14,12 +14,12 @@ import { IChatAgentRequest } from './chatAgents.js';
 import { IRelaxedExtensionDescription } from '../../../../platform/extensions/common/extensions.js';
 
 export interface IChatSessionsExtensionPoint {
-	id: string;
-	name: string;
-	displayName: string;
-	description: string;
-	extensionDescription: IRelaxedExtensionDescription;
-	when?: string;
+	readonly type: string;
+	readonly name: string;
+	readonly displayName: string;
+	readonly description: string;
+	readonly extensionDescription: IRelaxedExtensionDescription;
+	readonly when?: string;
 }
 export interface IChatSessionItem {
 

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

@@ -31,9 +31,8 @@ declare module 'vscode' {
 
 		/**
 		 * Provides a list of chat sessions.
-		 *
-		 * TODO: Do we need a flag to try auth if needed?
 		 */
+		// TODO: Do we need a flag to try auth if needed?
 		provideChatSessionItems(token: CancellationToken): ProviderResult<ChatSessionItem[]>;
 	}
 
@@ -60,10 +59,9 @@ declare module 'vscode' {
 		 * The full history of the session
 		 *
 		 * This should not include any currently active responses
-		 *
-		 * TODO: Are these the right types to use?
-		 * TODO: link request + response to encourage correct usage?
 		 */
+		// TODO: Are these the right types to use?
+		// TODO: link request + response to encourage correct usage?
 		readonly history: ReadonlyArray<ChatRequestTurn | ChatResponseTurn2>;
 
 		/**
@@ -79,27 +77,41 @@ declare module 'vscode' {
 		 * Handles new request for the session.
 		 *
 		 * If not set, then the session will be considered read-only and no requests can be made.
-		 *
-		 * TODO: Should we introduce our own type for `ChatRequestHandler` since not all field apply to chat sessions?
 		 */
+		// TODO: Should we introduce our own type for `ChatRequestHandler` since not all field apply to chat sessions?
 		readonly requestHandler: ChatRequestHandler | undefined;
 	}
 
 	export interface ChatSessionContentProvider {
 		/**
 		 * Resolves a chat session into a full `ChatSession` object.
 		 *
-		 * @param uri The URI of the chat session to open. Uris as structured as `vscode-chat-session:<chatSessionType>/id`
+		 * @param sessionId The id of the chat session to open.
 		 * @param token A cancellation token that can be used to cancel the operation.
 		 */
-		provideChatSessionContent(id: string, token: CancellationToken): Thenable<ChatSession>;
+		provideChatSessionContent(sessionId: string, token: CancellationToken): Thenable<ChatSession> | ChatSession;
 	}
 
 	export namespace chat {
+		/**
+		 * Registers a new {@link ChatSessionItemProvider chat session item provider}.
+		 *
+		 * To use this, also make sure to also add `chatSessions` contribution in the `package.json`.
+		 *
+		 * @param chatSessionType The type of chat session the provider is for.
+		 * @param provider The provider to register.
+		 *
+		 * @returns A disposable that unregisters the provider when disposed.
+		 */
 		export function registerChatSessionItemProvider(chatSessionType: string, provider: ChatSessionItemProvider): Disposable;
 
 		/**
+		 * Registers a new {@link ChatSessionContentProvider chat session content provider}.
+		 *
 		 * @param chatSessionType A unique identifier for the chat session type. This is used to differentiate between different chat session providers.
+		 * @param provider The provider to register.
+		 *
+		 * @returns A disposable that unregisters the provider when disposed.
 		 */
 		export function registerChatSessionContentProvider(chatSessionType: string, provider: ChatSessionContentProvider): Disposable;
 	}
@@ -114,7 +126,9 @@ declare module 'vscode' {
 	}
 
 	export namespace window {
-
-		export function showChatSession(chatSessionType: string, id: string, options: ChatSessionShowOptions): Thenable<void>;
+		/**
+		 * Shows a chat session in the panel or editor.
+		 */
+		export function showChatSession(chatSessionType: string, sessionId: string, options: ChatSessionShowOptions): Thenable<void>;
 	}
 }