@gravity-ui/aikit 2.3.0 → 2.4.0

package/build/cjs/components/organisms/AssistantMessage/defaultMessageTypeRegistry.js

@@ -10,12 +10,18 @@ function createDefaultMessageRegistry(transformOptions, shouldParseIncompleteMar
     const registry = (0, messageTypeRegistry_1.createMessageRendererRegistry)();
     (0, messageTypeRegistry_1.registerMessageRenderer)(registry, 'text', {
         component: ({ part }) => ((0, jsx_runtime_1.jsx)(MarkdownRenderer_1.MarkdownRenderer, { content: part.data.text, transformOptions: transformOptions, shouldParseIncompleteMarkdown: shouldParseIncompleteMarkdown })),
+    }, {
+        isDefault: true,
     });
     (0, messageTypeRegistry_1.registerMessageRenderer)(registry, 'tool', {
         component: ({ part }) => (0, jsx_runtime_1.jsx)(ToolMessage_1.ToolMessage, Object.assign({}, part.data)),
+    }, {
+        isDefault: true,
     });
     (0, messageTypeRegistry_1.registerMessageRenderer)(registry, 'thinking', {
         component: ({ part }) => (0, jsx_runtime_1.jsx)(ThinkingMessage_1.ThinkingMessage, Object.assign({}, part.data)),
+    }, {
+        isDefault: true,
     });
     return registry;
 }

package/build/cjs/components/organisms/AssistantMessage/defaultMessageTypeRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaultMessageTypeRegistry.js","sourceRoot":"../../../../../src","sources":["components/organisms/AssistantMessage/defaultMessageTypeRegistry.tsx"],"names":[],"mappings":";;AAgBA,oEAyBC;;AAlCD,+EAI4C;AAC5C,4EAA8D;AAC9D,iEAAmD;AACnD,yDAA2C;AAE3C,SAAgB,4BAA4B,CACxC,gBAA8B,EAC9B,6BAAuC;IAEvC,MAAM,QAAQ,GAAG,IAAA,mDAA6B,GAAE,CAAC;IAEjD,IAAA,6CAAuB,EAAqB,QAAQ,EAAE,MAAM,EAAE;QAC1D,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,CACnB,uBAAC,mCAAgB,IACb,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EACvB,gBAAgB,EAAE,gBAAgB,EAClC,6BAA6B,EAAE,6BAA6B,GAC9D,CACL;KACJ,CAAC,CAAC;IAEH,IAAA,6CAAuB,EAAqB,QAAQ,EAAE,MAAM,EAAE;QAC1D,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,uBAAC,yBAAW,oBAAK,IAAI,CAAC,IAAI,EAAI;KACxD,CAAC,CAAC;IAEH,IAAA,6CAAuB,EAAyB,QAAQ,EAAE,UAAU,EAAE;QAClE,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,uBAAC,iCAAe,oBAAK,IAAI,CAAC,IAAI,EAAI;KAC5D,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AACpB,CAAC","sourcesContent":["import type {OptionsType} from '@diplodoc/transform/lib/typings';\n\nimport type {\n    TextMessageContent,\n    ThinkingMessageContent,\n    ToolMessageContent,\n} from '../../../types/messages';\nimport {\n    type MessageRendererRegistry,\n    createMessageRendererRegistry,\n    registerMessageRenderer,\n} from '../../../utils/messageTypeRegistry';\nimport {MarkdownRenderer} from '../../atoms/MarkdownRenderer';\nimport {ThinkingMessage} from '../ThinkingMessage';\nimport {ToolMessage} from '../ToolMessage';\n\nexport function createDefaultMessageRegistry(\n    transformOptions?: OptionsType,\n    shouldParseIncompleteMarkdown?: boolean,\n): MessageRendererRegistry {\n    const registry = createMessageRendererRegistry();\n\n    registerMessageRenderer<TextMessageContent>(registry, 'text', {\n        component: ({part}) => (\n            <MarkdownRenderer\n                content={part.data.text}\n                transformOptions={transformOptions}\n                shouldParseIncompleteMarkdown={shouldParseIncompleteMarkdown}\n            />\n        ),\n    });\n\n    registerMessageRenderer<ToolMessageContent>(registry, 'tool', {\n        component: ({part}) => <ToolMessage {...part.data} />,\n    });\n\n    registerMessageRenderer<ThinkingMessageContent>(registry, 'thinking', {\n        component: ({part}) => <ThinkingMessage {...part.data} />,\n    });\n\n    return registry;\n}\n"]}
+{"version":3,"file":"defaultMessageTypeRegistry.js","sourceRoot":"../../../../../src","sources":["components/organisms/AssistantMessage/defaultMessageTypeRegistry.tsx"],"names":[],"mappings":";;AAgBA,oEA8CC;;AAvDD,+EAI4C;AAC5C,4EAA8D;AAC9D,iEAAmD;AACnD,yDAA2C;AAE3C,SAAgB,4BAA4B,CACxC,gBAA8B,EAC9B,6BAAuC;IAEvC,MAAM,QAAQ,GAAG,IAAA,mDAA6B,GAAE,CAAC;IAEjD,IAAA,6CAAuB,EACnB,QAAQ,EACR,MAAM,EACN;QACI,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,CACnB,uBAAC,mCAAgB,IACb,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EACvB,gBAAgB,EAAE,gBAAgB,EAClC,6BAA6B,EAAE,6BAA6B,GAC9D,CACL;KACJ,EACD;QACI,SAAS,EAAE,IAAI;KAClB,CACJ,CAAC;IAEF,IAAA,6CAAuB,EACnB,QAAQ,EACR,MAAM,EACN;QACI,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,uBAAC,yBAAW,oBAAK,IAAI,CAAC,IAAI,EAAI;KACxD,EACD;QACI,SAAS,EAAE,IAAI;KAClB,CACJ,CAAC;IAEF,IAAA,6CAAuB,EACnB,QAAQ,EACR,UAAU,EACV;QACI,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE,CAAC,uBAAC,iCAAe,oBAAK,IAAI,CAAC,IAAI,EAAI;KAC5D,EACD;QACI,SAAS,EAAE,IAAI;KAClB,CACJ,CAAC;IAEF,OAAO,QAAQ,CAAC;AACpB,CAAC","sourcesContent":["import type {OptionsType} from '@diplodoc/transform/lib/typings';\n\nimport type {\n    TextMessageContent,\n    ThinkingMessageContent,\n    ToolMessageContent,\n} from '../../../types/messages';\nimport {\n    type MessageRendererRegistry,\n    createMessageRendererRegistry,\n    registerMessageRenderer,\n} from '../../../utils/messageTypeRegistry';\nimport {MarkdownRenderer} from '../../atoms/MarkdownRenderer';\nimport {ThinkingMessage} from '../ThinkingMessage';\nimport {ToolMessage} from '../ToolMessage';\n\nexport function createDefaultMessageRegistry(\n    transformOptions?: OptionsType,\n    shouldParseIncompleteMarkdown?: boolean,\n): MessageRendererRegistry {\n    const registry = createMessageRendererRegistry();\n\n    registerMessageRenderer<TextMessageContent>(\n        registry,\n        'text',\n        {\n            component: ({part}) => (\n                <MarkdownRenderer\n                    content={part.data.text}\n                    transformOptions={transformOptions}\n                    shouldParseIncompleteMarkdown={shouldParseIncompleteMarkdown}\n                />\n            ),\n        },\n        {\n            isDefault: true,\n        },\n    );\n\n    registerMessageRenderer<ToolMessageContent>(\n        registry,\n        'tool',\n        {\n            component: ({part}) => <ToolMessage {...part.data} />,\n        },\n        {\n            isDefault: true,\n        },\n    );\n\n    registerMessageRenderer<ThinkingMessageContent>(\n        registry,\n        'thinking',\n        {\n            component: ({part}) => <ThinkingMessage {...part.data} />,\n        },\n        {\n            isDefault: true,\n        },\n    );\n\n    return registry;\n}\n"]}

