@gravity-ui/aikit 2.3.0 → 2.4.0

package/docs/HOOKS.md

@@ -1,16 +1,17 @@
 # Hooks
 
-AIKit exports 7 public hooks. All are re-exported from the package root and from the `@gravity-ui/aikit/hooks` subpath.
-
-| Hook                                                        | Purpose                                                      |
-| ----------------------------------------------------------- | ------------------------------------------------------------ |
-| [`useDateFormatter`](#usedateformatter)                     | Format chat timestamps with locale and relative-date logic   |
-| [`useToolMessage`](#usetoolmessage)                         | Tool-message state machine (expand/collapse based on status) |
-| [`useSmartScroll`](#usesmartscroll)                         | Auto-scroll to bottom while respecting user scroll-up        |
-| [`useScrollPreservation`](#usescrollpreservation)           | Preserve scroll position when items are prepended            |
-| [`useAutoCollapseOnSuccess`](#useautocollapseonsuccess)     | Collapse a section when its async operation succeeds         |
-| [`useAutoCollapseOnCancelled`](#useautocollapseoncancelled) | Collapse a section when its async operation is cancelled     |
-| [`useFileUploadStore`](#usefileuploadstore)                 | Standalone file-upload store with progress/error states      |
+AIKit exports 8 public hooks. All are re-exported from the package root and from the `@gravity-ui/aikit/hooks` subpath.
+
+| Hook                                                        | Purpose                                                                        |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [`useDateFormatter`](#usedateformatter)                     | Format chat timestamps with locale and relative-date logic                     |
+| [`useToolMessage`](#usetoolmessage)                         | Tool-message state machine (expand/collapse based on status)                   |
+| [`useSmartScroll`](#usesmartscroll)                         | Auto-scroll to bottom while respecting user scroll-up                          |
+| [`useScrollPreservation`](#usescrollpreservation)           | Preserve scroll position when items are prepended                              |
+| [`useAutoCollapseOnSuccess`](#useautocollapseonsuccess)     | Collapse a section when its async operation succeeds                           |
+| [`useAutoCollapseOnCancelled`](#useautocollapseoncancelled) | Collapse a section when its async operation is cancelled                       |
+| [`useFileUploadStore`](#usefileuploadstore)                 | Standalone file-upload store with progress/error states                        |
+| [`useToolset`](#usetoolset)                                 | Wire a toolset into the chat: renderer registry + history merge for tool calls |
 
 ## `useDateFormatter`
 
@@ -129,3 +130,56 @@ type UseFileUploadStoreReturn<Meta> = {
 ```
 
 See `src/hooks/useFileUploadStore.ts` for the complete type signature.
+
+## `useToolset`
+
+Wires a `Toolset` into the chat: returns a `MessageRendererRegistry` whose `tool`
+dispatcher renders your tool components, and a `handleToolResult` callback that
+merges results into history via `applyToolResult`. It does not run model
+continuation side effects; pair it with `useToolResultContinuation` when you
+need to re-send the updated conversation after a tool completes.
+
+```typescript
+function useToolset<TCustom extends TMessageContent = never>(
+  options: UseToolsetOptions<TCustom>,
+): UseToolsetReturn;
+
+type UseToolsetOptions<TCustom> = {
+  toolset: Toolset;
+  setMessages: Dispatch<SetStateAction<TChatMessage<TCustom>[]>>;
+  registry?: MessageRendererRegistry;
+};
+
+type UseToolsetReturn = {
+  messageRendererRegistry: MessageRendererRegistry;
+  handleToolResult: (event: ToolsetResultEvent) => void;
+};
+```
+
+## `useToolResultContinuation`
+
+Observes `messages` and calls `onSettled` once when a tool part moves from a
+pending status (`loading`, `waitingConfirmation`, `waitingSubmission`) to a
+terminal status (`success`, `error`, `cancelled`). Tools that are already
+terminal in the first observed snapshot do not fire, so replay/restore is silent
+by default.
+
+```typescript
+function useToolResultContinuation<TCustom extends TMessageContent = never>(
+  options: UseToolResultContinuationOptions<TCustom>,
+): void;
+
+type UseToolResultContinuationOptions<TCustom> = {
+  messages: TChatMessage<TCustom>[];
+  onSettled: (event: ToolSettledEvent<TCustom>) => void;
+};
+
+type ToolSettledEvent<TCustom> = {
+  toolCallId: string;
+  toolName: string;
+  status: 'success' | 'error' | 'cancelled';
+  messages: TChatMessage<TCustom>[];
+};
+```
+
+See [GENUI.md](./GENUI.md) for an end-to-end example with a live model adapter.

package/llms.txt

@@ -88,6 +88,7 @@ Tree-shaken imports: `@gravity-ui/aikit/PromptInput`, `/Header`, `/MessageList`,
 - [useAutoCollapseOnSuccess](https://github.com/gravity-ui/aikit/blob/main/src/hooks/useAutoCollapseOnSuccess.ts): auto-collapse a section on success status
 - [useAutoCollapseOnCancelled](https://github.com/gravity-ui/aikit/blob/main/src/hooks/useAutoCollapseOnCancelled.ts): auto-collapse a section on cancelled status
 - [useFileUploadStore](https://github.com/gravity-ui/aikit/blob/main/src/hooks/useFileUploadStore.ts): headless file-upload store with progress/error states
+- [useToolset](https://github.com/gravity-ui/aikit/blob/main/src/hooks/useToolset.ts): wire a toolset into the chat — renderer registry + history merge for tool calls
 
 ## Theming & i18n
 
@@ -103,6 +104,6 @@ Tree-shaken imports: `@gravity-ui/aikit/PromptInput`, `/Header`, `/MessageList`,
 - [Live Storybook](https://preview.gravity-ui.com/aikit/): interactive component playground
 - [Project Structure](https://github.com/gravity-ui/aikit/blob/main/docs/PROJECT_STRUCTURE.md): source tree (for contributors)
 - [Components Catalog](https://github.com/gravity-ui/aikit/blob/main/docs/COMPONENTS.md): same component list as above, with table-style reference
-- [Hooks Reference](https://github.com/gravity-ui/aikit/blob/main/docs/HOOKS.md): detailed signatures for the 7 public hooks
+- [Hooks Reference](https://github.com/gravity-ui/aikit/blob/main/docs/HOOKS.md): detailed signatures for the 8 public hooks
 - [AI Agent Integration](https://github.com/gravity-ui/aikit/blob/main/docs/AI_AGENTS.md): drop-in Cursor rule and Claude Code skill for consumer projects
 - [Issue tracker](https://github.com/gravity-ui/aikit/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ui/aikit",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Gravity UI base kit for building ai assistant chats",
   "license": "MIT",
   "type": "commonjs",
@@ -98,6 +98,16 @@
         "default": "./build/cjs/utils/clipboardUtils.js"
       }
     },
+    "./utils/toolset": {
+      "import": {
+        "types": "./build/esm/utils/toolset/index.d.ts",
+        "default": "./build/esm/utils/toolset/index.js"
+      },
+      "require": {
+        "types": "./build/cjs/utils/toolset/index.d.ts",
+        "default": "./build/cjs/utils/toolset/index.js"
+      }
+    },
     "./adapters": {
       "import": {
         "types": "./build/esm/adapters/index.d.ts",