@ckeditor/ckeditor5-ai 48.8.1-alpha.4 → 49.0.0-alpha.1

package/dist/aichat/model/aichatconversation.d.ts

@@ -1,292 +1,293 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module ai/aichat/model/aichatconversation
- */
-import { CKEditorError, type Locale } from '@ckeditor/ckeditor5-utils';
-import type { AIConnector, AIModelData } from '../../aicore/aiconnector.js';
-import { AIChatContext, type AIChatContextConfig, type AIContextProvider, type AIContextResource, type AIContextResourceState } from './aichatcontext.js';
-import { type AIToolContextItem, type AIContextItem } from '../../aicore/model/aicontext.js';
-import { AICapabilities, type AICapabilitiesConfig } from '../../aicore/model/aicapabilities.js';
-import type { AIModels } from '../../aicore/model/aimodels.js';
-import { type Editor } from '@ckeditor/ckeditor5-core';
-import { AIChatInteraction } from './aichatinteraction.js';
-declare const AIChatConversation_base: {
-    new (): import("@ckeditor/ckeditor5-utils").Emitter;
-    prototype: import("@ckeditor/ckeditor5-utils").Emitter;
-};
+* @module ai/aichat/model/aichatconversation
+*/
+import { type EmitterMixinConstructor, type Locale } from "@ckeditor/ckeditor5-utils";
+import type { AIConnector, AIModelData } from "../../aicore/aiconnector.js";
+import { AIChatContext, type AIChatContextConfig, type AIContextProvider, type AIContextResource, type AIContextResourceState } from "./aichatcontext.js";
+import { type AIToolContextItem, type AIContextItem } from "../../aicore/model/aicontext.js";
+import { type AIEditing } from "../../aicore/aiediting.js";
+import { AICapabilities, type AICapabilitiesConfig } from "../../aicore/model/aicapabilities.js";
+import type { AIModels } from "../../aicore/model/aimodels.js";
+import { type Editor } from "@ckeditor/ckeditor5-core";
+import { AIChatInteraction } from "./aichatinteraction.js";
+declare const AIChatConversationBase: EmitterMixinConstructor;
 /**
- * Represents a conversation between the user and the AI endpoint on top of the
- * {@link module:ai/aichat/model/aichatconnector~AIChatConnector} in the network layer.
- *
- * A conversation hosts a collection of {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction user interactions}.
- *
- * The {@link module:ai/aichat/model/aichatconversation~AIChatConversation#currentInteraction current interaction} in the conversation
- * is the one that is currently being processed by the AI.
- *
- * Note: The conversation funnels (delegates) all events from the
- * {@link module:ai/aichat/model/aichatconversation~AIChatConversation#interactions} and their
- * {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction#replies replies}.
- */
-export declare class AIChatConversation extends /* #__PURE__ */ AIChatConversation_base {
-    /**
-     * The unique conversation ID.
-     */
-    id: string;
-    /**
-     * Indicates whether the conversation has been started.
-     *
-     * This is set to `true` when {@link #start} is called and the conversation is successfully started.
-     */
-    isStarted: boolean;
-    /**
-     * Indicates whether the conversation is from history.
-     */
-    isFromHistory: boolean;
-    /**
-     * The interactions in the conversation.
-     */
-    interactions: Array<AIChatInteraction>;
-    /**
-     * The current interaction in the conversation. Set and unset by {@link #handleUserInteraction}.
-     */
-    currentInteraction?: AIChatInteraction;
-    /**
-     * The selected AI chat model for the conversation.
-     *
-     * This is set when the user selects a model from the list of available models.
-     * If not set, the default model will be used.
-     */
-    selectedModel?: AIModelData;
-    /**
-     * Service for managing the conversation context.
-     */
-    chatContext: AIChatContext;
-    /**
-     * Service for managing the conversation capabilities.
-     */
-    chatCapabilities: AICapabilities;
-    /**
-     * Service for providing the list of available AI chat models.
-     */
-    chatModels: AIModels;
-    /**
-     * @inheritDoc
-     */
-    constructor(options: AIChatConversationOptions);
-    /**
-     * Initializes the conversation.
-     */
-    init(contextConfig?: AIChatContextConfig): Promise<void>;
-    start(): Promise<void>;
-    /**
-     * Loads a conversation from the backend using the provided conversation ID.
-     */
-    load(conversationId: string, sessionId: string): Promise<AIChatConversation>;
-    /**
-     * Processes messages to create interactions and replies.
-     */
-    private _processMessagesToInteractions;
-    /**
-     * Handles a user interaction by creating a new interaction and starting it.
-     */
-    handleUserInteraction({ userMessage, attributes }: {
-        userMessage: string;
-        attributes?: Record<string, unknown>;
-    }): Promise<void>;
-    /**
-     * Creates a new interaction and stores it in the conversation.
-     */
-    createInteraction({ userMessage, contextItems, capabilities, modelId, attributes }: {
-        userMessage: string;
-        contextItems: Map<string, AIContextItem>;
-        capabilities: AICapabilitiesConfig;
-        modelId: string;
-        attributes?: Record<string, unknown>;
-    }): AIChatInteraction;
-    /**
-     * Gets an interaction in the conversation by its ID.
-     */
-    getInteraction(id: string): AIChatInteraction | undefined;
-    /**
-     * Removes an interaction from the conversation by its ID.
-     */
-    removeInteraction(id: string): void;
-    /**
-     * Gets the last of {@link #interactions} in the conversation.
-     */
-    get lastInteraction(): AIChatInteraction | undefined;
-    /**
-     * Adds a current document to the context.
-     */
-    addCurrentDocumentToContext(label: string): void;
-    /**
-     * Updates the current document in the context to contain the necessary data.
-     */
-    updateCurrentDocumentInContext({ content, version, sessionId, channelId, rootName, selections }: {
-        content: string | undefined;
-        version: number;
-        sessionId: string | null;
-        channelId: string;
-        rootName: string;
-        selections: Array<{
-            start: number;
-            end: number;
-            htmlFragment: string;
-        }>;
-    }): Promise<void>;
-    /**
-     * Returns the content of the current interaction's document.
-     */
-    getCurrentDocumentContext(): string;
-    /**
-     * Adds a selection to the context.
-     */
-    addSelectionToContext(selection: string): void;
-    removeSelectionFromContext(): void;
-    /**
-     * Adds files to the context.
-     */
-    addFilesToContext(files: Array<File>): void;
-    /**
-     * Adds a URL to the context.
-     */
-    addUrlToContext(url: string): void;
-    /**
-     * Adds a tool-related item to the context.
-     */
-    addToolItemToContext(item: AIToolContextItem): void;
-    /**
-     * Adds a resource from a source provider to the context.
-     */
-    addResourceToContext(source: AIContextProvider, resource: AIContextResource): void;
-    /**
-     * Loads resources for a given source provider.
-     */
-    loadSourceResources(sourceId: string, query: string, uid: string): Promise<Array<AIContextResourceState>>;
-    /**
-     * Removes an item from the conversation context by its ID.
-     */
-    removeFromContext(id: string): void;
-    /**
-     * Sets the web search search functionality state.
-     */
-    setWebSearch(isWebSearchEnabled: boolean): void;
-    /**
-     * Toggles the web search functionality on or off.
-     */
-    toggleWebSearch(): void;
-    /**
-     * Sets the reasoning functionality state.
-     */
-    setReasoning(isReasoningEnabled: boolean): void;
-    /**
-     * Toggles the reasoning functionality on or off.
-     */
-    toggleReasoning(): void;
-    /**
-     * Checks if the current document is already in the conversation context.
-     */
-    isCurrentDocumentInContext(): boolean;
-    /**
-     * Checks if the current document is already in the conversation context.
-     */
-    isCurrentDocumentInConversation(): boolean;
-    /**
-     * Checks if the selection is already in the conversation context.
-     */
-    isSelectionInContext(): boolean;
-    /**
-     * Sets the AI model for the conversation.
-     */
-    setModel(model: AIModelData): Promise<void>;
+* Represents a conversation between the user and the AI endpoint on top of the
+* {@link module:ai/aichat/model/aichatconnector~AIChatConnector} in the network layer.
+*
+* A conversation hosts a collection of {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction user interactions}.
+*
+* The {@link module:ai/aichat/model/aichatconversation~AIChatConversation#currentInteraction current interaction} in the conversation
+* is the one that is currently being processed by the AI.
+*
+* Note: The conversation funnels (delegates) all events from the
+* {@link module:ai/aichat/model/aichatconversation~AIChatConversation#interactions} and their
+* {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction#replies replies}.
+*/
+export declare class AIChatConversation extends AIChatConversationBase {
+	/**
+	* The unique conversation ID.
+	*/
+	id: string;
+	/**
+	* Indicates whether the conversation has been started.
+	*
+	* This is set to `true` when {@link #start} is called and the conversation is successfully started.
+	*/
+	isStarted: boolean;
+	/**
+	* Indicates whether the conversation is from history.
+	*/
+	isFromHistory: boolean;
+	/**
+	* The interactions in the conversation.
+	*/
+	interactions: Array<AIChatInteraction>;
+	/**
+	* The current interaction in the conversation. Set and unset by {@link #handleUserInteraction}.
+	*/
+	currentInteraction?: AIChatInteraction;
+	/**
+	* The selected AI chat model for the conversation.
+	*
+	* This is set when the user selects a model from the list of available models.
+	* If not set, the default model will be used.
+	*/
+	selectedModel?: AIModelData;
+	/**
+	* Service for managing the conversation context.
+	*/
+	chatContext: AIChatContext;
+	/**
+	* Service for managing the conversation capabilities.
+	*/
+	chatCapabilities: AICapabilities;
+	/**
+	* Service for providing the list of available AI chat models.
+	*/
+	chatModels: AIModels;
+	/**
+	* @inheritDoc
+	*/
+	constructor(options: AIChatConversationOptions);
+	/**
+	* Initializes the conversation.
+	*/
+	init(contextConfig?: AIChatContextConfig): Promise<void>;
+	start(): Promise<void>;
+	/**
+	* Loads a conversation from the backend using the provided conversation ID.
+	*/
+	load(conversationId: string): Promise<AIChatConversation>;
+	/**
+	* Processes messages to create interactions and replies.
+	*/
+	private _processMessagesToInteractions;
+	/**
+	* Resumes an in-progress stream for a message that was still streaming when the conversation was loaded.
+	* Runs in the background - events propagate through the normal event system.
+	*/
+	private _resumeStream;
+	/**
+	* Handles a user interaction by creating a new interaction and starting it.
+	*/
+	handleUserInteraction({ userMessage, attributes }: {
+		userMessage: string;
+		attributes?: Record<string, unknown>;
+	}): Promise<void>;
+	stopProcessing(): void;
+	/**
+	* Creates a new interaction and stores it in the conversation.
+	*/
+	createInteraction({ userMessage, contextItems, capabilities, modelId, attributes, channelsToEditors }: {
+		userMessage: string;
+		contextItems: Map<string, AIContextItem>;
+		capabilities: AICapabilitiesConfig;
+		modelId: string;
+		attributes?: Record<string, unknown>;
+		channelsToEditors: Map<string, Editor>;
+	}): AIChatInteraction;
+	/**
+	* Gets an interaction in the conversation by its ID.
+	*/
+	getInteraction(id: string): AIChatInteraction | undefined;
+	/**
+	* Removes an interaction from the conversation by its ID.
+	*/
+	removeInteraction(id: string): void;
+	/**
+	* Gets the last of {@link #interactions} in the conversation.
+	*/
+	get lastInteraction(): AIChatInteraction | undefined;
+	/**
+	* Cancels the reply stream of the {@link #lastInteraction last interaction}.
+	* No-op when the last interaction has no `messageId` yet.
+	*/
+	cancelLastInteractionStream(): void;
+	/**
+	* Adds a current document to the context.
+	*/
+	addCurrentDocumentToContext(label: string): void;
+	/**
+	* Adds a selection to the context.
+	*/
+	addSelectionToContext(selection: string): void;
+	removeSelectionFromContext(): void;
+	/**
+	* Adds files to the context.
+	*/
+	addFilesToContext(files: Array<File>): void;
+	/**
+	* Adds a URL to the context.
+	*/
+	addUrlToContext(url: string): void;
+	/**
+	* Adds a tool-related item to the context.
+	*/
+	addToolItemToContext(item: AIToolContextItem): void;
+	/**
+	* Adds a reference to an admin-managed context from the Context Library to the context.
+	*/
+	addLibraryContextToContext(libraryContextId: string, label?: string): void;
+	/**
+	* Adds a resource from a source provider to the context.
+	*/
+	addResourceToContext(source: AIContextProvider, resource: AIContextResource): void;
+	/**
+	* Loads resources for a given source provider.
+	*/
+	loadSourceResources(sourceId: string, query: string, uid: string): Promise<Array<AIContextResourceState>>;
+	/**
+	* Removes an item from the conversation context by its ID.
+	*/
+	removeFromContext(id: string): void;
+	/**
+	* Sets the web search search functionality state.
+	*/
+	setWebSearch(isWebSearchEnabled: boolean): void;
+	/**
+	* Toggles the web search functionality on or off.
+	*/
+	toggleWebSearch(): void;
+	/**
+	* Sets the reasoning functionality state.
+	*/
+	setReasoning(isReasoningEnabled: boolean): void;
+	/**
+	* Toggles the reasoning functionality on or off.
+	*/
+	toggleReasoning(): void;
+	/**
+	* Checks if the current document is already in the conversation context.
+	*/
+	isCurrentDocumentInContext(): boolean;
+	/**
+	* Checks if the current document is already in the conversation context.
+	*/
+	isCurrentDocumentInConversation(): boolean;
+	/**
+	* Checks if the selection is already in the conversation context.
+	*/
+	isSelectionInContext(): boolean;
+	/**
+	* Returns the pending context items that will be sent to the AI endpoint in the next interaction.
+	*/
+	getPendingContextItems(): ReadonlyMap<string, AIContextItem>;
+	/**
+	* Sets the AI model for the conversation.
+	*/
+	setModel(model: AIModelData): Promise<void>;
 }
 /**
- * An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when a new interaction is created.
- *
- * @eventName ~AIChatConversation#interactionCreated
- */
+* An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when a new interaction is created.
+*
+* @eventName ~AIChatConversation#interactionCreated
+*/
 export type AIChatInteractionCreatedEvent = {
-    name: 'interactionCreated';
-    args: [interaction: AIChatInteraction];
+	name: "interactionCreated";
+	args: [interaction: AIChatInteraction];
 };
 /**
- * An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when an error occurs.
- *
- * @eventName ~AIChatConversation#error
- */
+* An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when an error occurs.
+*
+* @eventName ~AIChatConversation#error
+*/
 export type AIChatConversationError = {
-    name: 'error';
-    args: [
-        {
-            interactionId?: string;
-            error: CKEditorError;
-            fileName?: string;
-            url?: string;
-            sourceId?: string;
-            sourceLabel?: string;
-        }
-    ];
+	name: "error";
+	args: [{
+		interactionId?: string;
+		error: Error;
+		fileName?: string;
+		url?: string;
+		sourceId?: string;
+		sourceLabel?: string;
+	}];
 };
 /**
- * An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation#init} once the conversation was initialized.
- *
- * @eventName ~AIChatConversation#conversationInitialized
- */
+* An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation#init} once the conversation was initialized.
+*
+* @eventName ~AIChatConversation#conversationInitialized
+*/
 export type AIChatConversationInitializedEvent = {
-    name: 'conversationInitialized';
-    args: [
-        {
-            availableModels: Array<AIModelData>;
-        }
-    ];
+	name: "conversationInitialized";
+	args: [{
+		availableModels: Array<AIModelData>;
+	}];
 };
 /**
- * An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation#start} once the conversation was started.
- *
- * @eventName ~AIChatConversation#conversationStarted
- */
+* An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation#start} once the conversation was started.
+*
+* @eventName ~AIChatConversation#conversationStarted
+*/
 export type AIChatConversationStartedEvent = {
-    name: 'conversationStarted';
-    args: [
-        {
-            conversationId: string;
-            selectedModel: AIModelData;
-        }
-    ];
+	name: "conversationStarted";
+	args: [{
+		conversationId: string;
+		selectedModel: AIModelData;
+	}];
 };
 /**
- * An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when a model is selected.
- *
- * @eventName ~AIChatConversation#modelSelected
- */
+* An event emitted by {@link module:ai/aichat/model/aichatconversation~AIChatConversation} when a model is selected.
+*
+* @eventName ~AIChatConversation#modelSelected
+*/
 export type AIChatConversationModelSelectedEvent = {
-    name: 'modelSelected';
-    args: [
-        {
-            selectedModel?: AIModelData;
-            isDisabled?: boolean;
-        }
-    ];
+	name: "modelSelected";
+	args: [{
+		selectedModel?: AIModelData;
+		isDisabled?: boolean;
+	}];
 };
 /**
- * Options for the AI chat conversation.
- */
+* Options for the AI chat conversation.
+*/
 export type AIChatConversationOptions = {
-    connector: AIConnector;
-    chatModels: AIModels;
-    getEditor?: () => Editor;
-    getEditors?: () => Array<Editor>;
-    /**
-     * Locale forwarded to {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction interactions} (and through them to
-     * replies) for translating internal user-facing strings — see {@link module:ai/aicore/model/aiinteraction~AIInteractionOptions}.
-     */
-    locale?: Locale;
-    conversationId: string;
-    group: string;
-    selectedModelId?: string;
-    isFromHistory: boolean;
+	connector: AIConnector;
+	chatModels: AIModels;
+	/**
+	* Locale forwarded to {@link module:ai/aichat/model/aichatinteraction~AIChatInteraction interactions} (and through them to
+	* replies) for translating internal user-facing strings — see {@link module:ai/aicore/model/aiinteraction~AIInteractionOptions}.
+	*/
+	locale?: Locale;
+	conversationId: string;
+	group: string;
+	selectedModelId?: string;
+	isFromHistory: boolean;
+	/**
+	* Returns the session ID of the given editor. Used by the conversation when detecting whether a stored
+	* AI chat reply was created during the current editing session of its source editor.
+	*/
+	getSessionId: (editor: Editor) => string;
+	/**
+	* The {@link module:ai/aicore/aiediting~AIEditing} context plugin. The conversation uses its context-level utilities
+	* (e.g. {@link module:ai/aicore/aiediting~AIEditing#getDocumentData} and
+	* {@link module:ai/aicore/aiediting~AIEditing#getEditorsVersions}) to refresh the current-document context, instead of
+	* reaching for individual editor instances.
+	*/
+	aiEditing: AIEditing;
 };
 export {};