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

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

@@ -1,63 +1,79 @@
 /**
- * @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
- */
-export declare const CAPABILITIES_MODEL_EVENT_NAMES: readonly ["capabilitiesUpdated"];
-declare const AICapabilities_base: {
-    new (): import("@ckeditor/ckeditor5-utils").Emitter;
-    prototype: import("@ckeditor/ckeditor5-utils").Emitter;
-};
+* @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/model/aicapabilities
+* @publicApi
+*/
+import { type EmitterMixinConstructor } from "@ckeditor/ckeditor5-utils";
+declare const AICapabilitiesBase: EmitterMixinConstructor;
+export declare const AI_CAPABILITIES_MODEL_EVENT_NAMES: readonly ["capabilitiesUpdated"];
 /**
- * Manages the AI capabilities configuration and state.
- */
-export declare class AICapabilities extends /* #__PURE__ */ AICapabilities_base {
-    constructor();
-    /**
-     * Initializes the capabilities.
-     */
-    init(): void;
-    /**
-     * Resets the capabilities configuration to default state.
-     */
-    reset(): void;
-    /**
-     * Returns the current capabilities configuration.
-     *
-     * @returns The current capabilities configuration.
-     */
-    getCapabilitiesConfig(): AICapabilitiesConfig;
-    /**
-     * Converts capabilities configuration to request data format for API endpoint.
-     * @returns The request data or undefined if no capabilities are enabled.
-     */
-    static getCapabilitiesRequestData(config: AICapabilitiesConfig | undefined): AICapabilitiesRequestData;
-    /**
-     * Toggles the web search enabled state.
-     */
-    toggleWebSearch(): void;
-    /**
-     * Toggles the reasoning enabled state.
-     */
-    toggleReasoning(): void;
-    /**
-     * Sets the web search enabled state and fires an event with current state.
-     */
-    setWebSearch(isWebSearchEnabled: boolean): void;
-    /**
-     * Sets the reasoning enabled state and fires an event with current state.
-     */
-    setReasoning(isReasoningEnabled: boolean): void;
+* Manages the AI capabilities configuration and state.
+*/
+export declare class AICapabilities extends AICapabilitiesBase {
+	constructor();
+	/**
+	* Initializes the capabilities.
+	*/
+	init(): void;
+	/**
+	* Resets the capabilities configuration to default state.
+	*/
+	reset(): void;
+	/**
+	* Returns the current capabilities configuration.
+	*
+	* @returns The current capabilities configuration.
+	*/
+	getCapabilitiesConfig(): AICapabilitiesConfig;
+	/**
+	* 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 | AICapabilitiesConfigAdvanced | undefined): AICapabilitiesRequestData;
+	/**
+	* Toggles the web search enabled state.
+	*/
+	toggleWebSearch(): void;
+	/**
+	* Toggles the reasoning enabled state.
+	*/
+	toggleReasoning(): void;
+	/**
+	* Sets the web search enabled state and fires an event with current state.
+	*/
+	setWebSearch(isWebSearchEnabled: boolean): void;
+	/**
+	* Sets the reasoning enabled state and fires an event with current state.
+	*/
+	setReasoning(isReasoningEnabled: boolean): void;
 }
 export type AICapabilitiesUpdatedEvent = {
-    name: 'capabilitiesUpdated';
-    args: [AICapabilitiesConfig];
+	name: "capabilitiesUpdated";
+	args: [AICapabilitiesConfig];
 };
 export type AICapabilitiesConfig = {
-    isWebSearchEnabled: boolean;
-    isReasoningEnabled: boolean;
+	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;
+	webSearch?: object;
+	reasoning?: {
+		level?: AIReasoningLevel;
+	};
 };
 export {};

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

@@ -1,92 +1,131 @@
 /**
- * @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/aicore/model/aicontext
- * @publicApi
- */
-import type { Editor } from '@ckeditor/ckeditor5-core';
+* @module ai/aicore/model/aicontext
+* @publicApi
+*/
+import { type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
+import { type AIEditorConfig } from "../utils/geteditorconfig.js";
+import { type AIContextRef, type AIContextRefRequestData } from "./aicontextref.js";
 /**
- * Locates a `data-id` from AI chat document HTML in a specific editor model root (multi-editor / multi-root contexts).
- */
-export type AIDataIdDocumentSource = {
-    editor: Editor;
-    rootName: string;
-};
-/**
- * One concatenation segment of the AI chat document HTML (single editor model root). The post-AI portion of the merged document that
- * belongs to this slice is recovered by routing each top-level child via `AIReply#dataIdDocumentSources`, not by index.
- */
-export type AIDocumentContextSlice = {
-    editor: Editor;
-    rootName: string;
-    html: string;
-    version: number;
-};
+* The type of context item.
+*
+* Available types:
+* * `'mcp-tool-context'`: a tool-related context item,
+* * `'file'`: a file (PDF, Word document, etc.),
+* * `'document'`: all current editors documents (one per each root in each editor),
+* * `'image'`: an image file — internal sub-type of file, derived from the file's MIME type
+*   so the chip renders a distinct icon. Serialized to the backend as `'file'`.
+*   (used by {@link module:ai/aichat/model/aichatcontext~AIChatContextConfig#document `config.ai.chat.context.document` option}),
+* * `'web-resource'`: a URL (web page, blog post, etc.),
+* * `'text'`: a text (plain text, Markdown, HTML, etc.),
+* * `'selection'`: a selection of text in the editor
+*   (used by {@link module:ai/aiquickactions/aiquickactions~AIQuickActions AI Quick Actions} that pass the user selection
+*   to the {@link module:ai/aichat/aichat~AIChat AI Chat}),
+* * `'context'`: a reference to an admin-managed context.
+*/
+export type AIContextItemType = "mcp-tool-context" | "file" | "image" | "document" | "web-resource" | "text" | "selection" | "context";
 /**
- * The type of context item.
- *
- * Available types:
- * * `'mcp-tool-context'`: a tool-related context item,
- * * `'file'`: a file (PDF, Word document, etc.),
- * * `'document'`: a current editor document
- *   (used by {@link module:ai/aichat/model/aichatcontext~AIChatContextConfig#document `config.ai.chat.context.document` option}),
- * * `'web-resource'`: a URL (web page, blog post, etc.),
- * * `'text'`: a text (plain text, Markdown, HTML, etc.),
- * * `'selection'`: a selection of text in the editor
- *   (used by {@link module:ai/aiquickactions/aiquickactions~AIQuickActions AI Quick Actions} that pass the user selection
- *   to the {@link module:ai/aichat/aichat~AIChat AI Chat}).
- */
-export type AIContextItemType = 'mcp-tool-context' | 'file' | 'document' | 'web-resource' | 'text' | 'selection';
+* The type of text resource.
+*/
+export type AIContextTextResourceType = "text" | "markdown" | "html";
 /**
- * The type of text resource.
- */
-export type AIContextTextResourceType = 'text' | 'markdown' | 'html';
-/**
- * A context item.
- */
+* A context item.
+*/
 export type AIContextItem = AIContextItemRequestData & {
-    label: string;
-    uiId: string;
-    resourceId?: string;
-    isReadOnly?: boolean;
-    version?: number;
-    hidden?: boolean;
-    sessionId?: string | null;
-    selection?: Array<{
-        start: number;
-        end: number;
-    }>;
+	label: string;
+	uiId: string;
+	resourceId?: string;
+	isReadOnly?: boolean;
+	version?: number;
+	hidden?: boolean;
+	sessionId?: string | null;
+	selection?: Array<{
+		start: number;
+		end: number;
+	}>;
 };
 /**
- * A tool-related context item.
- */
+* A tool-related context item.
+*/
 export type AIToolContextItem = AIContextItem & {
-    type: 'mcp-tool-context';
-    mcpServerName: string;
-    toolName?: string;
-    data: Record<string, any>;
-    /**
-     * ID length can be between 1 and 21 characters. If not provided, it will be randomly generated 21 characters long string.
-     */
-    id?: string;
+	type: "mcp-tool-context";
+	mcpServerName: string;
+	toolName?: string;
+	data: Record<string, any>;
+	/**
+	* ID length can be between 1 and 21 characters. If not provided, it will be randomly generated 21 characters long string.
+	*/
+	id?: string;
 };
 /**
- * A context item request data for using in the `AIConnector`.
- */
+* A context item request data for using in the `AIConnector`.
+*/
 export type AIContextItemRequestData = {
-    type: AIContextItemType;
-    content?: string;
-    id?: string;
-    selection?: Array<{
-        start: number;
-        end: number;
-    }>;
+	type: AIContextItemType;
+	content?: string;
+	id?: string;
+	selection?: Array<{
+		start: number;
+		end: number;
+	}>;
+	editorConfig?: AIEditorConfig;
 };
+/**
+* A single entry in a request `content`/`parts` array: either a resolved context item or a
+* {@link module:ai/aicore/model/aicontextref~AIContextRefRequestData tagged reference} to an admin-managed context.
+*/
+export type AIContextRequestPart = AIContextItemRequestData | AIContextRefRequestData;
 export type AIToolRequestData = {
-    type: 'mcp-tool-context';
-    mcpServerName: string;
-    toolName?: string;
-    data: Record<string, any>;
+	type: "mcp-tool-context";
+	mcpServerName: string;
+	toolName?: string;
+	data: Record<string, any>;
 };
+declare const AIContextBase: ObservableMixinConstructor;
+/**
+* A set of context references attached to an AI request.
+*
+* It is the base context model shared by all AI features: features that do not manage interactive context
+* (Review, Translate, Quick Actions) use it directly, as the result of
+* {@link module:ai/aicore/model/aicontextlibrary~AIContextLibrary#resolveContext}, while
+* {@link module:ai/aichat/model/aichatcontext~AIChatContext} extends it with the chat-specific context state.
+*/
+export declare class AIContext extends AIContextBase {
+	/**
+	* @param refs The context references to hold.
+	*/
+	constructor(refs?: Array<AIContextRef>);
+	/**
+	* The context references, in resolution order. Returns a copy - mutating it does not affect the context.
+	*/
+	get refs(): Array<AIContextRef>;
+	/**
+	* Whether the context holds no references.
+	*/
+	get isEmpty(): boolean;
+	/**
+	* Returns a new context with the given references appended. The original context is left unchanged. Used to fold in
+	* a feature's own reference (for example a review check's `context`).
+	*/
+	cloneWith(...refs: Array<AIContextRef>): AIContext;
+	/**
+	* Returns the request parts to send: the context's references followed by the given message parts. This is where the
+	* leading references applied to every message are merged with a message's own context items.
+	*/
+	toRequestParts(parts?: Array<AIContextRequestPart>): Array<AIContextRequestPart>;
+	/**
+	* Merges the identifiers of this context's references into the given `message.attributes`, so they can be read
+	* back from history to keep the references' pills hidden. Returns the given attributes unchanged when the context
+	* holds no references.
+	*/
+	toMessageAttributes(attributes?: Record<string, unknown>): Record<string, unknown> | undefined;
+	/**
+	* Reads back the default context reference identifiers stored by {@link #toMessageAttributes} from a historical
+	* message's `attributes`.
+	*/
+	static getDefaultContextIds(attributes?: Record<string, unknown>): Set<string>;
+}
+export {};

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

@@ -0,0 +1,71 @@
+/**
+* @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/model/aicontextlibrary
+* @publicApi
+*/
+import { type AIConnector, type AIContextData } from "../aiconnector.js";
+import { type AIContextRef } from "./aicontextref.js";
+import { type AIContext } from "./aicontext.js";
+import { type AIDefaultContext, type AIDefaultContextFeature } from "./aidefaultcontext.js";
+/**
+* Stores the list of contexts available to the current token, acquired from the AI connector.
+*
+* A single instance is shared across all AI features (see {@link module:ai/aicore/aicore~AICore#contextLibrary}),
+* so the context list is fetched once and reused instead of each feature requesting it separately.
+*/
+export declare class AIContextLibrary {
+	/**
+	* @inheritDoc
+	*/
+	constructor({ connector, defaultContext }: {
+		connector: AIConnector;
+		defaultContext?: AIDefaultContext;
+	});
+	/**
+	* Returns the list of all contexts available to the current token.
+	*/
+	getAllContexts(): Promise<Array<AIContextData>>;
+	/**
+	* Returns the list of contexts that features may offer as user-selectable, which corresponds to
+	* {@link #getAllContexts all contexts} narrowed down by the global `ai.defaultContext` configuration.
+	*
+	* Any context referenced by `ai.defaultContext` is treated as config-managed and is **not** offered as a
+	* manually-selectable item. The exclusion is by context ID regardless of the reference granularity or which
+	* features the entry targets: an entry configured only for another feature (for example `features: { review: true }`)
+	* is still excluded from every picker, even where it is not attached automatically. This is deliberate - default
+	* contexts are owned by the configuration, not offered as picker items anywhere. Integrators who want a context
+	* available in a feature's picker simply leave it out of `ai.defaultContext`.
+	*/
+	getAvailableContexts(): Promise<Array<AIContextData>>;
+	/**
+	* Adds the context resolved for a feature invocation to the given context and returns it.
+	*
+	* It resolves the entries of the global `ai.defaultContext` configuration that apply to the given `feature` (narrowed
+	* by `ids` where a feature uses a `RegExp` filter), appends any `extraContexts` the caller supplies (for example a
+	* quick action's or review check's own `context`, or the contexts injected into a chat conversation), and adds the
+	* result to `context`.
+	*
+	* The caller passes its own context model, so a feature can resolve straight into it - for example
+	* {@link module:ai/aichat/model/aichatcontext~AIChatContext} for chat, or a fresh
+	* {@link module:ai/aicore/model/aicontext~AIContext} for review, translate and quick actions.
+	*
+	* @param options Options of the resolution.
+	* @param options.feature The feature the context is resolved for.
+	* @param options.ids The IDs matched against a feature's `RegExp` filter.
+	* @param options.extraContexts References to append after the resolved default context, in order.
+	* @param options.idScopedOnly When set, resolves only the entries that the given `IDs` make applicable.
+	* Used to add the id-specific increment to a context that already carries the
+	* always-applicable default context.
+	* @param options.context The context to add the resolved references to. Returned as-is for chaining.
+	*/
+	resolveContext<T extends AIContext>({ feature, ids, extraContexts, idScopedOnly, context }: {
+		feature: AIDefaultContextFeature;
+		ids?: Array<string>;
+		extraContexts?: Array<AIContextRef>;
+		idScopedOnly?: boolean;
+		context: T;
+	}): T;
+}

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

@@ -0,0 +1,37 @@
+/**
+* @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/model/aicontextref
+* @publicApi
+*/
+/**
+* A reference to a context or to a single item within a context.
+*
+* * `{ id }` — attaches all prompts and files from the context.
+* * `{ id, fileId }` — attaches a single file from the context.
+* * `{ id, promptId }` — attaches a single prompt from the context.
+*/
+export type AIContextRef = {
+	id: string;
+} | {
+	id: string;
+	fileId: string;
+} | {
+	id: string;
+	promptId: string;
+};
+/**
+* The request shape of a {@link module:ai/aicore/model/aicontextref~AIContextRef context reference}.
+*
+* The AI service expects a `type` discriminator, as a reference can share a request array with entries of other
+* types. It is added by {@link module:ai/aicore/model/aicontext~AIContext} when the request payload is built, so it is
+* not part of the reference shape the integrator provides.
+*
+* @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.
+*/
+export type AIContextRefRequestData = AIContextRef & {
+	type: "context";
+};

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

@@ -0,0 +1,83 @@
+/**
+* @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/model/aidefaultcontext
+* @publicApi
+*/
+import { type AIContextRef } from "./aicontextref.js";
+/**
+* Identifiers of the AI features that a {@link module:ai/aicore/model/aidefaultcontext~AIDefaultContextEntry
+* default context entry} can target.
+*/
+export type AIDefaultContextFeature = "chat" | "quickActions" | "review" | "translate";
+/**
+* Narrows down which invocations of the AI features a
+* {@link module:ai/aicore/model/aidefaultcontext~AIDefaultContextEntry default context entry} applies to.
+*
+* Each key targets one AI feature. When a key is omitted, the entry is **not** applied to that feature. A value
+* of `true` applies the entry to every invocation of the feature, while a `RegExp` applies it only when one of
+* the invocation IDs matches:
+*
+* * `chat` - the ID of the {@link module:ai/aichatshortcuts/aichatshortcuts~AIChatShortcutChatDefinition chat shortcut}
+*   used to start a conversation. A matching `RegExp` attaches the entry to that conversation, so it applies to the
+*   shortcut's message **and** to the conversation's later messages. A conversation not started by a matching shortcut
+*   (for example one started with a free-form message) receives the entry only when the value is `true`.
+* * `quickActions` - the ID of the quick action or of its group,
+* * `review` - the ID of the review command,
+* * `translate` - the ID of the target language.
+*
+* ```ts
+* // Attach to all review commands, but only to the translate quick actions.
+* {
+* 	review: true,
+* 	quickActions: /^translate/
+* }
+* ```
+*/
+export interface AIDefaultContextFeatures {
+	/**
+	* Whether the entry is attached to the AI Chat messages. Provide a `RegExp` to attach it when a conversation is
+	* started with an {@link module:ai/aichatshortcuts/aichatshortcuts~AIChatShortcutChatDefinition AI Chat shortcut}
+	* whose ID matches: the entry is folded into that conversation, so it applies to the shortcut's message and to its
+	* later messages as well. A conversation not started by a matching shortcut receives the entry only when the value
+	* is `true`.
+	*/
+	chat?: boolean | RegExp;
+	/**
+	* Whether the entry is attached to AI Quick Action requests. Provide a `RegExp` to attach it only to actions
+	* whose ID, or the ID of their group, matches.
+	*/
+	quickActions?: boolean | RegExp;
+	/**
+	* Whether the entry is attached to AI Review requests. Provide a `RegExp` to attach it only to review commands
+	* whose ID matches.
+	*/
+	review?: boolean | RegExp;
+	/**
+	* Whether the entry is attached to AI Translate requests. Provide a `RegExp` to attach it only to translations
+	* whose target language ID matches.
+	*/
+	translate?: boolean | RegExp;
+}
+/**
+* A single entry of the {@link module:ai/aiconfig~AIConfig#defaultContext global default context}.
+*
+* It is a {@link module:ai/aicore/model/aicontextref~AIContextRef context reference} optionally narrowed down to
+* specific features via `features`. When `features` is omitted, the entry is attached to **every** AI feature.
+*/
+export type AIDefaultContextEntry = AIContextRef & {
+	/**
+	* The features the entry is attached to. When omitted, the entry is attached to every AI feature.
+	*/
+	features?: AIDefaultContextFeatures;
+};
+/**
+* The shape accepted by {@link module:ai/aiconfig~AIConfig#defaultContext}.
+*
+* A list of {@link module:ai/aicore/model/aidefaultcontext~AIDefaultContextEntry context references} attached
+* automatically to AI feature invocations triggered through the editor UI. Each entry can target all features or a
+* subset of them. The headless gateway APIs are config-independent and do not apply it.
+*/
+export type AIDefaultContext = Array<AIDefaultContextEntry>;

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

@@ -0,0 +1,26 @@
+/**
+* @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/model/aieditorroot
+* @publicApi
+*/
+/**
+* Uniquely identifies a single root within an editor instance.
+*
+* `channelId` selects the editor (matches the `collaboration.channelId` config of the editor instance).
+* `rootName` selects the root within that editor.
+*
+* Use this type whenever an API needs to target a specific root in a multi-root or multi-editor setup.
+*/
+export type AIEditorRoot = {
+	/**
+	* The channel ID of the editor that owns the root. Matches the `collaboration.channelId` config of that editor.
+	*/
+	channelId: string;
+	/**
+	* The name of the root within the editor.
+	*/
+	rootName: string;
+};