package/build/cjs/hooks/index.d.ts

@@ -5,3 +5,5 @@ export * from "./useScrollPreservation.js";
 export * from "./useAutoCollapseOnSuccess.js";
 export * from "./useAutoCollapseOnCancelled.js";
 export * from "./useFileUploadStore.js";
+export * from "./useToolset.js";
+export * from "./useToolResultContinuation.js";

package/build/cjs/hooks/index.js

@@ -8,4 +8,6 @@ tslib_1.__exportStar(require("./useScrollPreservation.js"), exports);
 tslib_1.__exportStar(require("./useAutoCollapseOnSuccess.js"), exports);
 tslib_1.__exportStar(require("./useAutoCollapseOnCancelled.js"), exports);
 tslib_1.__exportStar(require("./useFileUploadStore.js"), exports);
+tslib_1.__exportStar(require("./useToolset.js"), exports);
+tslib_1.__exportStar(require("./useToolResultContinuation.js"), exports);
 //# sourceMappingURL=index.js.map

package/build/cjs/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["hooks/index.ts"],"names":[],"mappings":";;;AAAA,sEAAmC;AACnC,8DAAiC;AACjC,8DAAiC;AACjC,qEAAwC;AACxC,wEAA2C;AAC3C,0EAA6C;AAC7C,kEAAqC","sourcesContent":["export * from './useDateFormatter';\nexport * from './useToolMessage';\nexport * from './useSmartScroll';\nexport * from './useScrollPreservation';\nexport * from './useAutoCollapseOnSuccess';\nexport * from './useAutoCollapseOnCancelled';\nexport * from './useFileUploadStore';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["hooks/index.ts"],"names":[],"mappings":";;;AAAA,sEAAmC;AACnC,8DAAiC;AACjC,8DAAiC;AACjC,qEAAwC;AACxC,wEAA2C;AAC3C,0EAA6C;AAC7C,kEAAqC;AACrC,0DAA6B;AAC7B,yEAA4C","sourcesContent":["export * from './useDateFormatter';\nexport * from './useToolMessage';\nexport * from './useSmartScroll';\nexport * from './useScrollPreservation';\nexport * from './useAutoCollapseOnSuccess';\nexport * from './useAutoCollapseOnCancelled';\nexport * from './useFileUploadStore';\nexport * from './useToolset';\nexport * from './useToolResultContinuation';\n"]}

package/build/cjs/hooks/useToolResultContinuation.d.ts

@@ -0,0 +1,31 @@
+import type { TChatMessage, TMessageContent } from "../types/messages.js";
+import { type ToolExecutionStatus } from "../utils/toolset/index.js";
+export type ToolSettledEvent<TCustom extends TMessageContent = never> = {
+    toolCallId: string;
+    toolName: string;
+    status: ToolExecutionStatus;
+    messages: TChatMessage<TCustom>[];
+};
+export type UseToolResultContinuationOptions<TCustom extends TMessageContent = never> = {
+    messages: TChatMessage<TCustom>[];
+    /**
+     * Called once per tool that transitioned from a pending status
+     * (`waitingConfirmation`, `waitingSubmission`, `loading`) to a terminal
+     * one (`success`, `error`, `cancelled`). Typical use: forward the
+     * updated transcript to the model.
+     */
+    onSettled: (event: ToolSettledEvent<TCustom>) => void;
+};
+/**
+ * Pure: returns events for every tool whose status was pending in `prev`
+ * and is terminal in `next`. Tools that are already terminal in `prev`
+ * (replay/restore) do not produce events.
+ */
+export declare function findNewlySettledTools<TCustom extends TMessageContent = never>(prev: TChatMessage<TCustom>[], next: TChatMessage<TCustom>[]): ToolSettledEvent<TCustom>[];
+/**
+ * Observe `messages` and fire `onSettled` once whenever a tool part
+ * transitions from pending to terminal. Tools already terminal on the
+ * first observed snapshot do not fire — replay/restore is intentionally
+ * silent. Pair with `useToolset` to forward results to the model.
+ */
+export declare function useToolResultContinuation<TCustom extends TMessageContent = never>(options: UseToolResultContinuationOptions<TCustom>): void;

package/build/cjs/hooks/useToolResultContinuation.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findNewlySettledTools = findNewlySettledTools;
+exports.useToolResultContinuation = useToolResultContinuation;
+const react_1 = require("react");
+const PENDING_STATUSES = new Set([
+    'waitingConfirmation',
+    'waitingSubmission',
+    'loading',
+]);
+const TERMINAL_STATUSES = new Set([
+    'success',
+    'error',
+    'cancelled',
+]);
+function isPending(status) {
+    return status !== undefined && PENDING_STATUSES.has(status);
+}
+function isTerminal(status) {
+    return status !== undefined && TERMINAL_STATUSES.has(status);
+}
+function isToolPartContent(part) {
+    return (part.type === 'tool' &&
+        typeof part.data === 'object' &&
+        part.data !== null &&
+        'toolCallId' in part.data);
+}
+function toContentParts(content) {
+    if (typeof content === 'string')
+        return [];
+    return Array.isArray(content) ? content : [content];
+}
+function collectToolPartsByCallId(messages) {
+    const map = new Map();
+    for (const msg of messages) {
+        if (msg.role !== 'assistant')
+            continue;
+        for (const part of toContentParts(msg.content)) {
+            if (!part || typeof part !== 'object')
+                continue;
+            if (!isToolPartContent(part))
+                continue;
+            map.set(part.data.toolCallId, part.data);
+        }
+    }
+    return map;
+}
+/**
+ * Pure: returns events for every tool whose status was pending in `prev`
+ * and is terminal in `next`. Tools that are already terminal in `prev`
+ * (replay/restore) do not produce events.
+ */
+function findNewlySettledTools(prev, next) {
+    var _a;
+    const prevParts = collectToolPartsByCallId(prev);
+    const events = [];
+    for (const [toolCallId, data] of collectToolPartsByCallId(next)) {
+        const prevStatus = (_a = prevParts.get(toolCallId)) === null || _a === void 0 ? void 0 : _a.status;
+        if (isPending(prevStatus) && isTerminal(data.status)) {
+            events.push({
+                toolCallId,
+                toolName: data.toolName,
+                status: data.status,
+                messages: next,
+            });
+        }
+    }
+    return events;
+}
+/**
+ * Observe `messages` and fire `onSettled` once whenever a tool part
+ * transitions from pending to terminal. Tools already terminal on the
+ * first observed snapshot do not fire — replay/restore is intentionally
+ * silent. Pair with `useToolset` to forward results to the model.
+ */
+function useToolResultContinuation(options) {
+    const { messages, onSettled } = options;
+    const onSettledRef = (0, react_1.useRef)(onSettled);
+    (0, react_1.useEffect)(() => {
+        onSettledRef.current = onSettled;
+    });
+    const prevMessagesRef = (0, react_1.useRef)(messages);
+    (0, react_1.useEffect)(() => {
+        const events = findNewlySettledTools(prevMessagesRef.current, messages);
+        prevMessagesRef.current = messages;
+        for (const event of events) {
+            onSettledRef.current(event);
+        }
+    }, [messages]);
+}
+//# sourceMappingURL=useToolResultContinuation.js.map

package/build/cjs/hooks/useToolResultContinuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolResultContinuation.js","sourceRoot":"../../../src","sources":["hooks/useToolResultContinuation.ts"],"names":[],"mappings":"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","sourcesContent":["import {useEffect, useRef} from 'react';\n\nimport type {TChatMessage, TMessageContent} from '../types/messages';\nimport type {TToolStatus} from '../types/tool';\nimport {\n    type ToolExecutionStatus,\n    type ToolPartContent,\n    type ToolPartContentData,\n} from '../utils/toolset';\n\nexport type ToolSettledEvent<TCustom extends TMessageContent = never> = {\n    toolCallId: string;\n    toolName: string;\n    status: ToolExecutionStatus;\n    messages: TChatMessage<TCustom>[];\n};\n\nexport type UseToolResultContinuationOptions<TCustom extends TMessageContent = never> = {\n    messages: TChatMessage<TCustom>[];\n    /**\n     * Called once per tool that transitioned from a pending status\n     * (`waitingConfirmation`, `waitingSubmission`, `loading`) to a terminal\n     * one (`success`, `error`, `cancelled`). Typical use: forward the\n     * updated transcript to the model.\n     */\n    onSettled: (event: ToolSettledEvent<TCustom>) => void;\n};\n\nconst PENDING_STATUSES: ReadonlySet<TToolStatus> = new Set<TToolStatus>([\n    'waitingConfirmation',\n    'waitingSubmission',\n    'loading',\n]);\n\nconst TERMINAL_STATUSES: ReadonlySet<TToolStatus> = new Set<TToolStatus>([\n    'success',\n    'error',\n    'cancelled',\n]);\n\nfunction isPending(status: TToolStatus | undefined): boolean {\n    return status !== undefined && PENDING_STATUSES.has(status);\n}\n\nfunction isTerminal(status: TToolStatus | undefined): status is ToolExecutionStatus {\n    return status !== undefined && TERMINAL_STATUSES.has(status);\n}\n\nfunction isToolPartContent(part: TMessageContent): part is ToolPartContent {\n    return (\n        part.type === 'tool' &&\n        typeof part.data === 'object' &&\n        part.data !== null &&\n        'toolCallId' in part.data\n    );\n}\n\nfunction toContentParts<TCustom extends TMessageContent>(\n    content: TChatMessage<TCustom>['content'],\n): TMessageContent[] {\n    if (typeof content === 'string') return [];\n    return Array.isArray(content) ? content : [content];\n}\n\nfunction collectToolPartsByCallId<TCustom extends TMessageContent>(\n    messages: TChatMessage<TCustom>[],\n): Map<string, ToolPartContentData> {\n    const map = new Map<string, ToolPartContentData>();\n    for (const msg of messages) {\n        if (msg.role !== 'assistant') continue;\n        for (const part of toContentParts(msg.content)) {\n            if (!part || typeof part !== 'object') continue;\n            if (!isToolPartContent(part)) continue;\n            map.set(part.data.toolCallId, part.data);\n        }\n    }\n    return map;\n}\n\n/**\n * Pure: returns events for every tool whose status was pending in `prev`\n * and is terminal in `next`. Tools that are already terminal in `prev`\n * (replay/restore) do not produce events.\n */\nexport function findNewlySettledTools<TCustom extends TMessageContent = never>(\n    prev: TChatMessage<TCustom>[],\n    next: TChatMessage<TCustom>[],\n): ToolSettledEvent<TCustom>[] {\n    const prevParts = collectToolPartsByCallId(prev);\n    const events: ToolSettledEvent<TCustom>[] = [];\n    for (const [toolCallId, data] of collectToolPartsByCallId(next)) {\n        const prevStatus = prevParts.get(toolCallId)?.status;\n        if (isPending(prevStatus) && isTerminal(data.status)) {\n            events.push({\n                toolCallId,\n                toolName: data.toolName,\n                status: data.status,\n                messages: next,\n            });\n        }\n    }\n    return events;\n}\n\n/**\n * Observe `messages` and fire `onSettled` once whenever a tool part\n * transitions from pending to terminal. Tools already terminal on the\n * first observed snapshot do not fire — replay/restore is intentionally\n * silent. Pair with `useToolset` to forward results to the model.\n */\nexport function useToolResultContinuation<TCustom extends TMessageContent = never>(\n    options: UseToolResultContinuationOptions<TCustom>,\n): void {\n    const {messages, onSettled} = options;\n\n    const onSettledRef = useRef(onSettled);\n    useEffect(() => {\n        onSettledRef.current = onSettled;\n    });\n\n    const prevMessagesRef = useRef(messages);\n\n    useEffect(() => {\n        const events = findNewlySettledTools(prevMessagesRef.current, messages);\n        prevMessagesRef.current = messages;\n        for (const event of events) {\n            onSettledRef.current(event);\n        }\n    }, [messages]);\n}\n"]}

package/build/cjs/hooks/useToolset.d.ts

@@ -0,0 +1,24 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { TChatMessage, TMessageContent } from "../types/messages.js";
+import type { MessageRendererRegistry } from "../utils/messageTypeRegistry.js";
+import { type Toolset, type ToolsetResultEvent } from "../utils/toolset/index.js";
+export type UseToolsetOptions<TCustom extends TMessageContent = never> = {
+    toolset: Toolset;
+    setMessages: Dispatch<SetStateAction<TChatMessage<TCustom>[]>>;
+    /** Existing registry to extend instead of starting from a fresh one. */
+    registry?: MessageRendererRegistry;
+};
+export type UseToolsetReturn = {
+    messageRendererRegistry: MessageRendererRegistry;
+    handleToolResult: (event: ToolsetResultEvent) => void;
+};
+/**
+ * Wire a toolset into the chat: returns a `MessageRendererRegistry` that
+ * renders tool parts via the toolset and a `handleToolResult` callback
+ * that merges results into history. To react to tool completion (e.g.
+ * forward to the model), pair with `useToolResultContinuation`.
+ *
+ * Pass the same `toolset` reference across renders (e.g. via `useMemo` or
+ * `createToolset`) so the registry stays stable.
+ */
+export declare function useToolset<TCustom extends TMessageContent = never>(options: UseToolsetOptions<TCustom>): UseToolsetReturn;

package/build/cjs/hooks/useToolset.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useToolset = useToolset;
+const react_1 = require("react");
+const toolset_1 = require("../utils/toolset/index.js");
+/**
+ * Wire a toolset into the chat: returns a `MessageRendererRegistry` that
+ * renders tool parts via the toolset and a `handleToolResult` callback
+ * that merges results into history. To react to tool completion (e.g.
+ * forward to the model), pair with `useToolResultContinuation`.
+ *
+ * Pass the same `toolset` reference across renders (e.g. via `useMemo` or
+ * `createToolset`) so the registry stays stable.
+ */
+function useToolset(options) {
+    const { toolset, setMessages, registry } = options;
+    const handleToolResult = (0, react_1.useCallback)((event) => {
+        setMessages((prev) => (0, toolset_1.applyToolResult)(prev, event));
+    }, [setMessages]);
+    const messageRendererRegistry = (0, react_1.useMemo)(() => (0, toolset_1.createToolsetRenderer)(toolset, {
+        onToolResult: handleToolResult,
+        registry,
+    }), [toolset, handleToolResult, registry]);
+    return { messageRendererRegistry, handleToolResult };
+}
+//# sourceMappingURL=useToolset.js.map

package/build/cjs/hooks/useToolset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolset.js","sourceRoot":"../../../src","sources":["hooks/useToolset.ts"],"names":[],"mappings":";;AAiCA,gCAsBC;AAvDD,iCAA2C;AAK3C,uDAK0B;AAc1B;;;;;;;;GAQG;AACH,SAAgB,UAAU,CACtB,OAAmC;IAEnC,MAAM,EAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAC,GAAG,OAAO,CAAC;IAEjD,MAAM,gBAAgB,GAAG,IAAA,mBAAW,EAChC,CAAC,KAAyB,EAAE,EAAE;QAC1B,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,yBAAe,EAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC,EACD,CAAC,WAAW,CAAC,CAChB,CAAC;IAEF,MAAM,uBAAuB,GAAG,IAAA,eAAO,EACnC,GAAG,EAAE,CACD,IAAA,+BAAqB,EAAC,OAAO,EAAE;QAC3B,YAAY,EAAE,gBAAgB;QAC9B,QAAQ;KACX,CAAC,EACN,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CACxC,CAAC;IAEF,OAAO,EAAC,uBAAuB,EAAE,gBAAgB,EAAC,CAAC;AACvD,CAAC","sourcesContent":["import {useCallback, useMemo} from 'react';\nimport type {Dispatch, SetStateAction} from 'react';\n\nimport type {TChatMessage, TMessageContent} from '../types/messages';\nimport type {MessageRendererRegistry} from '../utils/messageTypeRegistry';\nimport {\n    type Toolset,\n    type ToolsetResultEvent,\n    applyToolResult,\n    createToolsetRenderer,\n} from '../utils/toolset';\n\nexport type UseToolsetOptions<TCustom extends TMessageContent = never> = {\n    toolset: Toolset;\n    setMessages: Dispatch<SetStateAction<TChatMessage<TCustom>[]>>;\n    /** Existing registry to extend instead of starting from a fresh one. */\n    registry?: MessageRendererRegistry;\n};\n\nexport type UseToolsetReturn = {\n    messageRendererRegistry: MessageRendererRegistry;\n    handleToolResult: (event: ToolsetResultEvent) => void;\n};\n\n/**\n * Wire a toolset into the chat: returns a `MessageRendererRegistry` that\n * renders tool parts via the toolset and a `handleToolResult` callback\n * that merges results into history. To react to tool completion (e.g.\n * forward to the model), pair with `useToolResultContinuation`.\n *\n * Pass the same `toolset` reference across renders (e.g. via `useMemo` or\n * `createToolset`) so the registry stays stable.\n */\nexport function useToolset<TCustom extends TMessageContent = never>(\n    options: UseToolsetOptions<TCustom>,\n): UseToolsetReturn {\n    const {toolset, setMessages, registry} = options;\n\n    const handleToolResult = useCallback(\n        (event: ToolsetResultEvent) => {\n            setMessages((prev) => applyToolResult(prev, event));\n        },\n        [setMessages],\n    );\n\n    const messageRendererRegistry = useMemo(\n        () =>\n            createToolsetRenderer(toolset, {\n                onToolResult: handleToolResult,\n                registry,\n            }),\n        [toolset, handleToolResult, registry],\n    );\n\n    return {messageRendererRegistry, handleToolResult};\n}\n"]}

package/build/cjs/package.json

@@ -1 +1 @@
-{"version":"2.3.0","type":"commonjs","sideEffects":["*.css","*.scss"]}
+{"version":"2.4.0","type":"commonjs","sideEffects":["*.css","*.scss"]}

package/build/cjs/utils/index.d.ts

@@ -3,3 +3,4 @@ export * from "./messageUtils.js";
 export * from "./validation.js";
 export * from "./messageTypeRegistry.js";
 export * from "./clipboardUtils.js";
+export * from "./toolset/index.js";

package/build/cjs/utils/index.js

@@ -7,4 +7,5 @@ tslib_1.__exportStar(require("./messageUtils.js"), exports);
 tslib_1.__exportStar(require("./validation.js"), exports);
 tslib_1.__exportStar(require("./messageTypeRegistry.js"), exports);
 tslib_1.__exportStar(require("./clipboardUtils.js"), exports);
+tslib_1.__exportStar(require("./toolset/index.js"), exports);
 //# sourceMappingURL=index.js.map

package/build/cjs/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":";;;AAAA,mBAAmB;AACnB,yDAA4B;AAC5B,4DAA+B;AAC/B,0DAA6B;AAC7B,mEAAsC;AACtC,8DAAiC","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":";;;AAAA,mBAAmB;AACnB,yDAA4B;AAC5B,4DAA+B;AAC/B,0DAA6B;AAC7B,mEAAsC;AACtC,8DAAiC;AACjC,6DAA0B","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\nexport * from './toolset';\n"]}

package/build/cjs/utils/messageTypeRegistry.d.ts

@@ -8,6 +8,13 @@ export type MessageRenderer<TContent extends TMessageContent = TMessageContent>
 };
 export type MessageRendererRegistry = Record<string, MessageRenderer>;
 export declare function createMessageRendererRegistry(): MessageRendererRegistry;
