@ckeditor/ckeditor5-ai 48.3.1 → 48.4.0-alpha.0

package/dist/aichat/ui/feed/aichatfeedsuggestionitemview.d.ts

@@ -9,10 +9,11 @@ import { type Locale } from "@ckeditor/ckeditor5-utils";
 import { AIChatFeedItemView, type AIChatItemViewOptions } from "./aichatfeeditemview.js";
 import { type AISuggestionContentPartDefinition } from "../../../aicore/utils/getsuggestionpartsfromreply.js";
 import { type AISuggestionActionName } from "./aichatfeedsuggestionitemactionsview.js";
-import { type AIReplyChangeGroupState } from "../../../aicore/model/aireply.js";
+import { type AIReplyChangeGroupState, type AIReplyChangeGroupOutdatedReason } from "../../../aicore/model/aireply.js";
 import { type AISource } from "../../../aicore/aiconnector.js";
 import { type AISuggestionBodyViewContentPartView } from "../../../aicore/ui/suggestioncontainer/aisuggestioncontentpartview.js";
 import { type BodyCollection } from "@ckeditor/ckeditor5-ui";
+import { type AISuggestionGating } from "../../../aicore/ui/suggestioncontainer/aisuggestionbodyview.js";
 /**
 * A view for an AI suggestion item in the AI chat feed.
 *
@@ -44,7 +45,7 @@ export declare class AIChatFeedSuggestionItemView extends AIChatFeedItemView {
 	/**
 	* Updates the state of a content part by its index.
 	*/
-	updatePartState(index: number, state: AIReplyChangeGroupState): void;
+	updatePartState(index: number, state: AIReplyChangeGroupState, outdatedReason?: AIReplyChangeGroupOutdatedReason): void;
 	/**
 	* Sets the part active or not (active parts are those currently previewed in a dialog by the user).
 	*
@@ -55,6 +56,10 @@ export declare class AIChatFeedSuggestionItemView extends AIChatFeedItemView {
 	updateSources(sources: Array<AISource>): void;
 	getPartView(index: number): AISuggestionBodyViewContentPartView | null;
 	/**
+	* Applies the gating state to this suggestion's body view.
+	*/
+	setGating(gating: AISuggestionGating): void;
+	/**
 	* Marks the suggestion as done and additionally updates the visibility of the actions view
 	* depending if any suggestion parts are actionable.
 	*/

package/dist/aichathistory/aichathistoryui.d.ts

