Implement optimistic UI for file uploads and enhance message handling (#967)

* feat(upload): implement optimistic UI for file uploads and enhance message handling

* feat(middleware): enhance file handling by collecting historical uploads from directory

* feat(thread-title): update page title handling for new threads and improve loading state

* feat(uploads-middleware): enhance file extraction by verifying file existence in uploads directory

* feat(thread-stream): update file path reference to use virtual_path for uploads

* feat(tests): add core behaviour tests for UploadsMiddleware

* feat(tests): remove unused pytest import from test_uploads_middleware_core_logic.py

* feat: enhance file upload handling and localization support

- Update UploadsMiddleware to validate filenames more robustly.
- Modify MessageListItem to parse uploaded files from raw content for backward compatibility.
- Add localization for uploading messages in English and Chinese.
- Introduce parseUploadedFiles utility to extract uploaded files from message content.

frontend/src/core/i18n/locales/en-US.ts

@@ -88,9 +88,11 @@ export const enUS: Translations = {
     reasoningEffortLow: "Low",
     reasoningEffortLowDescription: "Simple Logic Check + Shallow Deduction",
     reasoningEffortMedium: "Medium",
-    reasoningEffortMediumDescription: "Multi-layer Logic Analysis + Basic Verification",
+    reasoningEffortMediumDescription:
+      "Multi-layer Logic Analysis + Basic Verification",
     reasoningEffortHigh: "High",
-    reasoningEffortHighDescription: "Full-dimensional Logic Deduction + Multi-path Verification + Backward Check",
+    reasoningEffortHighDescription:
+      "Full-dimensional Logic Deduction + Multi-path Verification + Backward Check",
     searchModels: "Search models...",
     surpriseMe: "Surprise",
     surpriseMePrompt: "Surprise me",
@@ -248,6 +250,11 @@ export const enUS: Translations = {
   },
 
   // Subtasks
+  uploads: {
+    uploading: "Uploading...",
+    uploadingFiles: "Uploading files, please wait...",
+  },
+
   subtasks: {
     subtask: "Subtask",
     executing: (count: number) =>

frontend/src/core/i18n/locales/types.ts

@@ -187,6 +187,12 @@ export interface Translations {
     skillInstallTooltip: string;
   };
 
+  // Uploads
+  uploads: {
+    uploading: string;
+    uploadingFiles: string;
+  };
+
   // Subtasks
   subtasks: {
     subtask: string;

frontend/src/core/i18n/locales/zh-CN.ts

@@ -238,6 +238,11 @@ export const zhCN: Translations = {
     skillInstallTooltip: "安装技能并使其可在 DeerFlow 中使用",
   },
 
+  uploads: {
+    uploading: "上传中...",
+    uploadingFiles: "文件上传中，请稍候...",
+  },
+
   subtasks: {
     subtask: "子任务",
     executing: (count: number) =>

frontend/src/core/messages/utils.ts

@@ -263,57 +263,56 @@ export function findToolCallResult(toolCallId: string, messages: Message[]) {
 }
 
 /**
- * Represents an uploaded file parsed from the <uploaded_files> tag
+ * Represents a file stored in message additional_kwargs.files.
+ * Used for optimistic UI (uploading state) and structured file metadata.
  */
-export interface UploadedFile {
+export interface FileInMessage {
   filename: string;
-  size: string;
-  path: string;
+  size: number; // bytes
+  path?: string; // virtual path, may not be set during upload
+  status?: "uploading" | "uploaded";
 }
 
 /**
- * Result of parsing uploaded files from message content
+ * Strip <uploaded_files> tag from message content.
+ * Returns the content with the tag removed.
  */
-export interface ParsedUploadedFiles {
-  files: UploadedFile[];
-  cleanContent: string;
+export function stripUploadedFilesTag(content: string): string {
+  return content
+    .replace(/<uploaded_files>[\s\S]*?<\/uploaded_files>/g, "")
+    .trim();
 }
 
-/**
- * Parse <uploaded_files> tag from message content and extract file information.
- * Returns the list of uploaded files and the content with the tag removed.
- */
-export function parseUploadedFiles(content: string): ParsedUploadedFiles {
+export function parseUploadedFiles(content: string): FileInMessage[] {
   // Match <uploaded_files>...</uploaded_files> tag
   const uploadedFilesRegex = /<uploaded_files>([\s\S]*?)<\/uploaded_files>/;
   // eslint-disable-next-line @typescript-eslint/prefer-regexp-exec
   const match = content.match(uploadedFilesRegex);
 
   if (!match) {
-    return { files: [], cleanContent: content };
+    return [];
   }
 
   const uploadedFilesContent = match[1];
-  const cleanContent = content.replace(uploadedFilesRegex, "").trim();
 
   // Check if it's "No files have been uploaded yet."
   if (uploadedFilesContent?.includes("No files have been uploaded yet.")) {
-    return { files: [], cleanContent };
+    return [];
   }
 
   // Parse file list
   // Format: - filename (size)\n  Path: /path/to/file
   const fileRegex = /- ([^\n(]+)\s*\(([^)]+)\)\s*\n\s*Path:\s*([^\n]+)/g;
-  const files: UploadedFile[] = [];
+  const files: FileInMessage[] = [];
   let fileMatch;
 
   while ((fileMatch = fileRegex.exec(uploadedFilesContent ?? "")) !== null) {
     files.push({
       filename: fileMatch[1].trim(),
-      size: fileMatch[2].trim(),
+      size: parseInt(fileMatch[2].trim(), 10) ?? 0,
       path: fileMatch[3].trim(),
     });
   }
 
-  return { files, cleanContent };
+  return files;
 }

frontend/src/core/threads/hooks.ts

@@ -1,15 +1,18 @@
-import type { AIMessage } from "@langchain/langgraph-sdk";
+import type { AIMessage, Message } from "@langchain/langgraph-sdk";
 import type { ThreadsClient } from "@langchain/langgraph-sdk/client";
 import { useStream } from "@langchain/langgraph-sdk/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 
 import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
 
 import { getAPIClient } from "../api";
+import { useI18n } from "../i18n/hooks";
+import type { FileInMessage } from "../messages/utils";
 import type { LocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
+import type { UploadedFileInfo } from "../uploads";
 import { uploadFiles } from "../uploads";
 
 import type { AgentThread, AgentThreadState } from "./types";
@@ -36,11 +39,14 @@ export function useThreadStream({
   onFinish,
   onToolEnd,
 }: ThreadStreamOptions) {
+  const { t } = useI18n();
   const [_threadId, setThreadId] = useState<string | null>(threadId ?? null);
+  const startedRef = useRef(false);
 
   useEffect(() => {
     if (_threadId && _threadId !== threadId) {
       setThreadId(threadId ?? null);
+      startedRef.current = false; // Reset for new thread
     }
   }, [threadId, _threadId]);
 
@@ -54,7 +60,10 @@ export function useThreadStream({
     fetchStateHistory: { limit: 1 },
     onCreated(meta) {
       setThreadId(meta.thread_id);
-      onStart?.(meta.thread_id);
+      if (!startedRef.current) {
+        onStart?.(meta.thread_id);
+        startedRef.current = true;
+      }
     },
     onLangChainEvent(event) {
       if (event.event === "on_tool_end") {
@@ -85,6 +94,21 @@ export function useThreadStream({
     },
   });
 
+  // Optimistic messages shown before the server stream responds
+  const [optimisticMessages, setOptimisticMessages] = useState<Message[]>([]);
+  // Track message count before sending so we know when server has responded
+  const prevMsgCountRef = useRef(thread.messages.length);
+
+  // Clear optimistic when server messages arrive (count increases)
+  useEffect(() => {
+    if (
+      optimisticMessages.length > 0 &&
+      thread.messages.length > prevMsgCountRef.current
+    ) {
+      setOptimisticMessages([]);
+    }
+  }, [thread.messages.length, optimisticMessages.length]);
+
   const sendMessage = useCallback(
     async (
       threadId: string,
@@ -93,98 +117,191 @@ export function useThreadStream({
     ) => {
       const text = message.text.trim();
 
-      // Upload files first if any
-      if (message.files && message.files.length > 0) {
-        try {
-          // Convert FileUIPart to File objects by fetching blob URLs
-          const filePromises = message.files.map(async (fileUIPart) => {
-            if (fileUIPart.url && fileUIPart.filename) {
-              try {
-                // Fetch the blob URL to get the file data
-                const response = await fetch(fileUIPart.url);
-                const blob = await response.blob();
+      // Capture current count before showing optimistic messages
+      prevMsgCountRef.current = thread.messages.length;
 
-                // Create a File object from the blob
-                return new File([blob], fileUIPart.filename, {
-                  type: fileUIPart.mediaType || blob.type,
-                });
-              } catch (error) {
-                console.error(
-                  `Failed to fetch file ${fileUIPart.filename}:`,
-                  error,
-                );
-                return null;
-              }
-            }
-            return null;
-          });
+      // Build optimistic files list with uploading status
+      const optimisticFiles: FileInMessage[] = (message.files ?? []).map(
+        (f) => ({
+          filename: f.filename ?? "",
+          size: 0,
+          status: "uploading" as const,
+        }),
+      );
 
-          const conversionResults = await Promise.all(filePromises);
-          const files = conversionResults.filter(
-            (file): file is File => file !== null,
-          );
-          const failedConversions = conversionResults.length - files.length;
+      // Create optimistic human message (shown immediately)
+      const optimisticHumanMsg: Message = {
+        type: "human",
+        id: `opt-human-${Date.now()}`,
+        content: text ? [{ type: "text", text }] : "",
+        additional_kwargs:
+          optimisticFiles.length > 0 ? { files: optimisticFiles } : {},
+      };
 
-          if (failedConversions > 0) {
-            throw new Error(
-              `Failed to prepare ${failedConversions} attachment(s) for upload. Please retry.`,
-            );
-          }
+      const newOptimistic: Message[] = [optimisticHumanMsg];
+      if (optimisticFiles.length > 0) {
+        // Mock AI message while files are being uploaded
+        newOptimistic.push({
+          type: "ai",
+          id: `opt-ai-${Date.now()}`,
+          content: t.uploads.uploadingFiles,
+          additional_kwargs: { element: "task" },
+        });
+      }
+      setOptimisticMessages(newOptimistic);
 
-          if (!threadId) {
-            throw new Error("Thread is not ready for file upload.");
-          }
-
-          if (files.length > 0) {
-            await uploadFiles(threadId, files);
-          }
-        } catch (error) {
-          console.error("Failed to upload files:", error);
-          const errorMessage =
-            error instanceof Error ? error.message : "Failed to upload files.";
-          toast.error(errorMessage);
-          throw error;
-        }
+      if (!startedRef.current) {
+        onStart?.(threadId);
+        startedRef.current = true;
       }
 
-      await thread.submit(
-        {
-          messages: [
-            {
-              type: "human",
-              content: [
-                {
-                  type: "text",
-                  text,
-                },
-              ],
+      let uploadedFileInfo: UploadedFileInfo[] = [];
+
+      try {
+        // Upload files first if any
+        if (message.files && message.files.length > 0) {
+          try {
+            // Convert FileUIPart to File objects by fetching blob URLs
+            const filePromises = message.files.map(async (fileUIPart) => {
+              if (fileUIPart.url && fileUIPart.filename) {
+                try {
+                  // Fetch the blob URL to get the file data
+                  const response = await fetch(fileUIPart.url);
+                  const blob = await response.blob();
+
+                  // Create a File object from the blob
+                  return new File([blob], fileUIPart.filename, {
+                    type: fileUIPart.mediaType || blob.type,
+                  });
+                } catch (error) {
+                  console.error(
+                    `Failed to fetch file ${fileUIPart.filename}:`,
+                    error,
+                  );
+                  return null;
+                }
+              }
+              return null;
+            });
+
+            const conversionResults = await Promise.all(filePromises);
+            const files = conversionResults.filter(
+              (file): file is File => file !== null,
+            );
+            const failedConversions = conversionResults.length - files.length;
+
+            if (failedConversions > 0) {
+              throw new Error(
+                `Failed to prepare ${failedConversions} attachment(s) for upload. Please retry.`,
+              );
+            }
+
+            if (!threadId) {
+              throw new Error("Thread is not ready for file upload.");
+            }
+
+            if (files.length > 0) {
+              const uploadResponse = await uploadFiles(threadId, files);
+              uploadedFileInfo = uploadResponse.files;
+
+              // Update optimistic human message with uploaded status + paths
+              const uploadedFiles: FileInMessage[] = uploadedFileInfo.map(
+                (info) => ({
+                  filename: info.filename,
+                  size: info.size,
+                  path: info.virtual_path,
+                  status: "uploaded" as const,
+                }),
+              );
+              setOptimisticMessages((messages) => {
+                if (messages.length > 1 && messages[0]) {
+                  const humanMessage: Message = messages[0];
+                  return [
+                    {
+                      ...humanMessage,
+                      additional_kwargs: { files: uploadedFiles },
+                    },
+                    ...messages.slice(1),
+                  ];
+                }
+                return messages;
+              });
+            }
+          } catch (error) {
+            console.error("Failed to upload files:", error);
+            const errorMessage =
+              error instanceof Error
+                ? error.message
+                : "Failed to upload files.";
+            toast.error(errorMessage);
+            setOptimisticMessages([]);
+            throw error;
+          }
+        }
+
+        // Build files metadata for submission (included in additional_kwargs)
+        const filesForSubmit: FileInMessage[] = uploadedFileInfo.map(
+          (info) => ({
+            filename: info.filename,
+            size: info.size,
+            path: info.virtual_path,
+            status: "uploaded" as const,
+          }),
+        );
+
+        await thread.submit(
+          {
+            messages: [
+              {
+                type: "human",
+                content: [
+                  {
+                    type: "text",
+                    text,
+                  },
+                ],
+                additional_kwargs:
+                  filesForSubmit.length > 0 ? { files: filesForSubmit } : {},
+              },
+            ],
+          },
+          {
+            threadId: threadId,
+            streamSubgraphs: true,
+            streamResumable: true,
+            streamMode: ["values", "messages-tuple", "custom"],
+            config: {
+              recursion_limit: 1000,
+            },
+            context: {
+              ...extraContext,
+              ...context,
+              thinking_enabled: context.mode !== "flash",
+              is_plan_mode: context.mode === "pro" || context.mode === "ultra",
+              subagent_enabled: context.mode === "ultra",
+              thread_id: threadId,
             },
-          ],
-        },
-        {
-          threadId: threadId,
-          streamSubgraphs: true,
-          streamResumable: true,
-          streamMode: ["values", "messages-tuple", "custom"],
-          config: {
-            recursion_limit: 1000,
           },
-          context: {
-            ...extraContext,
-            ...context,
-            thinking_enabled: context.mode !== "flash",
-            is_plan_mode: context.mode === "pro" || context.mode === "ultra",
-            subagent_enabled: context.mode === "ultra",
-            thread_id: threadId,
-          },
-        },
-      );
-      void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
-      // afterSubmit?.();
+        );
+        void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
+      } catch (error) {
+        setOptimisticMessages([]);
+        throw error;
+      }
     },
-    [thread, context, queryClient],
+    [thread, t.uploads.uploadingFiles, onStart, context, queryClient],
   );
-  return [thread, sendMessage] as const;
+
+  // Merge thread with optimistic messages for display
+  const mergedThread =
+    optimisticMessages.length > 0
+      ? ({
+          ...thread,
+          messages: [...thread.messages, ...optimisticMessages],
+        } as typeof thread)
+      : thread;
+
+  return [mergedThread, sendMessage] as const;
 }
 
 export function useThreads(