-export declare function registerMessageRenderer<TContent extends TMessageContent>(registry: MessageRendererRegistry, contentType: TContent['type'], renderer: MessageRenderer<TContent>): MessageRendererRegistry;
+export type RegisterMessageRendererOptions = {
+    /**
+     * Marks a renderer as built-in. Replacing built-in renderers is expected
+     * when consumers customize the default registry, so it does not warn.
+     */
+    isDefault?: boolean;
+};
+export declare function registerMessageRenderer<TContent extends TMessageContent>(registry: MessageRendererRegistry, contentType: TContent['type'], renderer: MessageRenderer<TContent>, options?: RegisterMessageRendererOptions): MessageRendererRegistry;
 export declare function getMessageRenderer(registry: MessageRendererRegistry, contentType: string): React.ComponentType<MessageContentComponentProps> | undefined;
 export declare function mergeMessageRendererRegistries(defaultRegistry: MessageRendererRegistry, customRegistry: MessageRendererRegistry): MessageRendererRegistry;

package/build/cjs/utils/messageTypeRegistry.js

@@ -4,12 +4,24 @@ exports.createMessageRendererRegistry = createMessageRendererRegistry;
 exports.registerMessageRenderer = registerMessageRenderer;
 exports.getMessageRenderer = getMessageRenderer;
 exports.mergeMessageRendererRegistries = mergeMessageRendererRegistries;