@@ -7,7 +7,6 @@
 */
 import { type Context, type Editor, ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
 import { AITabs } from "../aitabs/aitabs.js";
-import "../../theme/aichat/aichathistory.css";
 export declare const AI_CHAT_HISTORY_UI_EVENT_NAMES: readonly ["showConversationHistory", "removeConversation", "editConversationTitle", "setConversationPinned", "selectConversation", "startConversation"];
 export declare class AIChatHistoryUI extends ContextPlugin {
 	/**

package/dist/aichatshortcuts/aichatshortcuts.d.ts

@@ -7,8 +7,8 @@
 * @publicApi
 */
 import { AIChatUI } from "../aichat/aichatui.js";
+import { AICore } from "../aicore/aicore.js";
 import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
-import "../../theme/aichatshortcuts/aichatshortcuts.css";
 /**
 * The type of the shortcut.
 *
@@ -28,7 +28,7 @@ export declare class AIChatShortcuts extends ContextPlugin {
 	/**
 	* @inheritDoc
 	*/
-	static get requires(): PluginDependenciesOf<[AIChatUI]>;
+	static get requires(): PluginDependenciesOf<[AIChatUI, AICore]>;
 	/**
 	* @inheritDoc
 	*/

package/dist/aiconfig.d.ts

@@ -13,6 +13,7 @@ import { type AIQuickActionsConfig } from "./aiquickactions/aiquickactions.js";
 import { type AITranslateConfig } from "./aitranslate/aitranslate.js";
 import { type AIModelsConfig } from "./aicore/model/aimodels.js";
 import { type AIReviewModeConfig } from "./aireviewmode/aireviewmode.js";
+import { type AIDefaultContext } from "./aicore/model/aidefaultcontext.js";
 /**
 * The configuration for all AI-related functionalities.
 *
@@ -44,6 +45,88 @@ export interface AIConfig {
 	*/
 	serviceUrl?: string;
 	/**
+	* A list of context references that are automatically attached to AI features.
+	* Each entry references an administrator-managed context, which is a reusable
+	* collection of prompts and files defined through the AI service and identified by its `id`.
+	*
+	* **Note:** The headless gateway APIs
+	* ({@link module:ai/aireviewmode/aireviewgateway~AIReviewGateway},
+	* {@link module:ai/aitranslate/aitranslategateway~AITranslateGateway}, and
+	* {@link module:ai/aidocumentprocessing/aidocumentprocessinggateway~AIDocumentProcessingGateway}) are
+	* config-independent by design and do **not** apply this option. Pass their context references explicitly through
+	* the `contexts` run option instead.
+	*
+	* Each entry is a context reference optionally narrowed down to specific features via `features`. When
+	* `features` is omitted, the entry is attached to **every** AI feature:
+	*
+	* ```ts
+	* ClassicEditor
+	* 	.create( {
+	* 		// ... Other configuration options ...
+	* 		ai: {
+	* 			defaultContext: [
+	* 				// Attached to every AI feature.
+	* 				{ id: 'style-guide' },
+	*
+	* 				// Attached only to the `translate.*` quick actions and to every review command.
+	* 				{
+	* 					id: 'glossary',
+	* 					features: {
+	* 						quickActions: /^translate\./,
+	* 						review: true
+	* 					}
+	* 				}
+	* 			]
+	* 		}
+	* 	} )
+	* 	.then( ... )
+	* 	.catch( ... );
+	* ```
+	*
+	* Read more in {@link module:ai/aicore/model/aidefaultcontext~AIDefaultContext}.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	defaultContext?: AIDefaultContext;
+	/**
+	* Extra HTTP headers that the AI service should attach when it fetches document images that live behind
+	* authentication (for example a private CDN or a token-protected asset server) during image analysis.
+	*
+	* The value is a list of entries, each pairing a `domain` with the `headers` to attach. A header set is attached when
+	* the image URL starts with the entry's `domain`.
+	*
+	* Because the match is a plain string prefix, always scope each `domain` to a full origin ending with a slash, for
+	* example `https://assets.example.com/`, so it cannot match a look-alike host such as `https://assets.example.com.incorrect.example/`.
+	*
+	* It is applied only to the AI Chat message flow and the document processing flow, as these are the only cases where
+	* the AI service works with images embedded in the document.
+	*
+	* ```ts
+	* ClassicEditor.create( {
+	* 	ai: {
+	* 		extraHttpHeaders: [
+	* 			{ domain: 'https://assets.example.com/', headers: { authorization: 'Bearer <token>' } }
+	* 		]
+	* 	}
+	* } );
+	* ```
+	*
+	* Because authorization tokens expire and rotate, the value can also be a function. It is called for every request,
+	* so it can return fresh headers each time:
+	*
+	* ```ts
+	* ClassicEditor.create( {
+	* 	ai: {
+	* 		extraHttpHeaders: () => ( [
+	* 			{ domain: 'https://assets.example.com/', headers: { authorization: `Bearer ${ getFreshToken() }` } }
+	* 		] )
+	* 	}
+	* } );
+	* ```
+	*/
+	extraHttpHeaders?: AIExtraHttpHeaders | (() => AIExtraHttpHeaders);
+	/**
 	* The configuration of the {@link module:ai/aiassistant/aiassistant~AIAssistant AI Assistant feature}.
 	*
 	* Read more in {@link module:ai/aiassistant/aiassistant~AIAssistantConfig}.
@@ -243,3 +326,29 @@ export interface AIContainerCustom extends AIContainerBase {
 * * {@link module:ai/aiconfig~AIContainerCustom} - the AI user interface is displayed in a custom way.
 */
 export type AIContainerConfig = AIContainerSidebar | AIContainerOverlay | AIContainerCustom;
+/**
+* If fetching some resources (for example images) used during AI image analysis requires passing an additional
+* authorization factor in the form of additional HTTP headers:
+*
+* ```
+* extraHttpHeaders: [
+* 		{ domain: 'https://ckeditor.com/', headers: { authorization: 'Bearer xxx' } },
+* 		{ domain: 'https://example.com/', headers: { authorization: 'Bearer xxx' } }
+* ]
+* ```
+*
+* See {@link module:ai/aiconfig~AIConfig#extraHttpHeaders}.
+*/
+export type AIExtraHttpHeaders = Array<{
+	/**
+	* The origin the headers apply to. Matched as a plain string prefix against the image URL, so it should be a full
+	* origin ending with a slash, for example `https://assets.example.com/`.
+	*/
+	domain: string;
+	/**
+	* The HTTP headers to attach for the matching `domain`.
+	*/
+	headers: {
+		[header: string]: string;
+	};
+}>;

package/dist/aicore/aiconnector.d.ts

@@ -4,9 +4,11 @@
 */
 import { type Editor, type Context, ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
 import { CloudServices } from "@ckeditor/ckeditor5-cloud-services";
-import { type AIContextItemRequestData, type AIContextItemType } from "./model/aicontext.js";
+import { type AIContextRequestPart, type AIContextItemType } from "./model/aicontext.js";
+import { type AIContextRef, type AIContextRefRequestData } from "./model/aicontextref.js";
 import { type AICapabilitiesRequestData } from "./model/aicapabilities.js";
 import type { AIActionsNames } from "../aiactions/aiactions.js";
+import { type AIEditorConfig } from "./utils/geteditorconfig.js";
 /**
 * A plugin that handles communication with the AI API.
 */
@@ -43,11 +45,11 @@ export declare class AIConnector extends ContextPlugin {
 	/**
 	* Sends a request to the /actions/custom/calls endpoint and returns a response stream reader.
 	*/
-	executeCustomAction({ content, message, model, outputFormat }: AIConnectorExecuteCustomActionData): AIConnectorRequest;
+	executeCustomAction({ content, message, model, outputFormat, contexts }: AIConnectorExecuteCustomActionData): AIConnectorRequest;
 	/**
 	* Sends a request to the /actions/system/{actionName}/calls endpoint and returns a response stream reader.
 	*/
-	executeAction({ actionName, content, args }: AIConnectorExecuteActionData): AIConnectorRequest;
+	executeAction({ actionName, content, args, contexts }: AIConnectorExecuteActionData): AIConnectorRequest;
 	/**
 	* Uploads a file to the AI API for a specific conversation.
 	*/
@@ -102,6 +104,10 @@ export declare class AIConnector extends ContextPlugin {
 	*/
 	getModels(language?: string): AIModelRequest;
 	/**
+	* Returns the list of contexts available to the current token.
+	*/
+	listContexts(params?: AIListContextsParams): AIListContextsRequest;
+	/**
 	* Deletes a file from a conversation.
 	*/
 	deleteFile(conversationId: string, fileId: string): AIDeleteFileRequest;
@@ -132,15 +138,15 @@ export declare class AIConnector extends ContextPlugin {
 	/**
 	* Sends a request to the AI API '/reviews/system/{reviewName}/calls' endpoint and returns a response stream reader.
 	*/
-	callSystemReview({ reviewName, content, args }: AIConnectorSystemReviewData): AIConnectorRequest;
+	callSystemReview({ reviewName, content, args, contexts }: AIConnectorSystemReviewData): AIConnectorRequest;
 	/**
 	* Sends a request to the AI API '/documents/process' endpoint and returns the parsed JSON reply.
 	*/
-	processDocument({ document, prompt, model }: AIConnectorProcessDocumentData): AIConnectorProcessDocumentRequest;
+	processDocument({ content, prompt, model, capabilities, contexts }: AIConnectorProcessDocumentData): AIConnectorProcessDocumentRequest;
 	/**
 	* Sends a request to the AI API '/reviews/custom/calls' endpoint and returns a response stream reader.
 	*/
-	callCustomReview({ content, prompt, model }: AIConnectorCustomReviewData): AIConnectorRequest;
+	callCustomReview({ content, prompt, model, contexts }: AIConnectorCustomReviewData): AIConnectorRequest;
 	upsertAIChatRating(conversationId: string, messageId: string, rating: AIRating): AIUpdateRating;
 	upsertAIActionRating(actionName: string, callId: string, rating: AIRating): AIUpdateRating;
 	upsertCustomAIActionRating(callId: string, rating: AIRating): AIUpdateRating;
@@ -249,7 +255,7 @@ export type AICancelStreamRequest = {
 export type AIConnectorQueryAssistantData = {
 	message: string;
 	conversationId: string;
-	parts: Array<AIContextItemRequestData>;
+	parts: Array<AIContextRequestPart>;
 	capabilities: AICapabilitiesRequestData | undefined;
 	model: string;
 	attributes?: Record<string, unknown>;
@@ -341,6 +347,7 @@ export type AIUserMessageContent = {
 	type: AIContextItemType;
 	content: string;
 	mcpServerName: string;
+	editorConfig?: AIEditorConfig;
 	toolName?: string;
 	data?: Record<string, any>;
 	name?: string;
@@ -408,6 +415,49 @@ export type AIModelRequest = {
 	}>;
 	abortController: AbortController;
 };
+/**
+* A single context available to the current token, as returned by {@link module:ai/aicore/aiconnector~AIConnector#listContexts}.
+*
+* A context is an admin-managed, named collection of prompts and files. It is referenced elsewhere by its `id` through an
+* {@link module:ai/aicore/model/aicontextref~AIContextRef}.
+*/
+export type AIContextData = {
+	/**
+	* The stable identifier of the context. This is the value referenced by an
+	* {@link module:ai/aicore/model/aicontextref~AIContextRef}.
+	*/
+	id: string;
+	/**
+	* The human-readable name of the context.
+	*/
+	name?: string;
+	/**
+	* The optional description of the context.
+	*/
+	description?: string;
+	/**
+	* The optional custom attributes attached to the context.
+	*/
+	attributes?: Record<string, unknown>;
+};
+export type AIListContextsParams = {
+	/**
+	* The cursor of the page to fetch. When not specified, the first page is fetched.
+	*/
+	cursor?: string;
+	/**
+	* The number of items to fetch.
+	*/
+	limit?: number;
+	/**
+	* Determines the direction of sorting.
+	*/
+	order?: "desc" | "asc";
+};
+export type AIListContextsRequest = {
+	getContexts: () => Promise<Array<AIContextData>>;
+	abortController: AbortController;
+};
 export type AIDeleteFileRequest = {
 	execute: () => Promise<void>;
 	abortController: AbortController;
@@ -422,9 +472,10 @@ export type AIDeleteWebResourceRequest = {
 };
 export type AIConnectorExecuteCustomActionData = {
 	content: string;
-	message: string;
+	message?: string;
 	model: string;
 	outputFormat: "plainText" | "html";
+	contexts?: Array<AIContextRef>;
 };
 export type AIConnectorExecuteActionData = {
 	actionName: AIActionsNames;
@@ -432,6 +483,7 @@ export type AIConnectorExecuteActionData = {
 	args?: {
 		language?: string;
 	};
+	contexts?: Array<AIContextRef>;
 };
 export type AIConnectorSystemReviewData = {
 	reviewName: string;
@@ -439,19 +491,34 @@ export type AIConnectorSystemReviewData = {
 	args?: {
 		language?: string;
 	};
+	contexts?: Array<AIContextRef>;
 };
 export type AIConnectorCustomReviewData = {
 	content: string;
-	prompt: string;
+	prompt?: string;
 	model: string;
+	contexts?: Array<AIContextRef>;
+};
+export type AIConnectorProcessDocumentContentDocument = {
+	type: "document";
+	content: string;
+	selection?: Array<{
+		start: number;
+		end: number;
+	}>;
 };
 export type AIConnectorProcessDocumentData = {
-	document: string;
+	content: Array<AIConnectorProcessDocumentContentDocument | AIContextRefRequestData>;
 	prompt: string;
 	model: string;
+	capabilities?: AICapabilitiesRequestData;
+	contexts?: Array<AIContextRef>;
 };
 export type AIConnectorProcessDocumentReply = {
-	document: string;
+	documents: Array<{
+		document: string;
+		summary: string;
+	}>;
 	summary?: string;
 };
 export type AIConnectorProcessDocumentRequest = {

package/dist/aicore/aicore.d.ts

@@ -0,0 +1,53 @@
+/**
+* @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/aicore/aicore
+* @publicApi
+*/
+import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { AIConnector } from "./aiconnector.js";
+import { AIModels } from "./model/aimodels.js";
+import { AIContextLibrary } from "./model/aicontextlibrary.js";
+/**
+* A shared, context-level home for cross-feature AI state.
+*
+* It owns a single {@link module:ai/aicore/model/aimodels~AIModels} instance so the model list is
+* fetched once and shared across all AI features (chat, quick actions, review mode, gateway) instead
+* of each feature building its own. Access it via {@link #models}.
+*
+* It owns a single {@link module:ai/aicore/model/aicontextlibrary~AIContextLibrary} instance
+* so the list of contexts available to the current token is fetched once and shared. Access it via
+* {@link #contextLibrary}.
+*/
+export declare class AICore extends ContextPlugin {
+	/**
+	* The shared model registry — fetched once and shared across all AI features.
+	*/
+	models: AIModels;
+	/**
+	* The shared context library, fetched once and shared across all AI features.
+	*/
+	contextLibrary: AIContextLibrary;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AICore";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[AIConnector]>;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
+}

package/dist/aicore/aiediting.d.ts

@@ -7,6 +7,7 @@
 */
 import { type ModelRange, type ModelDocumentFragment } from "@ckeditor/ckeditor5-engine";
 import { ContextPlugin, type Context, Editor } from "@ckeditor/ckeditor5-core";
+import { type AIEditorConfig } from "./utils/geteditorconfig.js";
 export declare const AI_VISUAL_SELECTION_MARKER_NAME = "ai-selection";
 export declare class AIEditing extends ContextPlugin {
 	/**
@@ -40,8 +41,11 @@ export declare class AIEditing extends ContextPlugin {
 	*
 	* `rootName` and `channelId` identify the source of each entry so callers can remap AI modifications back to the editor and root
 	* they came from.
+	*
+	* Note, that this method is async and does significant processing if the editor data is big or custom output processor is registered.
+	* If you just want to fetch the session id or document version, use {@link #getSessionId} and {@link #getEditorsVersions}.
 	*/
-	getDocumentData(): Promise<Array<AIEditingDocumentData>>;
+	getDocumentData(channelIds?: Set<string>): Promise<Array<AIEditingDocumentData>>;
 	afterInit(): void;
 	/**
 	* Displays a fake visual selection on given ranges.
@@ -57,7 +61,7 @@ export declare class AIEditing extends ContextPlugin {
 	* @param id ID of the fake visual selection to remove.
 	*/
 	hideFakeVisualSelection(id: string): void;
-	modelToDataWithIds(modelFragment: ModelDocumentFragment, editor: Editor): Promise<string>;
+	modelToDataWithIds(modelFragment: ModelDocumentFragment, editor: Editor, rootName?: string): Promise<string>;
 }
 /**
 * A single document entry returned by {@link module:ai/aicore/aiediting~AIEditing#getDocumentData `AIEditing#getDocumentData()`}. One
@@ -77,6 +81,8 @@ export type AIEditingDocumentData = {
 		end: number;
 		htmlFragment: string;
 	}>;
+	selectionSignature: string;
+	editorConfig: AIEditorConfig;
 	name?: string;
 	description?: string;
 };

package/dist/aicore/aigateway.d.ts

@@ -8,10 +8,13 @@
 */
 import { ContextPlugin, type PluginDependenciesOf, type Editor } from "@ckeditor/ckeditor5-core";
 import { DocumentCompare } from "@ckeditor/ckeditor5-collaboration-core";
+import { AICore } from "./aicore.js";
+import { type AIModels } from "./model/aimodels.js";
 import { AIResponseApplier } from "./pipeline/airesponseapplier.js";
-import { type AIRunResult } from "./model/airunresult.js";
-import { type AIModelData } from "./aiconnector.js";
+import { type AIEditorRoot } from "./model/aieditorroot.js";
 import { type AIOperationSource } from "./utils/markoperationsasai.js";
+import type { AIRunResult } from "./model/airunresult.js";
+import { type AIContextRef } from "./model/aicontextref.js";
 /**
 * How AI run changes are applied to the editor when using {@link module:ai/aicore/aigateway~AIGateway#apply}.
 */
@@ -35,6 +38,13 @@ export type AIRunBaseOptions = {
 	* An `AbortSignal` that cancels the run when aborted. Aborted runs resolve with `status: 'aborted'`.
 	*/
 	signal?: AbortSignal;
+	/**
+	* Context references attached to the request.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	contexts?: Array<AIContextRef>;
 };
 export type AIGatewayApplyOptions = {
 	/**
@@ -54,6 +64,11 @@ export type AIGatewayApplyOptions = {
 	* plugin uses this attribute to display the suggestion as AI-generated.
 	*/
 	aiSource?: AIOperationSource;
+	/**
+	* Restrict the apply to a subset of the result's per-root entries. Each entry's `channelId` and `rootName` must match
+	* a per-root sub-result in the passed `AIRunResult`. When omitted, every entry in `result.results` is applied.
+	*/
+	roots?: Array<AIEditorRoot>;
 };
 /**
 * Base plugin exposing common methods for end-to-end public AI API.
@@ -66,7 +81,16 @@ export declare class AIGateway extends ContextPlugin {
 	/**
 	* @inheritDoc
 	*/
-	static get requires(): PluginDependenciesOf<[DocumentCompare]>;
+	static get requires(): PluginDependenciesOf<[DocumentCompare, AICore]>;
+	/**
+	* The shared model registry. Exposed here so headless gateways are self-sufficient — integrators can
+	* discover and resolve models (`getAvailableModels()`, `getModel()`, `resolveModel()`, …) without
+	* reaching for the `AICore` plugin directly.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	get models(): AIModels;
 	/**
 	* @inheritDoc
 	*/
@@ -76,16 +100,24 @@ export declare class AIGateway extends ContextPlugin {
 	*/
 	static override get isPremiumPlugin(): true;
 	/**
-	* Returns the list of AI models available to be used with AI gateway features.
+	* Applies an AI run result to editor content. Accepts the whole `AIRunResult` — per-root sub-results targeting
+	* the same editor are batched into one `model.change()` block, so all of that editor's roots become a single
+	* undoable step. An optional `options.roots` filter restricts the apply to a subset of the sub-results without the
+	* caller having to unpack or repack the result.
 	*
-	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
-	* without the standard deprecation policy. Check the changelog for migration guidance.
-	*/
-	getAvailableModels(): Promise<Array<AIModelData>>;
-	/**
-	* Applies the AI run result to the editor content.
+	* Refuses the call up front only on whole-run failures (`result.error` set or empty `result.results`). Per-root
+	* failures on an otherwise successful run are validated after the filter, so the caller can filter around the
+	* failed roots via `options.roots` and still apply the completed ones. If any *included* sub-result fails
+	* validation the whole call throws before touching any editor, so partial applies can't leave content in a
+	* mixed state.
+	*
+	* `options.roots` is validated at the call boundary — an explicitly empty array throws
+	* `ai-gateway-apply-empty-roots`, and any entry that does not match a per-root sub-result in
+	* `result.results` throws `ai-gateway-apply-root-not-found`.
 	*
-	* Throws `ai-no-track-changes` when `options.applyMethod` is `'suggest'` and the `TrackChanges` plugin is not loaded.
+	* Also throws `ai-gateway-apply-invalid-status` when the whole run failed or when any included sub-result's
+	* `status` is not `'completed'`, and `ai-no-track-changes` when `options.applyMethod` is `'suggest'` and any
+	* targeted editor is missing the `TrackChanges` plugin.
 	*
 	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
 	* without the standard deprecation policy. Check the changelog for migration guidance.

package/dist/aicore/errors/normalizeerror.d.ts

@@ -10,6 +10,10 @@ import { CKEditorError } from "@ckeditor/ckeditor5-utils";
 * Wraps an arbitrary thrown value in a {@link module:utils/ckeditorerror~CKEditorError} with the given `errorName`,
 * unless it already is a `CKEditorError`.
 *
+* If the thrown value carries a `data` field (as backend API errors do — see {@link module:ai/aicore/aiconnector~AIConnector}),
+* it is attached to the wrapped error as `data.backendData` so consumers can inspect the backend's structured response
+* (for example `issues[]` describing which fields failed validation).
+*
 * @param error The thrown value to normalize.
 * @param errorName The `error-name` used when wrapping a non-`CKEditorError`.
 * @param context The error context (typically the plugin instance) used by the watchdog.

package/dist/aicore/model/aicapabilities.d.ts

@@ -4,10 +4,11 @@
 */
 /**
 * @module ai/aicore/model/aicapabilities
+* @publicApi
 */
 import { type EmitterMixinConstructor } from "@ckeditor/ckeditor5-utils";
 declare const AICapabilitiesBase: EmitterMixinConstructor;
-export declare const CAPABILITIES_MODEL_EVENT_NAMES: readonly ["capabilitiesUpdated"];
+export declare const AI_CAPABILITIES_MODEL_EVENT_NAMES: readonly ["capabilitiesUpdated"];
 /**
 * Manages the AI capabilities configuration and state.
 */
@@ -28,10 +29,13 @@ export declare class AICapabilities extends AICapabilitiesBase {
 	*/
 	getCapabilitiesConfig(): AICapabilitiesConfig;
 	/**
-	* Converts capabilities configuration to request data format for API endpoint.
-	* @returns The request data or undefined if no capabilities are enabled.
+	* Converts a capabilities configuration to the wire-shape consumed by the AI API endpoints.
+	*
+	* Accepts either the simple chat-style config (`isWebSearchEnabled` / `isReasoningEnabled`) or the advanced
+	* per-call directive (`webSearch` / `reasoning`, where `reasoning` may also be a level string such as `'low'`
+	* or `'minimal'`).
 	*/
-	static getCapabilitiesRequestData(config: AICapabilitiesConfig | undefined): AICapabilitiesRequestData;
+	static getCapabilitiesRequestData(config: AICapabilitiesConfig | AICapabilitiesConfigAdvanced | undefined): AICapabilitiesRequestData;
 	/**
 	* Toggles the web search enabled state.
 	*/
@@ -57,8 +61,19 @@ export type AICapabilitiesConfig = {
 	isWebSearchEnabled: boolean;
 	isReasoningEnabled: boolean;
 };
+/**
+* Reasoning level accepted by the AI service. Controls how much effort the model is allowed to spend
+* on reasoning before producing the final reply.
+*/
+export type AIReasoningLevel = "minimal" | "low" | "balanced" | "thorough" | "maximum";
+export type AICapabilitiesConfigAdvanced = {
+	webSearch?: boolean;
+	reasoning?: boolean | AIReasoningLevel;
+};
 export type AICapabilitiesRequestData = {
 	webSearch?: object;
-	reasoning?: object;
+	reasoning?: {
+		level?: AIReasoningLevel;
+	};
 };
 export {};