feat(chat): add support for client side tools

packages/instantsearch-ui-components/src/components/chat/ChatMessage.tsx

@@ -7,10 +7,10 @@ import { MenuIconComponent } from './icons';
 
 import type { ComponentProps, Renderer } from '../../types';
 import type {
-  AddToolResult,
-  ChatInit,
+  AddToolResultWithOutput,
   ChatMessageBase,
   ChatToolMessage,
+  ClientSideTool,
 } from './types';
 
 export type ChatMessageSide = 'left' | 'right';
@@ -77,21 +77,6 @@ export type ChatMessageActionProps = {
   onClick?: (message: ChatMessageBase) => void;
 };
 
-export type Tools = Array<{
-  type: string;
-  component: (props: {
-    message: ChatToolMessage;
-    indexUiState: object;
-    setIndexUiState: (state: object) => void;
-  }) => JSX.Element;
-  onToolCall: (params: {
-    toolCall: Parameters<
-      NonNullable<ChatInit<ChatMessageBase>['onToolCall']>
-    >[0]['toolCall'];
-    addToolResult: AddToolResult;
-  }) => void;
-}>;
-
 export type ChatMessageProps = ComponentProps<'article'> & {
   /**
    * The message object associated with this chat message
@@ -138,7 +123,7 @@ export type ChatMessageProps = ComponentProps<'article'> & {
   /**
    * Array of tools available for the assistant (for tool messages)
    */
-  tools?: Tools;
+  tools?: ClientSideTool[];
   /**
    * Optional handler to refine the search query (for tool actions)
    */
@@ -216,15 +201,25 @@ export function createChatMessageComponent({ createElement }: Renderer) {
         const tool = find(tools, (t) => t.type === part.type);
         if (tool) {
           const ToolComponent = tool.component;
+          const toolMessage = part as ChatToolMessage;
+
+          const boundAddToolResult: AddToolResultWithOutput = (params) =>
+            tool.addToolResult?.({
+              output: params.output,
+              tool: part.type,
+              toolCallId: toolMessage.toolCallId,
+            });
+
           return (
             <div
               key={`${message.id}-${index}`}
               className="ais-ChatMessage-tool"
             >
               <ToolComponent
-                message={part as ChatToolMessage}
+                message={toolMessage}
                 indexUiState={indexUiState}
                 setIndexUiState={setIndexUiState}
+                addToolResult={boundAddToolResult}
               />
             </div>
           );

packages/instantsearch-ui-components/src/components/chat/ChatMessages.tsx

@@ -12,14 +12,10 @@ import {
 } from './icons';
 
 import type { ComponentProps, MutableRef, Renderer } from '../../types';
-import type {
-  ChatMessageProps,
-  Tools,
-  ChatMessageActionProps,
-} from './ChatMessage';
+import type { ChatMessageProps, ChatMessageActionProps } from './ChatMessage';
 import type { ChatMessageErrorProps } from './ChatMessageError';
 import type { ChatMessageLoaderProps } from './ChatMessageLoader';
-import type { ChatMessageBase, ChatStatus } from './types';
+import type { ChatMessageBase, ChatStatus, ClientSideTool } from './types';
 
 export type ChatMessagesTranslations = {
   /**
@@ -85,7 +81,7 @@ export type ChatMessagesProps<
   /**
    * Tools available for the assistant
    */
-  tools?: Tools;
+  tools?: ClientSideTool[];
   /**
    * Current chat status
    */
@@ -173,7 +169,7 @@ function createDefaultMessageComponent<
     assistantMessageProps?: Partial<ChatMessageProps>;
     indexUiState: object;
     setIndexUiState: (state: object) => void;
-    tools?: Tools;
+    tools?: ClientSideTool[];
     onReload?: (messageId?: string) => void;
   }) {
     const defaultAssistantActions: ChatMessageActionProps[] = [

packages/instantsearch-ui-components/src/components/chat/__tests__/ChatMessage.test.tsx

@@ -215,6 +215,7 @@ describe('ChatMessage', () => {
             component: ({ message }) => (
               <div className="wrapper">{JSON.stringify(message.output)}</div>
             ),
+            addToolResult: jest.fn(),
             onToolCall: jest.fn(),
           },
         ]}

packages/instantsearch-ui-components/src/components/chat/types.ts

@@ -9,6 +9,31 @@ export type ChatToolMessage = Extract<
   ChatMessageBase['parts'][number],
   { type: `tool-${string}` }
 >;
+export type ChatToolType = ChatToolMessage['type'];
 
 export type { ChatInit } from 'ai';
 export type AddToolResult = AbstractChat<UIMessage>['addToolResult'];
+
+export type AddToolResultWithOutput = (
+  params: Pick<Parameters<AddToolResult>[0], 'output'>
+) => ReturnType<AddToolResult>;
+
+export type ClientSideToolComponentProps = {
+  message: ChatToolMessage;
+  indexUiState: object;
+  setIndexUiState: (state: object) => void;
+  addToolResult: AddToolResultWithOutput;
+};
+
+export type ClientSideToolComponent = (
+  props: ClientSideToolComponentProps
+) => JSX.Element;
+
+export type ClientSideTool = {
+  type: ChatToolType;
+  component: ClientSideToolComponent;
+  addToolResult: AddToolResult;
+  onToolCall?: (params: { addToolResult: AddToolResultWithOutput }) => void;
+};
+
+export type UserClientSideTool = Omit<ClientSideTool, 'addToolResult'>;

packages/instantsearch.js/src/connectors/chat/connectChat.ts

@@ -264,6 +264,10 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
         };
       },
 
+      get chatInstance() {
+        return _chatInstance;
+      },
+
       dispose() {
         unmountFn();
       },

packages/instantsearch.js/src/lib/chat/index.ts

@@ -3,3 +3,4 @@ export type { ChatInit } from './chat';
 export { AbstractChat } from './chat';
 export { ChatState } from './chat';
 export { Chat } from './chat';
+export * from './tools';

packages/instantsearch.js/src/lib/chat/tools.ts

@@ -0,0 +1,5 @@
+import type { ChatToolType } from 'instantsearch-ui-components';
+
+export const SearchIndexToolType: ChatToolType = 'tool-algolia_search_index';
+
+export const defaultTools: ChatToolType[] = [SearchIndexToolType];