+const defaultRenderers = new WeakSet();
 function createMessageRendererRegistry() {
     return {};
 }
-function registerMessageRenderer(registry, contentType, renderer) {
+function registerMessageRenderer(registry, contentType, renderer, options) {
+    const existingRenderer = registry[contentType];
+    if (process.env.NODE_ENV !== 'production' &&
+        existingRenderer &&
+        !defaultRenderers.has(existingRenderer)) {
+        // eslint-disable-next-line no-console
+        console.warn(`registerMessageRenderer: overwriting existing renderer for content type "${contentType}"`);
+    }
+    const registeredRenderer = renderer;
+    if (options === null || options === void 0 ? void 0 : options.isDefault) {
+        defaultRenderers.add(registeredRenderer);
+    }
     Object.assign(registry, {
-        [contentType]: renderer,
+        [contentType]: registeredRenderer,
     });
     return registry;
 }

package/build/cjs/utils/messageTypeRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"messageTypeRegistry.js","sourceRoot":"../../../src","sources":["utils/messageTypeRegistry.ts"],"names":[],"mappings":";;AAcA,sEAEC;AAED,0DASC;AAED,gDAKC;AAED,wEAQC;AA9BD,SAAgB,6BAA6B;IACzC,OAAO,EAAE,CAAC;AACd,CAAC;AAED,SAAgB,uBAAuB,CACnC,QAAiC,EACjC,WAA6B,EAC7B,QAAmC;IAEnC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE;QACpB,CAAC,WAAW,CAAC,EAAE,QAAsC;KACxD,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,SAAgB,kBAAkB,CAC9B,QAAiC,EACjC,WAAmB;;IAEnB,OAAO,MAAA,QAAQ,CAAC,WAAW,CAAC,0CAAE,SAAS,CAAC;AAC5C,CAAC;AAED,SAAgB,8BAA8B,CAC1C,eAAwC,EACxC,cAAuC;IAEvC,uCACO,eAAe,GACf,cAAc,EACnB;AACN,CAAC","sourcesContent":["import type React from 'react';\n\nimport type {TMessageContent} from '../types/messages';\n\nexport type MessageContentComponentProps<TContent extends TMessageContent = TMessageContent> = {\n    part: TContent;\n};\n\nexport type MessageRenderer<TContent extends TMessageContent = TMessageContent> = {\n    component: React.ComponentType<MessageContentComponentProps<TContent>>;\n};\n\nexport type MessageRendererRegistry = Record<string, MessageRenderer>;\n\nexport function createMessageRendererRegistry(): MessageRendererRegistry {\n    return {};\n}\n\nexport function registerMessageRenderer<TContent extends TMessageContent>(\n    registry: MessageRendererRegistry,\n    contentType: TContent['type'],\n    renderer: MessageRenderer<TContent>,\n): MessageRendererRegistry {\n    Object.assign(registry, {\n        [contentType]: renderer as unknown as MessageRenderer,\n    });\n    return registry;\n}\n\nexport function getMessageRenderer(\n    registry: MessageRendererRegistry,\n    contentType: string,\n): React.ComponentType<MessageContentComponentProps> | undefined {\n    return registry[contentType]?.component;\n}\n\nexport function mergeMessageRendererRegistries(\n    defaultRegistry: MessageRendererRegistry,\n    customRegistry: MessageRendererRegistry,\n): MessageRendererRegistry {\n    return {\n        ...defaultRegistry,\n        ...customRegistry,\n    };\n}\n"]}
+{"version":3,"file":"messageTypeRegistry.js","sourceRoot":"../../../src","sources":["utils/messageTypeRegistry.ts"],"names":[],"mappings":";;AAgBA,sEAEC;AAUD,0DAyBC;AAED,gDAKC;AAED,wEAQC;AAxDD,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAmB,CAAC;AAExD,SAAgB,6BAA6B;IACzC,OAAO,EAAE,CAAC;AACd,CAAC;AAUD,SAAgB,uBAAuB,CACnC,QAAiC,EACjC,WAA6B,EAC7B,QAAmC,EACnC,OAAwC;IAExC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/C,IACI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QACrC,gBAAgB;QAChB,CAAC,gBAAgB,CAAC,GAAG,CAAC,gBAAgB,CAAC,EACzC,CAAC;QACC,sCAAsC;QACtC,OAAO,CAAC,IAAI,CACR,4EAA4E,WAAW,GAAG,CAC7F,CAAC;IACN,CAAC;IACD,MAAM,kBAAkB,GAAG,QAAsC,CAAC;IAClE,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,EAAE,CAAC;QACrB,gBAAgB,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE;QACpB,CAAC,WAAW,CAAC,EAAE,kBAAkB;KACpC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,SAAgB,kBAAkB,CAC9B,QAAiC,EACjC,WAAmB;;IAEnB,OAAO,MAAA,QAAQ,CAAC,WAAW,CAAC,0CAAE,SAAS,CAAC;AAC5C,CAAC;AAED,SAAgB,8BAA8B,CAC1C,eAAwC,EACxC,cAAuC;IAEvC,uCACO,eAAe,GACf,cAAc,EACnB;AACN,CAAC","sourcesContent":["import type React from 'react';\n\nimport type {TMessageContent} from '../types/messages';\n\nexport type MessageContentComponentProps<TContent extends TMessageContent = TMessageContent> = {\n    part: TContent;\n};\n\nexport type MessageRenderer<TContent extends TMessageContent = TMessageContent> = {\n    component: React.ComponentType<MessageContentComponentProps<TContent>>;\n};\n\nexport type MessageRendererRegistry = Record<string, MessageRenderer>;\n\nconst defaultRenderers = new WeakSet<MessageRenderer>();\n\nexport function createMessageRendererRegistry(): MessageRendererRegistry {\n    return {};\n}\n\nexport type RegisterMessageRendererOptions = {\n    /**\n     * Marks a renderer as built-in. Replacing built-in renderers is expected\n     * when consumers customize the default registry, so it does not warn.\n     */\n    isDefault?: boolean;\n};\n\nexport function registerMessageRenderer<TContent extends TMessageContent>(\n    registry: MessageRendererRegistry,\n    contentType: TContent['type'],\n    renderer: MessageRenderer<TContent>,\n    options?: RegisterMessageRendererOptions,\n): MessageRendererRegistry {\n    const existingRenderer = registry[contentType];\n    if (\n        process.env.NODE_ENV !== 'production' &&\n        existingRenderer &&\n        !defaultRenderers.has(existingRenderer)\n    ) {\n        // eslint-disable-next-line no-console\n        console.warn(\n            `registerMessageRenderer: overwriting existing renderer for content type \"${contentType}\"`,\n        );\n    }\n    const registeredRenderer = renderer as unknown as MessageRenderer;\n    if (options?.isDefault) {\n        defaultRenderers.add(registeredRenderer);\n    }\n    Object.assign(registry, {\n        [contentType]: registeredRenderer,\n    });\n    return registry;\n}\n\nexport function getMessageRenderer(\n    registry: MessageRendererRegistry,\n    contentType: string,\n): React.ComponentType<MessageContentComponentProps> | undefined {\n    return registry[contentType]?.component;\n}\n\nexport function mergeMessageRendererRegistries(\n    defaultRegistry: MessageRendererRegistry,\n    customRegistry: MessageRendererRegistry,\n): MessageRendererRegistry {\n    return {\n        ...defaultRegistry,\n        ...customRegistry,\n    };\n}\n"]}

