@meetsmore-oss/use-ai-client 1.15.0 → 1.16.0

package/dist/index.d.ts

@@ -668,24 +668,40 @@ interface FileAttachment {
     transformedContent?: string;
 }
 /**
- * Abstract file upload backend interface.
- * Converts File objects to URLs at send time.
+ * Result of preparing a file for send.
+ *
+ * Only one of the two is returned:
+ * - `{ url }`: a directly usable url (an inline base64 data URL, or a remote url).
+ *   The bytes travel along with the message.
+ * - `{ ref }`: a pointer into persistent storage (e.g. an S3 key). The bytes stay in
+ *   storage; only the ref travels with the message and is kept in history. It is
+ *   resolved on the server before being passed to the model.
+ *
+ * A backend may also return a bare `string`, which is treated as `{ url: string }`
+ * (for backward compatibility with backends written against the older signature).
+ */
+type FileUploadResult = {
+    url: string;
+} | {
+    ref: string;
+};
+/**
+ * Interface for an abstract file upload backend.
+ * Converts a File object into a sendable reference at send time.
  *
  * Implementations:
- * - EmbedFileUploadBackend: Converts to base64 data URL (built-in)
- * - S3FileUploadBackend: Uploads to S3 and returns public URL (future)
+ * - EmbedFileUploadBackend: converts to a base64 data URL (built-in)
+ * - S3FileUploadBackend: uploads to storage and returns a `ref` (future)
  */
 interface FileUploadBackend {
     /**
-     * Prepare file for sending to AI.
-     * Called at send time - converts File to URL.
+     * Prepare a file to send to the AI. Called at send time.
      *
      * @param file - The File object to prepare
-     * @returns Promise resolving to a URL string
-     *          - For embed: base64 data URL
-     *          - For S3: public URL after upload
+     * @returns A {@link FileUploadResult} (`{ url }` or `{ ref }`), or a bare url string
+     *          for backward compatibility (treated as `{ url }`).
      */
-    prepareForSend(file: File): Promise<string>;
+    prepareForSend(file: File): Promise<string | FileUploadResult>;
 }
 /**
  * Context provided to file transformers.
@@ -773,6 +789,14 @@ interface FileUploadConfig {
      * before being sent to the AI.
      */
     transformers?: FileTransformerMap;
+    /**
+     * Maximum number of attachments allowed per message.
+     * Enforced at attach time; files beyond the limit are rejected with an error.
+     * The value is the host's policy (e.g. set it below the AI provider's per-message
+     * limit). use-ai only exposes the knob and assumes no default. When undefined, the
+     * number of attachments is not limited.
+     */
+    maxAttachments?: number;
 }
 
 /**
@@ -811,11 +835,35 @@ interface PersistedTransformedFileContent {
     text: string;
     originalFile: PersistedFileMetadata;
 }
+/**
+ * Ref-backed attachment content part for persisted messages.
+ *
+ * Unlike {@link PersistedFileContent} (metadata only, discarded on reload), this part
+ * holds a `ref` into persistent storage (e.g. an S3 key). This lets attachments be
+ * re-sent to the AI even after a page reload. The actual bytes live in storage rather
+ * than localStorage, and the ref is resolved on the host before the next run.
+ *
+ * Covers both image and non-image attachments in a single type (the persistence layer
+ * does not split them: display is identical, and the re-send tag is derived from
+ * `mimeType`). On reload it is read two ways: as a name/size chip for display, and as a
+ * re-sendable `{ type: 'image_ref' | 'file_ref', ref }` wire part (see `messageConversion.ts`).
+ */
+interface PersistedAttachmentRefContent {
+    type: 'attachment_ref';
+    /** Ref into persistent storage (e.g. an S3 key). Never expires. */
+    ref: string;
+    /** Original file name (for display). */
+    name: string;
+    /** MIME type, e.g. 'image/jpeg' | 'application/pdf'. Decides whether to re-send as image or file. */
+    mimeType: string;
+    /** Byte size after client-side resize (for display). */
+    size: number;
+}
 /**
  * Content part for persisted messages.
- * Can be text, file metadata, or transformed file content.
+ * One of: text, file metadata, transformed file content, or a ref-backed attachment.
  */
-type PersistedContentPart = PersistedTextContent | PersistedFileContent | PersistedTransformedFileContent;
+type PersistedContentPart = PersistedTextContent | PersistedFileContent | PersistedTransformedFileContent | PersistedAttachmentRefContent;
 /**
  * Content that can be persisted.
  * Simple string for text-only messages, or array for multimodal content.
@@ -1200,6 +1248,8 @@ declare const defaultStrings: {
         fileSizeError: string;
         /** File type error (use {type} placeholder) */
         fileTypeError: string;
