fix: improve agent tool call animations for smoother UI (#4069)

## Summary

- Stagger tool call appearances with a 150ms delay between each,
preventing multiple tools from popping into the DOM at once
- Add a height + opacity CSS animation so each tool smoothly expands
into place instead of causing a layout jump
- Collapse fast `tool_started`/`tool_finished` pairs in the queue so
tools that complete before rendering skip the "running" flash
- Fix `tool_finished` events failing to match their `tool_started`
message when the backend omits `tool_call_id` (`Date.now()` fallback
produced mismatched IDs)
- Clean up elapsed time display: "326ms" instead of "326.0ms", "1.2s"
for longer durations

---------

Signed-off-by: Milos Jovanovic <[email protected]>

Author: 0vertake

web_src/src/App.css

@@ -244,3 +244,18 @@
   color: transparent;
   animation: sp-ai-thinking-shimmer 1.4s linear infinite;
 }
+
+@keyframes sp-tool-enter {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.sp-tool-enter {
+  animation: sp-tool-enter 0.2s ease-out both;
+}

web_src/src/components/AiBuilderChatMessage.tsx

@@ -7,9 +7,10 @@ import { cn } from "../lib/utils";
 
 export type AiMessageProps = {
   message: AiBuilderMessage;
+  animate?: boolean;
 };
 
-export function AiMessage({ message }: AiMessageProps) {
+export function AiMessage({ message, animate }: AiMessageProps) {
   if (message.role === "assistant" && message.content.trim().length === 0) {
     return null;
   }
@@ -18,27 +19,24 @@ export function AiMessage({ message }: AiMessageProps) {
     case "user":
       return <UserMessage content={message.content} />;
     case "tool":
-      return <ToolMessage message={message} />;
+      return <ToolMessage message={message} animate={animate} />;
     case "assistant":
       return <AssistantMessage content={message.content} />;
     default:
       return null;
   }
 }
 
-function ToolMessage({ message }: { message: AiBuilderMessage }) {
+function ToolMessage({ message, animate }: { message: AiBuilderMessage; animate?: boolean }) {
   const isRunning = message.toolStatus === "running";
 
-  const className = cn(
-    "flex items-center gap-2 px-2 text-xs leading-relaxed text-gray-500",
-    isRunning ? "sp-ai-thinking" : "",
-  );
-
   return (
-    <div className="w-full">
-      <div className={className}>
+    <div className={cn("w-full", animate && "sp-tool-enter")}>
+      <div className="flex items-center gap-2 px-2 text-xs leading-relaxed text-gray-500">
         <Activity className="h-3 w-3 shrink-0 text-gray-400" aria-hidden="true" />
-        <span className="min-w-0 whitespace-pre-wrap break-words">{message.content}</span>
+        <span className={cn("min-w-0 whitespace-pre-wrap break-words", isRunning && "sp-ai-thinking")}>
+          {message.content}
+        </span>
       </div>
     </div>
   );

web_src/src/components/AiBuilderConversationMessageList.tsx

@@ -97,7 +97,7 @@ function buildAiConversationItems({
       if (showToolsInlineForLiveTurn) {
         for (let k = groupStart; k < j; k++) {
           const toolMessage = messages[k];
-          items.push(<AiMessage key={toolMessage.id} message={toolMessage} />);
+          items.push(<AiMessage key={toolMessage.id} message={toolMessage} animate />);
         }
       } else {
         const toolGroup = messages.slice(groupStart, j);

web_src/src/ui/BuildingBlocksSidebar/agentChatSupport.ts

@@ -3,6 +3,7 @@ import type { AiBuilderMessage, AiBuilderProposal } from "./agentChat";
 import { normalizeAiProposal } from "./agentChatProposal";
 
 type JsonObject = Record<string, unknown>;
+type ToolEvent = Extract<ChatStreamEvent, { type: "tool_started" | "tool_finished" }>;
 
 export type ChatStreamEvent =
   | { type: "run_started"; model?: string }
@@ -167,6 +168,36 @@ function createToolCallId(toolName: string, toolCallId?: string): string {
   return typeof toolCallId === "string" && toolCallId.trim().length > 0 ? toolCallId : `${toolName}-${Date.now()}`;
 }
 
+function collapseWithFinishedEvent(
+  event: ToolEvent,
+  pendingEvents: ToolEvent[],
+): { effectiveEvent: ToolEvent; wasCollapsed: boolean } {
+  if (event.type !== "tool_started") {
+    return { effectiveEvent: event, wasCollapsed: false };
+  }
+
+  const toolName = typeof event.tool_name === "string" ? event.tool_name : "unknown";
+  const hasExplicitCallId = typeof event.tool_call_id === "string" && event.tool_call_id.trim().length > 0;
+
+  const finishedIdx = pendingEvents.findIndex((e) => {
+    if (e.type !== "tool_finished") {
+      return false;
+    }
+    const eName = typeof e.tool_name === "string" ? e.tool_name : "unknown";
+    const eHasId = typeof e.tool_call_id === "string" && e.tool_call_id.trim().length > 0;
+    if (hasExplicitCallId || eHasId) {
+      return hasExplicitCallId && eHasId && e.tool_call_id === event.tool_call_id;
+    }
+    return eName === toolName;
+  });
+
+  if (finishedIdx >= 0) {
+    return { effectiveEvent: pendingEvents.splice(finishedIdx, 1)[0], wasCollapsed: true };
+  }
+
+  return { effectiveEvent: event, wasCollapsed: false };
+}
+
 function createAssistantStreamController({
   assistantMessageId,
   insertAiMessageBefore,
@@ -181,6 +212,9 @@ function createAssistantStreamController({
   let assistantContentSnapshot = "";
   let pendingRenderBuffer = "";
   let isRenderLoopRunning = false;
+  const pendingToolEvents: ToolEvent[] = [];
+  let isToolLoopRunning = false;
+  const flushedToolCallIds = new Set<string>();
 
   const flushPendingRenderBuffer = async () => {
     if (isRenderLoopRunning) {
@@ -214,36 +248,74 @@ function createAssistantStreamController({
     void flushPendingRenderBuffer();
   };
 
-  const upsertToolMessage = (event: Extract<ChatStreamEvent, { type: "tool_started" | "tool_finished" }>) => {
+  const applyToolEvent = (event: ToolEvent): boolean => {
     const toolName = typeof event.tool_name === "string" ? event.tool_name : "unknown";
+    const hasExplicitCallId = typeof event.tool_call_id === "string" && event.tool_call_id.trim().length > 0;
     const toolCallId = createToolCallId(toolName, event.tool_call_id);
     const toolLabel = typeof event.tool_label === "string" ? event.tool_label.trim() : "";
     const content = event.type === "tool_started" ? `${toolLabel}...` : toolLabel;
     const toolStatus = event.type === "tool_started" ? "running" : "completed";
 
+    const isAlreadyTracked = flushedToolCallIds.has(toolCallId);
+    const isNameBasedUpdate = !isAlreadyTracked && event.type === "tool_finished" && !hasExplicitCallId;
+    const isNewInsertion = !isAlreadyTracked && !isNameBasedUpdate;
+
+    flushedToolCallIds.add(toolCallId);
+
     setAiMessages((previous) => {
-      const existingIndex = previous.findIndex(
-        (message) => message.role === "tool" && message.toolCallId === toolCallId,
-      );
-      const nextMessage: AiBuilderMessage = {
-        id: existingIndex >= 0 ? previous[existingIndex].id : `tool-${toolCallId}`,
-        role: "tool",
-        content,
-        toolCallId,
-        toolStatus,
-      };
+      let existingIndex = previous.findIndex((message) => message.role === "tool" && message.toolCallId === toolCallId);
+
+      if (existingIndex < 0 && event.type === "tool_finished" && !hasExplicitCallId && toolLabel.length > 0) {
+        existingIndex = previous.findIndex(
+          (message) =>
+            message.role === "tool" && message.toolStatus === "running" && message.content.startsWith(toolLabel),
+        );
+      }
+
       if (existingIndex >= 0) {
         const updated = [...previous];
-        updated[existingIndex] = nextMessage;
+        updated[existingIndex] = { ...previous[existingIndex], content, toolStatus };
         return trimAiMessages(updated);
       }
 
-      return insertAiMessageBefore(previous, nextMessage, assistantMessageId);
+      return insertAiMessageBefore(
+        previous,
+        { id: `tool-${toolCallId}`, role: "tool", content, toolCallId, toolStatus },
+        assistantMessageId,
+      );
     });
+
+    return isNewInsertion;
+  };
+
+  const flushPendingToolEvents = async () => {
+    if (isToolLoopRunning) {
+      return;
+    }
+
+    isToolLoopRunning = true;
+    try {
+      while (pendingToolEvents.length > 0) {
+        const event = pendingToolEvents.shift()!;
+        const { effectiveEvent, wasCollapsed } = collapseWithFinishedEvent(event, pendingToolEvents);
+        const isNewInsertion = applyToolEvent(effectiveEvent);
+
+        if (isNewInsertion || wasCollapsed) {
+          await sleep(150);
+        }
+      }
+    } finally {
+      isToolLoopRunning = false;
+    }
+  };
+
+  const upsertToolMessage = (event: ToolEvent) => {
+    pendingToolEvents.push(event);
+    void flushPendingToolEvents();
   };
 
   const waitForRenderLoopIdle = async () => {
-    while (isRenderLoopRunning || pendingRenderBuffer.length > 0) {
+    while (isRenderLoopRunning || pendingRenderBuffer.length > 0 || isToolLoopRunning || pendingToolEvents.length > 0) {
       await sleep(10);
     }
   };