package/build/cjs/utils/toolset/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "fallback-unknown-tool": "Unknown tool: {{toolName}}"
+}

package/build/cjs/utils/toolset/i18n/index.d.ts

@@ -0,0 +1,13 @@
+export declare const i18n: ((key: "fallback-unknown-tool", params?: import("@gravity-ui/i18n").Params) => string) & {
+    Translation: import("react").ComponentType<{
+        children: (props: {
+            t: (key: "fallback-unknown-tool", params?: import("@gravity-ui/i18n").Params) => string;
+        }) => React.ReactNode;
+    }>;
+    useTranslation: () => {
+        t: (key: "fallback-unknown-tool", params?: import("@gravity-ui/i18n").Params) => string;
+    };
+    keysetData: {
+        "g-aikit-Toolset": Record<"fallback-unknown-tool", import("@gravity-ui/i18n").KeyData>;
+    };
+};

package/build/cjs/utils/toolset/i18n/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.i18n = void 0;
+const tslib_1 = require("tslib");
+const i18n_1 = require("@gravity-ui/uikit/i18n");
+const cn_1 = require("../../cn.js");
+const en_json_1 = tslib_1.__importDefault(require("./en.json"));
+const ru_json_1 = tslib_1.__importDefault(require("./ru.json"));
+exports.i18n = (0, i18n_1.addComponentKeysets)({ en: en_json_1.default, ru: ru_json_1.default }, `${cn_1.NAMESPACE}Toolset`);
+//# sourceMappingURL=index.js.map

