Initial sketch of a controller based chat session item API

For #276243

Explores moving the chat session item api to use a controller instead of a provider

eslint.config.js

@@ -899,6 +899,7 @@ export default tseslint.config(
 					],
 					'verbs': [
 						'accept',
+						'archive',
 						'change',
 						'close',
 						'collapse',

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

@@ -26,30 +26,96 @@ declare module 'vscode' {
 		InProgress = 2
 	}
 
+	export namespace chat {
+		/**
+		 * Creates a new {@link ChatSessionItemController chat session item controller} with the given unique identifier.
+		 */
+		export function createChatSessionItemController(id: string): ChatSessionItemController;
+	}
+
 	/**
 	 * Provides a list of information about chat sessions.
 	 */
-	export interface ChatSessionItemProvider {
-		/**
-		 * Event that the provider can fire to signal that chat sessions have changed.
-		 */
-		readonly onDidChangeChatSessionItems: Event<void>;
+	export class ChatSessionItemController {
+		readonly id: string;
 
 		/**
-		 * Provides a list of chat sessions.
+		 * Unregisters the controller, disposing of its associated chat session items.
 		 */
-		// TODO: Do we need a flag to try auth if needed?
-		provideChatSessionItems(token: CancellationToken): ProviderResult<ChatSessionItem[]>;
-
-		// #region Unstable parts of API
+		dispose(): void;
 
 		/**
-		 * Event that the provider can fire to signal that the current (original) chat session should be replaced with a new (modified) chat session.
-		 * The UI can use this information to gracefully migrate the user to the new session.
+		 * Managed collection of chat session items
 		 */
-		readonly onDidCommitChatSessionItem: Event<{ original: ChatSessionItem /** untitled */; modified: ChatSessionItem /** newly created */ }>;
+		readonly items: ChatSessionItemCollection;
 
-		// #endregion
+		/**
+		 * Creates a new managed chat session item that be added to the collection.
+		 */
+		createChatSessionItem(resource: Uri, label: string): ChatSessionItem;
+
+		/**
+		 * Handler called to refresh the collection of chat session items.
+		 *
+		 * This is also called on first load to get the initial set of items.
+		 */
+		refreshHandler: () => Thenable<void>;
+
+		/**
+		 * Fired when an item is archived by the editor
+		 *
+		 * TODO: expose archive state on the item too? Or should this
+		 */
+		readonly onDidArchiveChatSessionItem: Event<ChatSessionItem>;
+
+		/**
+		 * Fired when an item is disposed by the editor
+		 */
+		readonly onDidDisposeChatSessionItem: Event<ChatSessionItem>;
+	}
+
+	/**
+	 * A collection of chat session items. It provides operations for managing and iterating over the items.
+	 */
+	export interface ChatSessionItemCollection extends Iterable<readonly [id: string, chatSessionItem: ChatSessionItem]> {
+		/**
+		 * Gets the number of items in the collection.
+		 */
+		readonly size: number;
+
+		/**
+		 * Replaces the items stored by the collection.
+		 * @param items Items to store.
+		 */
+		replace(items: readonly ChatSessionItem[]): void;
+
+		/**
+		 * Iterate over each entry in this collection.
+		 *
+		 * @param callback Function to execute for each entry.
+		 * @param thisArg The `this` context used when invoking the handler function.
+		 */
+		forEach(callback: (item: ChatSessionItem, collection: ChatSessionItemCollection) => unknown, thisArg?: any): void;
+
+		/**
+		 * Adds the chat session item to the collection. If an item with the same resource URI already
+		 * exists, it'll be replaced.
+		 * @param item Item to add.
+		 */
+		add(item: ChatSessionItem): void;
+
+		/**
+		 * Removes a single chat session item from the collection.
+		 * @param resource Item resource to delete.
+		 */
+		delete(resource: Uri): void;
+
+		/**
+		 * Efficiently gets a chat session item by resource, if it exists, in the collection.
+		 * @param resource Item resource to get.
+		 * @returns The found item or undefined if it does not exist.
+		 */
+		get(resource: Uri): ChatSessionItem | undefined;
 	}
 
 	export interface ChatSessionItem {
@@ -268,18 +334,6 @@ declare module 'vscode' {
 	}
 
 	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}.
 		 *