+        /** Error when too many files are attached (use {max} placeholder) */
+        maxAttachmentsError: string;
     };
     floatingButton: {
         /** Floating button title when connected */
@@ -2638,4 +2688,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 EnabledFeatures, 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 SubmitMode, 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 };
+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 EnabledFeatures, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FileUploadResult, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedAttachmentRefContent, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type PersistedTransformedFileContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type SubmitMode, 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

@@ -56,7 +56,9 @@ var defaultStrings = {
     /** File size error (use {filename} and {maxSize} placeholders) */
     fileSizeError: 'File "{filename}" exceeds {maxSize}MB limit',
     /** File type error (use {type} placeholder) */
-    fileTypeError: 'File type "{type}" is not accepted'
+    fileTypeError: 'File type "{type}" is not accepted',
+    /** Error when too many files are attached (use {max} placeholder) */
+    maxAttachmentsError: "You can attach at most {max} files per message"
   },
   // Floating button
   floatingButton: {
@@ -1405,6 +1407,9 @@ async function getTransformedContent(files, transformer, context, onProgress) {
   transformationCache.set(cacheKey, results);
   return results;
 }
+function normalizeUploadResult(result) {
+  return typeof result === "string" ? { url: result } : result;
+}
 async function toContentPart(attachment, backend) {
   if (attachment.transformedContent !== void 0) {
     return {
@@ -1417,16 +1422,12 @@ async function toContentPart(attachment, backend) {
       }
     };
   }
-  const url = await backend.prepareForSend(attachment.file);
-  if (attachment.file.type.startsWith("image/")) {
-    return { type: "image", url };
+  const result = normalizeUploadResult(await backend.prepareForSend(attachment.file));
+  const isImage = attachment.file.type.startsWith("image/");
+  if ("ref" in result) {
+    return isImage ? { type: "image_ref", ref: result.ref } : { type: "file_ref", ref: result.ref, mimeType: attachment.file.type, name: attachment.file.name };
   }
-  return {
-    type: "file",
-    url,
-    mimeType: attachment.file.type,
-    name: attachment.file.name
-  };
+  return isImage ? { type: "image_url", url: result.url } : { type: "file_url", url: result.url, mimeType: attachment.file.type, name: attachment.file.name };
 }
 async function processAttachments(attachments, config) {
   const { getCurrentChat, backend = new EmbedFileUploadBackend(), transformers = {}, onFileProgress } = config;
@@ -1529,7 +1530,12 @@ function useFileUpload({
   const enabled = config !== void 0;
   const maxFileSize = config?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
   const acceptedTypes = config?.acceptedTypes;
+  const maxAttachments = config?.maxAttachments;
   const transformers = config?.transformers;
+  const attachmentsRef = useRef3(attachments);
+  useEffect3(() => {
+    attachmentsRef.current = attachments;
+  }, [attachments]);
   useEffect3(() => {
     if (fileError) {
       const timer = setTimeout(() => setFileError(null), 3e3);
@@ -1565,7 +1571,13 @@ function useFileUpload({
   }, [getCurrentChat, transformers]);
   const handleFiles = useCallback2(async (files) => {
     const fileArray = Array.from(files);
+    let currentCount = attachmentsRef.current.length;
     for (const file of fileArray) {
+      if (maxAttachments !== void 0 && currentCount >= maxAttachments) {
+        const errorMsg = strings.fileUpload.maxAttachmentsError.replace("{max}", String(maxAttachments));
+        setFileError(errorMsg);
+        break;
+      }
       if (file.size > maxFileSize) {
         const errorMsg = strings.fileUpload.fileSizeError.replace("{filename}", file.name).replace("{maxSize}", String(Math.round(maxFileSize / (1024 * 1024))));
         setFileError(errorMsg);
@@ -1584,14 +1596,17 @@ function useFileUpload({
         preview
       };
       setAttachments((prev) => [...prev, attachment]);
+      attachmentsRef.current = [...attachmentsRef.current, attachment];
+      currentCount++;
       const transformerKey = findTransformerPattern(file.type, transformers);
       if (transformerKey) {
         runTransformer(attachmentId, file, transformerKey);
       }
     }
-  }, [maxFileSize, acceptedTypes, strings, transformers, runTransformer]);
+  }, [maxFileSize, acceptedTypes, maxAttachments, strings, transformers, runTransformer]);
   const removeAttachment = useCallback2((id) => {
     setAttachments((prev) => prev.filter((a) => a.id !== id));
+    attachmentsRef.current = attachmentsRef.current.filter((a) => a.id !== id);
     setProcessingState((prev) => {
       const next = new Map(prev);
       next.delete(id);
@@ -1600,6 +1615,7 @@ function useFileUpload({
   }, []);
   const clearAttachments = useCallback2(() => {
     setAttachments([]);
+    attachmentsRef.current = [];
     setProcessingState(/* @__PURE__ */ new Map());
   }, []);
   const openFilePicker = useCallback2(() => {
@@ -2170,7 +2186,16 @@ function FeedbackButton({ type, isSelected, onClick, selectedColor, unselectedCo
   );
 }
 function hasFileContent(content) {
-  return Array.isArray(content) && content.some((part) => part.type === "file");
+  return Array.isArray(content) && content.some((part) => part.type === "file" || part.type === "attachment_ref");
+}
+function fileChipInfo(part) {
+  if (part.type === "file") {
+    return { name: part.file.name, size: part.file.size };
+  }
+  if (part.type === "attachment_ref") {
+    return { name: part.name, size: part.size };
+  }
+  return null;
 }
 function UseAIChatPanel({
   onSendMessage,
@@ -2843,14 +2868,10 @@ function UseAIChatPanel({
                                   wordWrap: "break-word"
                                 },
                                 children: [
-                                  message.role === "user" && hasFileContent(message.content) && /* @__PURE__ */ jsx12("div", { style: { display: "flex", flexWrap: "wrap", gap: "6px", marginBottom: "8px" }, children: message.content.filter((part) => part.type === "file").map((part, idx) => /* @__PURE__ */ jsx12(
-                                    FilePlaceholder,
-                                    {
-                                      name: part.file.name,
-                                      size: part.file.size
-                                    },
-                                    idx
-                                  )) }),
+                                  message.role === "user" && hasFileContent(message.content) && /* @__PURE__ */ jsx12("div", { style: { display: "flex", flexWrap: "wrap", gap: "6px", marginBottom: "8px" }, children: message.content.flatMap((part, idx) => {
+                                    const info = fileChipInfo(part);
+                                    return info ? [/* @__PURE__ */ jsx12(FilePlaceholder, { name: info.name, size: info.size }, idx)] : [];
+                                  }) }),
                                   message.role === "assistant" ? /* @__PURE__ */ jsxs9(Fragment, { children: [
                                     message.reasoningParts && message.reasoningParts.length > 0 && /* @__PURE__ */ jsx12(
                                       Reasoning,
@@ -3669,31 +3690,13 @@ var UseAIClient = class {
   async sendPrompt(prompt, multimodalContent, forwardedProps) {
     let messageContent = prompt;
     if (multimodalContent && multimodalContent.length > 0) {
-      messageContent = multimodalContent.map((part) => {
-        if (part.type === "text") {
-          return { type: "text", text: part.text };
-        } else if (part.type === "image") {
-          return { type: "image", url: part.url };
-        } else if (part.type === "file") {
-          return {
-            type: "file",
-            url: part.url,
-            mimeType: part.mimeType
-          };
-        } else {
-          return {
-            type: "transformed_file",
-            text: part.text,
-            originalFile: part.originalFile
-          };
-        }
-      });
+      messageContent = multimodalContent;
     }
     const userMessage = {
       id: uuidv42(),
       role: "user",
+      // @ag-ui/core declares Message.content as `string`; the wire also carries MultimodalContent[].
       content: messageContent
-      // Type cast needed for Message type compatibility
     };
     this._messages.push(userMessage);
     const runId = uuidv42();
@@ -4391,6 +4394,7 @@ function buildPersistedParts(message, attachments, fileContent) {
     parts.push({ type: "text", text: message });
   }
   const transformedByKey = /* @__PURE__ */ new Map();
+  const nonTransformedParts = [];
   for (const part of fileContent) {
     if (part.type === "transformed_file") {
       const key = `${part.originalFile.name}:${part.originalFile.size}:${part.originalFile.mimeType}`;
@@ -4400,6 +4404,8 @@ function buildPersistedParts(message, attachments, fileContent) {
       } else {
         transformedByKey.set(key, [part]);
       }
+    } else {
+      nonTransformedParts.push(part);
     }
   }
   for (const attachment of attachments) {
@@ -4411,6 +4417,18 @@ function buildPersistedParts(message, attachments, fileContent) {
         text: transformed.text,
         originalFile: transformed.originalFile
       });
+      continue;
+    }
+    const part = nonTransformedParts.shift();
+    const ref = part && (part.type === "image_ref" || part.type === "file_ref") ? part.ref : void 0;
+    if (ref) {
+      parts.push({
+        type: "attachment_ref",
+        ref,
+        name: attachment.file.name,
+        mimeType: attachment.file.type,
+        size: attachment.file.size
+      });
     } else {
       parts.push({
         type: "file",
@@ -4463,9 +4481,18 @@ function transformMessagesToClientFormat(persistedMessages) {
 ${p.text}`
             }];
           }
+          if (p.type === "attachment_ref") {
+            return [
+              p.mimeType.startsWith("image/") ? { type: "image_ref", ref: p.ref } : { type: "file_ref", ref: p.ref, mimeType: p.mimeType, name: p.name }
+            ];
+          }
           return [];
         });
-        return { id: msg.id, role: "user", content: parts };
+        return {
+          id: msg.id,
+          role: "user",
+          content: parts
+        };
       }
     }
   });