@meetsmore-oss/use-ai-client 1.8.0 → 1.9.0

package/dist/index.d.ts

@@ -5,6 +5,44 @@ export { AgentInfo, ToolAnnotations, ToolDefinition } from '@meetsmore-oss/use-a
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { MutableRefObject, RefObject, ReactNode } from 'react';
 
+/**
+ * Context provided to tool execution functions.
+ * Allows tools to dynamically request user approval at runtime.
+ */
+interface ToolExecutionContext {
+    /**
+     * Request user approval during tool execution.
+     * Use this for conditional approval based on runtime values
+     * (e.g., API endpoint, input values, computed risk).
+     *
+     * @param input - Approval request details
+     * @returns Promise resolving with approval decision
+     *
+     * @example
+     * ```typescript
+     * const callApi = defineTool(
+     *   'Call an external API',
+     *   z.object({ url: z.string() }),
+     *   async (input, ctx) => {
+     *     if (input.url.includes('production')) {
+     *       const { approved } = await ctx.requestApproval({
+     *         message: `This will call production API: ${input.url}`,
+     *       });
+     *       if (!approved) return { error: 'User rejected the action' };
+     *     }
+     *     return fetch(input.url);
+     *   }
+     * );
+     * ```
+     */
+    requestApproval(input: {
+        message: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+}
 /**
  * Options for configuring tool behavior.
  */
@@ -36,13 +74,13 @@ interface DefinedTool<T extends z.ZodType> {
     /** Zod schema for validating input */
     _zodSchema: T;
     /** The function to execute when the tool is called */
-    fn: (input: z.infer<T>) => unknown | Promise<unknown>;
+    fn: (input: z.infer<T>, ctx: ToolExecutionContext) => unknown | Promise<unknown>;
     /** Configuration options for the tool */
     _options: ToolOptions;
     /** Converts this tool to a ToolDefinition for registration with the server */
     _toToolDefinition: (name: string) => ToolDefinition;
     /** Validates input and executes the tool function */
-    _execute: (input: unknown) => Promise<unknown>;
+    _execute: (input: unknown, ctx: ToolExecutionContext) => Promise<unknown>;
 }
 /**
  * Defines a tool with no input parameters that can be called by the AI.
@@ -61,7 +99,7 @@ interface DefinedTool<T extends z.ZodType> {
  * );
  * ```
  */
-declare function defineTool<TReturn>(description: string, fn: () => TReturn | Promise<TReturn>, options?: ToolOptions): DefinedTool<z.ZodObject<{}>>;
+declare function defineTool<TReturn>(description: string, fn: (ctx: ToolExecutionContext) => TReturn | Promise<TReturn>, options?: ToolOptions): DefinedTool<z.ZodObject<{}>>;
 /**
  * Defines a tool with typed input parameters that can be called by the AI.
  *
@@ -87,7 +125,7 @@ declare function defineTool<TReturn>(description: string, fn: () => TReturn | Pr
  * );
  * ```
  */
-declare function defineTool<TSchema extends z.ZodType>(description: string, schema: TSchema, fn: (input: z.infer<TSchema>) => unknown | Promise<unknown>, options?: ToolOptions): DefinedTool<TSchema>;
+declare function defineTool<TSchema extends z.ZodType>(description: string, schema: TSchema, fn: (input: z.infer<TSchema>, ctx: ToolExecutionContext) => unknown | Promise<unknown>, options?: ToolOptions): DefinedTool<TSchema>;
 /**
  * A collection of named tools.
  * Used to register multiple tools with the useAI hook.
@@ -111,7 +149,7 @@ declare function convertToolsToDefinitions(tools: ToolsDefinition): ToolDefiniti
  * @throws Error if the tool is not found
  * @internal
  */
-declare function executeDefinedTool(tools: ToolsDefinition, toolName: string, input: unknown): Promise<unknown>;
+declare function executeDefinedTool(tools: ToolsDefinition, toolName: string, input: unknown, ctx: ToolExecutionContext): Promise<unknown>;
 
 /**
  * Options for configuring the useAI hook.
@@ -1155,6 +1193,10 @@ interface PendingToolApproval {
     toolCallName: string;
     toolCallArgs: Record<string, unknown>;
     annotations?: ToolAnnotations;
+    /** Optional message explaining why approval is needed (runtime approval) */
+    message?: string;
+    /** Optional metadata for the approval request (runtime approval) */
+    metadata?: Record<string, unknown>;
 }
 interface UseToolSystemOptions {
     /** Reference to the UseAI client for sending responses */
@@ -2376,4 +2418,4 @@ interface UseDropdownStateOptions {
  */
 declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;
 
-export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, validateCommandName };
+export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolExecutionContext, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, validateCommandName };

package/dist/index.js

@@ -1638,7 +1638,8 @@ function ToolApprovalDialog({
   const [showDetails, setShowDetails] = useState4(false);
   const displayName = annotations?.title || toolCallName;
   const isBatch = toolCount > 1;
-  const message = isBatch ? strings.toolApproval.batchMessage?.replace("{count}", String(toolCount)) ?? `${toolCount} actions are waiting for your approval` : strings.toolApproval.message.replace("{toolName}", displayName);
+  const runtimeMessage = pendingTools.find((t) => t.message)?.message;
+  const message = runtimeMessage ? runtimeMessage : isBatch ? strings.toolApproval.batchMessage?.replace("{count}", String(toolCount)) ?? `${toolCount} actions are waiting for your approval` : strings.toolApproval.message.replace("{toolName}", displayName);
   const getToolDisplayName = (tool) => tool.annotations?.title || tool.toolCallName;
   return /* @__PURE__ */ jsxs7(
     "div",
@@ -3605,7 +3606,8 @@ function defineTool(description, schemaOrFn, fnOrOptions, options) {
   let actualFn;
   let actualOptions;
   if (isNoParamFunction) {
-    actualFn = schemaOrFn;
+    const noParamFn = schemaOrFn;
+    actualFn = (_input, ctx) => noParamFn(ctx);
     actualOptions = fnOrOptions || {};
   } else {
     actualFn = fnOrOptions;
@@ -3639,21 +3641,21 @@ function defineTool(description, schemaOrFn, fnOrOptions, options) {
       }
       return toolDef;
     },
-    async _execute(input) {
+    async _execute(input, ctx) {
       const validated = this._zodSchema.parse(input);
-      return await actualFn(validated);
+      return await actualFn(validated, ctx);
     }
   };
 }
 function convertToolsToDefinitions(tools) {
   return Object.entries(tools).map(([name, tool]) => tool._toToolDefinition(name));
 }
-async function executeDefinedTool(tools, toolName, input) {
+async function executeDefinedTool(tools, toolName, input, ctx) {
   const tool = tools[toolName];
   if (!tool) {
     throw new Error(`Tool "${toolName}" not found`);
   }
-  return await tool._execute(input);
+  return await tool._execute(input, ctx);
 }
 
 // src/providers/chatRepository/LocalStorageChatRepository.ts
@@ -4344,6 +4346,7 @@ function useToolSystem({
   const waitersRef = useRef7(/* @__PURE__ */ new Map());
   const [pendingApprovals, setPendingApprovals] = useState9([]);
   const pendingApprovalToolCallsRef = useRef7(/* @__PURE__ */ new Map());
+  const runtimeApprovalResolversRef = useRef7(/* @__PURE__ */ new Map());
   const registerTools = useCallback7((id, tools, options) => {
     const existingTools = toolRegistryRef.current.get(id);
     toolRegistryRef.current.set(id, tools);
@@ -4453,7 +4456,9 @@ function useToolSystem({
         toolCallId: event.toolCallId,
         toolCallName: event.toolCallName,
         toolCallArgs: event.toolCallArgs,
-        annotations: event.annotations
+        annotations: event.annotations,
+        message: event.message,
+        metadata: event.metadata
       }
     ]);
   }, []);
@@ -4466,8 +4471,26 @@ function useToolSystem({
     try {
       const ownerId = toolOwnershipRef.current.get(name);
       console.log(`[useToolSystem] Tool "${name}" owned by component:`, ownerId);
+      const ctx = {
+        requestApproval: ({ message, metadata }) => {
+          return new Promise((resolve) => {
+            const approvalId = `${toolCallId}-runtime-${Date.now()}`;
+            runtimeApprovalResolversRef.current.set(approvalId, resolve);
+            setPendingApprovals((prev) => [
+              ...prev,
+              {
+                toolCallId: approvalId,
+                toolCallName: name,
+                toolCallArgs: input || {},
+                message,
+                metadata
+              }
+            ]);
+          });
+        }
+      };
       console.log("[useToolSystem] Executing tool...");
-      const result = await executeDefinedTool(aggregatedToolsRef.current, name, input);
+      const result = await executeDefinedTool(aggregatedToolsRef.current, name, input, ctx);
       const isErrorResult = result && typeof result === "object" && ("error" in result || result.success === false);
       const ownerIsInvisible = ownerId ? isInvisible(ownerId) : false;
       if (ownerId && !isErrorResult && !ownerIsInvisible) {
@@ -4512,24 +4535,32 @@ function useToolSystem({
     if (!clientRef.current) return;
     console.log("[useToolSystem] Approving all tool calls:", pendingApprovals.length);
     const pendingTools = [...pendingApprovals];
-    for (const pending of pendingTools) {
-      clientRef.current.sendToolApprovalResponse(pending.toolCallId, true);
-    }
     setPendingApprovals([]);
-    for (const tool of pendingTools) {
-      await executePendingToolAfterApproval(tool.toolCallId);
+    for (const pending of pendingTools) {
+      const runtimeResolver = runtimeApprovalResolversRef.current.get(pending.toolCallId);
+      if (runtimeResolver) {
+        runtimeApprovalResolversRef.current.delete(pending.toolCallId);
+        runtimeResolver({ approved: true });
+      } else {
+        clientRef.current.sendToolApprovalResponse(pending.toolCallId, true);
+        await executePendingToolAfterApproval(pending.toolCallId);
+      }
     }
   }, [clientRef, pendingApprovals, executePendingToolAfterApproval]);
   const rejectAll = useCallback7((reason) => {
     if (!clientRef.current) return;
     console.log("[useToolSystem] Rejecting all tool calls:", pendingApprovals.length, reason);
     const pendingTools = [...pendingApprovals];
-    for (const pending of pendingTools) {
-      clientRef.current.sendToolApprovalResponse(pending.toolCallId, false, reason);
-    }
     setPendingApprovals([]);
-    for (const tool of pendingTools) {
-      pendingApprovalToolCallsRef.current.delete(tool.toolCallId);
+    for (const pending of pendingTools) {
+      const runtimeResolver = runtimeApprovalResolversRef.current.get(pending.toolCallId);
+      if (runtimeResolver) {
+        runtimeApprovalResolversRef.current.delete(pending.toolCallId);
+        runtimeResolver({ approved: false, reason });
+      } else {
+        clientRef.current.sendToolApprovalResponse(pending.toolCallId, false, reason);
+        pendingApprovalToolCallsRef.current.delete(pending.toolCallId);
+      }
     }
   }, [clientRef, pendingApprovals]);
   return {
@@ -5326,19 +5357,19 @@ function useStableTools(tools) {
   return stableToolsRef.current;
 }
 function createStableToolWrapper(name, tool, latestToolsRef) {
-  const stableHandler = (input) => {
+  const stableHandler = (input, ctx) => {
     const currentTool = latestToolsRef.current[name];
     if (!currentTool) {
       throw new Error(`Tool "${name}" no longer exists`);
     }
-    return currentTool.fn(input);
+    return currentTool.fn(input, ctx);
   };
-  const stableExecute = async (input) => {
+  const stableExecute = async (input, ctx) => {
     const currentTool = latestToolsRef.current[name];
     if (!currentTool) {
       throw new Error(`Tool "${name}" no longer exists`);
     }
-    return await currentTool._execute(input);
+    return await currentTool._execute(input, ctx);
   };
   return {
     description: tool.description,
@@ -5546,7 +5577,10 @@ function useAIWorkflow(runner, workflowId) {
         console.log(`[useAIWorkflow] Executing tool: ${toolName}`, toolArgs);
         console.log(`[useAIWorkflow] Available tools:`, Object.keys(currentWorkflow.tools));
         try {
-          const result = await executeDefinedTool(currentWorkflow.tools, toolName, toolArgs);
+          const noopCtx = {
+            requestApproval: async () => ({ approved: true })
+          };
+          const result = await executeDefinedTool(currentWorkflow.tools, toolName, toolArgs, noopCtx);
           currentWorkflow.toolCalls.push({
             toolName,
             args: toolArgs,