package/build/cjs/utils/toolset/i18n/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"../../../../../src","sources":["utils/toolset/i18n/index.ts"],"names":[],"mappings":";;;;AAAA,iDAA2D;AAE3D,oCAAmC;AAEnC,gEAA2B;AAC3B,gEAA2B;AAEd,QAAA,IAAI,GAAG,IAAA,0BAAmB,EAAC,EAAC,EAAE,EAAF,iBAAE,EAAE,EAAE,EAAF,iBAAE,EAAC,EAAE,GAAG,cAAS,SAAS,CAAC,CAAC","sourcesContent":["import {addComponentKeysets} from '@gravity-ui/uikit/i18n';\n\nimport {NAMESPACE} from '../../cn';\n\nimport en from './en.json';\nimport ru from './ru.json';\n\nexport const i18n = addComponentKeysets({en, ru}, `${NAMESPACE}Toolset`);\n"]}

package/build/cjs/utils/toolset/i18n/ru.json

@@ -0,0 +1,3 @@
+{
+  "fallback-unknown-tool": "Неизвестный инструмент: {{toolName}}"
+}

package/build/cjs/utils/toolset/index.d.ts

@@ -0,0 +1,142 @@
+import type { ComponentType } from 'react';
+import type { TChatMessage, TMessageContent, ToolMessageContentData } from "../../types/messages.js";
+import { type MessageRendererRegistry } from "../messageTypeRegistry.js";
+export type ToolSchemaResult<TArgs> = {
+    success: true;
+    data: TArgs;
+} | {
+    success: false;
+    error: {
+        message: string;
+    };
+};
+export type ToolSchema<TArgs> = {
+    validate: (input: unknown) => ToolSchemaResult<TArgs>;
+};
+export type ToolComponentProps<TArgs, TResult> = {
+    args: TArgs;
+    result?: TResult;
+    submitResult: (result: TResult) => void;
+};
+export type ToolExecutionStatus = 'success' | 'error' | 'cancelled';
+/**
+ * Discriminated outcome returned by a tool's `execute` callback.
+ * A tool may also return a bare `TResult`; it is then treated as
+ * `{status: 'success', result}` to keep simple cases boilerplate-free.
+ */
+export type ToolExecutionOutcome<TResult> = {
+    status: 'success';
+    result: TResult;
+} | {
+    status: 'error';
+    result?: TResult;
+    error?: {
+        message: string;
+    };
+} | {
+    status: 'cancelled';
+    result?: TResult;
+};
+export type ToolDefinition<TArgs, TResult, TName extends string = string> = {
+    name: TName;
+    description: string;
+    parameters: Record<string, unknown>;
+    schema: ToolSchema<TArgs>;
+    component: ComponentType<ToolComponentProps<TArgs, TResult>>;
+    /**
+     * Run after the user submits a result inside the tool component.
+     * Return:
+     *  - `TResult` (or a Promise of one) for a successful execution;
+     *  - a `ToolExecutionOutcome<TResult>` to explicitly report `error`
+     *    or `cancelled`. A thrown error is surfaced as `{status: 'error'}`.
+     */
+    execute?: (params: {
+        args: TArgs;
+        result: TResult;
+        toolCallId: string;
+    }) => TResult | ToolExecutionOutcome<TResult> | Promise<TResult | ToolExecutionOutcome<TResult>>;
+};
+export type RuntimeToolDefinition<TName extends string = string> = {
+    name: TName;
+    description: string;
+    parameters: Record<string, unknown>;
+    validate: (input: unknown) => ToolSchemaResult<unknown>;
+    /**
+     * Rendered as `<Renderer ... />` JSX. Hooks placed at the top of this
+     * component work normally because it is a real React component, not a
+     * function called inside another render path.
+     */
+    Renderer: ComponentType<ToolComponentProps<unknown, unknown>>;
+    execute: (params: {
+        args: unknown;
+        result: unknown;
+        toolCallId: string;
+    }) => unknown | ToolExecutionOutcome<unknown> | Promise<unknown | ToolExecutionOutcome<unknown>>;
+};
+export type Toolset = Record<string, RuntimeToolDefinition>;
+export type ToolPartContentData<TArgs = unknown, TResult = unknown> = ToolMessageContentData & {
+    toolCallId: string;
+    args?: TArgs;
+    result?: TResult;
+};
+export type ToolPartContent<TArgs = unknown, TResult = unknown> = TMessageContent<'tool', ToolPartContentData<TArgs, TResult>>;
+export type ToolsetResultEvent = {
+    toolCallId: string;
+    toolName: string;
+    status: ToolExecutionStatus;
+    result: unknown;
+    error?: {
+        message: string;
+    };
+};
+/**
+ * Wrap a typed tool definition into an erased runtime entry that the
+ * toolset renderer can dispatch by `toolName`. The literal `name` is
+ * preserved as a type parameter so `createToolset` can derive its keys.
+ */
+export declare function defineTool<TArgs, TResult, const TName extends string>(definition: ToolDefinition<TArgs, TResult, TName>): RuntimeToolDefinition<TName>;
+/**
+ * Build a `Toolset` from a list of `defineTool(...)` results. Keys are
+ * derived from `definition.name`, so the call site cannot drift between
+ * a literal-object key and the embedded `name`. The return type narrows
+ * its keys to the union of literal tool names, giving name-autocomplete
+ * on lookups. Throws on duplicates.
+ */
+export declare function createToolset<const T extends readonly RuntimeToolDefinition<string>[]>(...tools: T): {
+    [K in T[number]['name']]: RuntimeToolDefinition<T[number]['name']>;
+};
+/**
+ * Map a `Toolset` to the OpenAI `tools[]` shape so chat clients can pass
+ * tool definitions to the model without reimplementing the conversion.
+ */
+export declare function toolsetToOpenAIDefinitions(toolset: Toolset): Array<{
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}>;
+export type CreateToolsetRendererOptions = {
+    onToolResult: (event: ToolsetResultEvent) => void;
+    /**
+     * Existing registry whose entries should be preserved. A shallow copy
+     * is taken; the input reference is never mutated.
+     */
+    registry?: MessageRendererRegistry;
+};
+/**
+ * Build a `MessageRendererRegistry` whose `tool` renderer dispatches
+ * by `toolName` into the provided toolset. Unknown tools and invalid
+ * args fall back to a generic `<ToolMessage status="error" />`. Errors
+ * thrown inside `execute` are surfaced via an `error` outcome.
+ */
+export declare function createToolsetRenderer(toolset: Toolset, options: CreateToolsetRendererOptions): MessageRendererRegistry;
+/**
+ * Merge a tool result into the matching `tool` part of the chat history.
+ * Honors `event.status` so the part reflects success / error / cancelled.
+ * For backward compatibility, a missing `status` is treated as `'success'`.
+ * Returns the original array reference when nothing matched, so React state
+ * setters can skip needless updates.
+ */
+export declare function applyToolResult<TCustom extends TMessageContent = never>(messages: TChatMessage<TCustom>[], event: ToolsetResultEvent): TChatMessage<TCustom>[];