@runtypelabs/persona 3.10.1 → 3.11.0

package/src/components/tool-bubble.ts

@@ -1,11 +1,12 @@
 import { createElement } from "../utils/dom";
 import { AgentWidgetMessage, AgentWidgetConfig } from "../types";
-import { formatUnknownValue, describeToolTitle } from "../utils/formatting";
+import { formatUnknownValue, describeToolTitle, resolveToolHeaderText, computeToolElapsed, parseFormattedTemplate } from "../utils/formatting";
 import { renderLucideIcon } from "../utils/icons";
 
 // Expansion state per widget instance
 export const toolExpansionState = new Set<string>();
 
+
 const appendRenderedValue = (
   container: HTMLElement,
   value: HTMLElement | string | null | undefined
@@ -59,6 +60,7 @@ const getToolSummaryText = (
   }
 
   const isActive = tool.status !== "complete";
+  const toolCallConfig = config?.toolCall ?? {};
   let summary = defaultSummary;
   if (collapsedMode === "tool-name") {
     summary = tool.name?.trim() || defaultSummary;
@@ -66,6 +68,13 @@ const getToolSummaryText = (
     summary = previewText;
   }
 
+  // Apply text templates if configured
+  if (isActive && toolCallConfig.activeTextTemplate) {
+    summary = resolveToolHeaderText(tool, toolCallConfig.activeTextTemplate, summary);
+  } else if (!isActive && toolCallConfig.completeTextTemplate) {
+    summary = resolveToolHeaderText(tool, toolCallConfig.completeTextTemplate, summary);
+  }
+
   return { summary, previewText, isActive };
 };
 
@@ -151,6 +160,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   const expandable = toolDisplayConfig.expandable !== false;
   let expanded = expandable && toolExpansionState.has(message.id);
   const { summary, previewText, isActive } = getToolSummaryText(message, config);
+
   const header = createElement(
     "button",
     expandable
@@ -182,6 +192,18 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   if (toolCallConfig.headerTextColor) {
     title.style.color = toolCallConfig.headerTextColor;
   }
+
+  // Elapsed helpers — defined early so they're available to renderCollapsedSummary
+  const startedAt = String(tool.startedAt ?? Date.now());
+
+  // Helper: build a <span data-tool-elapsed> that the global timer in ui.ts updates
+  const createElapsedSpan = (): HTMLElement => {
+    const span = createElement("span", "");
+    span.setAttribute("data-tool-elapsed", startedAt);
+    span.textContent = computeToolElapsed(tool);
+    return span;
+  };
+
   const customSummary = toolCallConfig.renderCollapsedSummary?.({
     message,
     toolCall: tool,
@@ -190,6 +212,8 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     collapsedMode: toolDisplayConfig.collapsedMode ?? "tool-call",
     isActive,
     config: config ?? {},
+    elapsed: computeToolElapsed(tool),
+    createElapsedElement: createElapsedSpan,
   });
   if (typeof customSummary === "string" && customSummary.trim()) {
     title.textContent = customSummary;
@@ -201,6 +225,102 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     headerContent.appendChild(title);
   }
 
+  // Apply loading animation when tool is active and no custom HTMLElement was provided
+  const loadingAnimation = toolDisplayConfig.loadingAnimation ?? "none";
+  const activeTemplate = toolCallConfig.activeTextTemplate;
+  const completeTemplate = toolCallConfig.completeTextTemplate;
+  const currentTemplate = isActive ? activeTemplate : completeTemplate;
+  const skipCustomElement = customSummary instanceof HTMLElement;
+
+  // Helper: append text as individual animated character spans
+  const appendCharSpans = (container: HTMLElement, text: string, startIndex: number): number => {
+    let idx = startIndex;
+    for (const char of text) {
+      const span = createElement("span", "persona-tool-char");
+      span.style.setProperty("--char-index", String(idx));
+      span.textContent = char === " " ? "\u00A0" : char;
+      container.appendChild(span);
+      idx++;
+    }
+    return idx;
+  };
+
+  /**
+   * Renders a template into the title element, handling:
+   * - Inline formatting markers: **bold**, *italic*, ~dim~
+   * - {duration} as a live-updating elapsed span (active) or static text (complete)
+   * - Character-by-character animation wrapping when `animated` is true
+   */
+  const renderFormattedTitle = (template: string, animated: boolean) => {
+    title.textContent = "";
+    const toolName = tool.name?.trim() || "tool";
+    const segments = parseFormattedTemplate(template, toolName);
+    let charIndex = 0;
+
+    for (const seg of segments) {
+      // Determine parent: wrap in a styled span if formatting is present
+      const parent = seg.styles.length > 0
+        ? (() => {
+            const w = createElement("span", seg.styles.map(s => `persona-tool-text-${s}`).join(" "));
+            title.appendChild(w);
+            return w;
+          })()
+        : title;
+
+      if (seg.isDuration && isActive) {
+        // Live-updating elapsed span for active tools
+        parent.appendChild(createElapsedSpan());
+      } else {
+        // Static text (or resolved duration for completed tools)
+        const text = seg.isDuration ? computeToolElapsed(tool) : seg.text;
+        if (animated) {
+          charIndex = appendCharSpans(parent, text, charIndex);
+        } else {
+          parent.appendChild(document.createTextNode(text));
+        }
+      }
+    }
+  };
+
+  if (!skipCustomElement) {
+    if (isActive && loadingAnimation !== "none") {
+      const animDuration = toolCallConfig.loadingAnimationDuration ?? 2000;
+      title.setAttribute("data-preserve-animation", "true");
+
+      if (loadingAnimation === "pulse") {
+        title.classList.add("persona-tool-loading-pulse");
+        title.style.setProperty("--persona-tool-anim-duration", `${animDuration}ms`);
+        if (currentTemplate) {
+          renderFormattedTitle(currentTemplate, false);
+        }
+      } else {
+        // Character-by-character modes: shimmer, shimmer-color, rainbow
+        title.classList.add(`persona-tool-loading-${loadingAnimation}`);
+        title.style.setProperty("--persona-tool-anim-duration", `${animDuration}ms`);
+
+        if (loadingAnimation === "shimmer-color") {
+          if (toolCallConfig.loadingAnimationColor) {
+            title.style.setProperty("--persona-tool-anim-color", toolCallConfig.loadingAnimationColor);
+          }
+          if (toolCallConfig.loadingAnimationSecondaryColor) {
+            title.style.setProperty("--persona-tool-anim-secondary-color", toolCallConfig.loadingAnimationSecondaryColor);
+          }
+        }
+
+        if (currentTemplate) {
+          renderFormattedTitle(currentTemplate, true);
+        } else {
+          const text = title.textContent || summary;
+          title.textContent = "";
+          appendCharSpans(title, text, 0);
+        }
+      }
+    } else if (currentTemplate) {
+      // Template with formatting but no animation (or completed tool)
+      renderFormattedTitle(currentTemplate, false);
+    }
+  }
+
   let toggleIcon: HTMLElement | null = null;
   if (expandable) {
     toggleIcon = createElement("div", "persona-flex persona-items-center");

package/src/defaults.ts

@@ -123,6 +123,7 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       grouped: false,
       previewMaxLines: 3,
       expandable: true,
+      loadingAnimation: "none",
     },
     reasoningDisplay: {
       activePreview: false,

package/src/styles/widget.css

@@ -1220,6 +1220,86 @@
   box-shadow: var(--persona-tool-bubble-shadow, 0 5px 15px rgba(15, 23, 42, 0.08));
 }
 
+/* ==============================
+   Tool call loading animations
+   ============================== */
+
+/* Inline formatting classes for template text */
+[data-persona-root] .persona-tool-text-dim {
+  opacity: 0.5;
+}
+[data-persona-root] .persona-tool-text-bold {
+  font-weight: 600;
+}
+[data-persona-root] .persona-tool-text-italic {
+  font-style: italic;
+}
+
+/* Pulse mode: entire text element pulses opacity */
+@keyframes persona-tool-loading-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+[data-persona-root] .persona-tool-loading-pulse {
+  animation: persona-tool-loading-pulse var(--persona-tool-anim-duration, 2s) ease-in-out infinite;
+}
+
+/* Shimmer mode: monochrome brightness sweep per character */
+@keyframes persona-tool-loading-shimmer {
+  0%, 100% { opacity: 0.4; }
+  50% { opacity: 1; }
+}
+
+[data-persona-root] .persona-tool-loading-shimmer .persona-tool-char {
+  display: inline-block;
+  animation: persona-tool-loading-shimmer var(--persona-tool-anim-duration, 2s) ease-in-out infinite;
+  animation-delay: calc(var(--char-index, 0) * 60ms);
+}
+
+/* Shimmer-color mode: color gradient sweep per character */
+@keyframes persona-tool-loading-shimmer-color {
+  0%, 100% {
+    color: var(--persona-tool-anim-color, currentColor);
+  }
+  50% {
+    color: var(--persona-tool-anim-secondary-color, #3b82f6);
+  }
+}
+
+[data-persona-root] .persona-tool-loading-shimmer-color .persona-tool-char {
+  display: inline-block;
+  animation: persona-tool-loading-shimmer-color var(--persona-tool-anim-duration, 2s) ease-in-out infinite;
+  animation-delay: calc(var(--char-index, 0) * 60ms);
+}
+
+/* Rainbow mode: hue rotation per character */
+@keyframes persona-tool-loading-rainbow {
+  0% { color: #ef4444; }
+  16% { color: #f59e0b; }
+  33% { color: #22c55e; }
+  50% { color: #06b6d4; }
+  66% { color: #3b82f6; }
+  83% { color: #8b5cf6; }
+  100% { color: #ef4444; }
+}
+
+[data-persona-root] .persona-tool-loading-rainbow .persona-tool-char {
+  display: inline-block;
+  animation: persona-tool-loading-rainbow var(--persona-tool-anim-duration, 2s) linear infinite;
+  animation-delay: calc(var(--char-index, 0) * 80ms);
+}
+
+/* Prefers-reduced-motion: disable all tool loading animations */
+@media (prefers-reduced-motion: reduce) {
+  [data-persona-root] .persona-tool-loading-pulse,
+  [data-persona-root] .persona-tool-loading-shimmer .persona-tool-char,
+  [data-persona-root] .persona-tool-loading-shimmer-color .persona-tool-char,
+  [data-persona-root] .persona-tool-loading-rainbow .persona-tool-char {
+    animation: none !important;
+  }
+}
+
 [data-persona-root] .persona-reasoning-bubble.persona-shadow-sm {
   box-shadow: var(--persona-reasoning-bubble-shadow, 0 5px 15px rgba(15, 23, 42, 0.08));
 }

package/src/theme-reference.ts

@@ -210,9 +210,12 @@ export const THEME_TOKEN_DOCS = {
         'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only). Defaults: enabled=true, iconName="arrow-down", label="".',
     },
     toolCall: {
-      description: 'Tool call display styling and collapsed/grouped rendering hooks.',
+      description:
+        'Tool call display styling, text templates, loading animations, and rendering hooks. ' +
+        'Text templates support placeholders ({toolName}, {duration}) and inline formatting (~dim~, *italic*, **bold**). ' +
+        'renderCollapsedSummary receives elapsed (static string) and createElapsedElement() (live-updating span) in its context.',
       properties:
-        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor, renderCollapsedSummary, renderCollapsedPreview, renderGroupedSummary.',
+        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor, activeTextTemplate, completeTextTemplate, loadingAnimationColor, loadingAnimationSecondaryColor, loadingAnimationDuration, renderCollapsedSummary, renderCollapsedPreview, renderGroupedSummary.',
     },
     reasoning: {
       description: 'Reasoning/thinking row rendering hooks.',
@@ -282,7 +285,7 @@ export const THEME_TOKEN_DOCS = {
     features: {
       description: 'Feature flags.',
       properties:
-        'showReasoning (AI thinking steps), showToolCalls (tool invocations), toolCallDisplay (collapsedMode, activePreview, activeMinHeight, previewMaxLines, grouped), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines), artifacts (sidebar config).',
+        'showReasoning (AI thinking steps), showToolCalls (tool invocations), toolCallDisplay (collapsedMode, activePreview, activeMinHeight, previewMaxLines, grouped, expandable, loadingAnimation), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines, expandable), artifacts (sidebar config).',
     },
   },
 }

package/src/tool-call-display-defaults.test.ts

@@ -10,6 +10,7 @@ describe("tool call display defaults", () => {
       grouped: false,
       previewMaxLines: 3,
       expandable: true,
+      loadingAnimation: "none",
     });
   });
 

package/src/types.ts

@@ -577,6 +577,19 @@ export type AgentWidgetToolCallCollapsedMode =
   | "tool-name"
   | "tool-preview";
 
+/**
+ * Animation mode applied to tool call header text while the tool is running.
+ * Character-by-character modes (`shimmer`, `shimmer-color`, `rainbow`) wrap each
+ * character in a span with staggered `animation-delay`. `pulse` applies to the
+ * entire text container. Honors `prefers-reduced-motion`.
+ */
+export type AgentWidgetToolCallLoadingAnimation =
+  | "none"
+  | "pulse"
+  | "shimmer"
+  | "shimmer-color"
+  | "rainbow";
+
 export type AgentWidgetToolCallDisplayFeature = {
   /**
    * Controls what collapsed tool call rows show in their header/summary area.
@@ -590,6 +603,8 @@ export type AgentWidgetToolCallDisplayFeature = {
   activePreview?: boolean;
   /**
    * Optional CSS min-height applied to active collapsed tool call rows.
+   * @default undefined (no min-height)
+   * @example "100px"
    */
   activeMinHeight?: string;
   /**
@@ -608,6 +623,16 @@ export type AgentWidgetToolCallDisplayFeature = {
    * @default true
    */
   expandable?: boolean;
+  /**
+   * Animation mode applied to the tool call header text while the tool is active.
+   * - "none" — static text, no animation
+   * - "pulse" — opacity pulse on the entire header text
+   * - "shimmer" — monochrome opacity sweep per character
+   * - "shimmer-color" — color gradient sweep per character
+   * - "rainbow" — rainbow color cycle per character
+   * @default "none"
+   */
+  loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
 export type AgentWidgetReasoningDisplayFeature = {
@@ -1234,22 +1259,39 @@ export type AgentWidgetApprovalConfig = {
 export type AgentWidgetToolCallConfig = {
   /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
   shadow?: string;
+  /** Background color of the tool call bubble container. */
   backgroundColor?: string;
+  /** Border color of the tool call bubble container. */
   borderColor?: string;
+  /** Border width of the tool call bubble container (CSS value, e.g. `"1px"`). */
   borderWidth?: string;
+  /** Border radius of the tool call bubble container (CSS value, e.g. `"12px"`). */
   borderRadius?: string;
+  /** Background color of the collapsed header row. */
   headerBackgroundColor?: string;
+  /** Text color of the collapsed header row (tool name / summary). */
   headerTextColor?: string;
+  /** Horizontal padding of the collapsed header row (CSS value). */
   headerPaddingX?: string;
+  /** Vertical padding of the collapsed header row (CSS value). */
   headerPaddingY?: string;
+  /** Background color of the expanded content area. */
   contentBackgroundColor?: string;
+  /** Text color of the expanded content area. */
   contentTextColor?: string;
+  /** Horizontal padding of the expanded content area (CSS value). */
   contentPaddingX?: string;
+  /** Vertical padding of the expanded content area (CSS value). */
   contentPaddingY?: string;
+  /** Background color of code blocks (arguments / result) in the expanded area. */
   codeBlockBackgroundColor?: string;
+  /** Border color of code blocks in the expanded area. */
   codeBlockBorderColor?: string;
+  /** Text color of code blocks in the expanded area. */
   codeBlockTextColor?: string;
+  /** Color of the expand/collapse toggle icon. */
   toggleTextColor?: string;
+  /** Color of section labels ("Arguments", "Result", "Activity") in the expanded area. */
   labelTextColor?: string;
   /**
    * Override the collapsed summary row content for a tool call bubble.
@@ -1263,6 +1305,14 @@ export type AgentWidgetToolCallConfig = {
     collapsedMode: AgentWidgetToolCallCollapsedMode;
     isActive: boolean;
     config: AgentWidgetConfig;
+    /** Static elapsed time snapshot, e.g. "2.6s". */
+    elapsed: string;
+    /**
+     * Returns a `<span>` whose text content is automatically updated every
+     * 100ms by the widget's global timer. Place it anywhere in your returned
+     * HTMLElement to get a live-ticking duration display.
+     */
+    createElapsedElement: () => HTMLElement;
   }) => HTMLElement | string | null;
   /**
    * Override the lightweight collapsed preview content shown for active tool rows.
@@ -1285,6 +1335,47 @@ export type AgentWidgetToolCallConfig = {
     defaultSummary: string;
     config: AgentWidgetConfig;
   }) => HTMLElement | string | null;
+  /**
+   * Template string for the header text while a tool call is active (running).
+   *
+   * **Placeholders:** `{toolName}` (tool name), `{duration}` (live-updating elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — parsed at render time and
+   * applied as styled `<span>` elements. Works with all animation modes.
+   *
+   * When not set, falls back to the current `collapsedMode` behavior.
+   * @example "Calling {toolName}... ~{duration}~"
+   * @example "**Searching** *{toolName}*..."
+   */
+  activeTextTemplate?: string;
+  /**
+   * Template string for the header text when a tool call is complete.
+   *
+   * **Placeholders:** `{toolName}` (tool name), `{duration}` (final elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — same syntax as `activeTextTemplate`.
+   *
+   * When not set, falls back to the existing "Used tool for X seconds" text.
+   * @example "Finished {toolName} ~{duration}~"
+   */
+  completeTextTemplate?: string;
+  /**
+   * Primary color for shimmer-color animation mode.
+   * Defaults to the current text color.
+   */
+  loadingAnimationColor?: string;
+  /**
+   * Secondary/end color for shimmer-color animation mode.
+   * Creates a gradient sweep between `loadingAnimationColor` and this color.
+   * @default "#3b82f6"
+   */
+  loadingAnimationSecondaryColor?: string;
+  /**
+   * Duration of one full animation cycle in milliseconds.
+   * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
+   * @default 2000
+   */
+  loadingAnimationDuration?: number;
 };
 
 export type AgentWidgetReasoningConfig = {

package/src/ui.scroll.test.ts

@@ -34,6 +34,16 @@ const installRafMock = () => {
   });
 
   return {
+    step(frameCount = 1) {
+      let frames = 0;
+      while (callbacks.size > 0 && frames < frameCount) {
+        const pending = [...callbacks.entries()];
+        callbacks.clear();
+        frames += 1;
+        now += 16;
+        pending.forEach(([, callback]) => callback(now));
+      }
+    },
     flush(maxFrames = 80) {
       let frames = 0;
       while (callbacks.size > 0 && frames < maxFrames) {
@@ -215,14 +225,14 @@ describe("createAgentExperience streaming scroll", () => {
 
     expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
 
-    metrics.setScrollTop(metrics.getBottomScrollTop() - 3);
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 6);
     scrollContainer!.dispatchEvent(new Event("scroll"));
 
     metrics.setScrollHeight(1040);
     emitStreamingMessage(controller, "Second chunk");
     raf.flush();
 
-    expect(metrics.getScrollTop()).toBe(597);
+    expect(metrics.getScrollTop()).toBe(594);
 
     controller.destroy();
   });
@@ -364,6 +374,39 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("catches up immediately when a streamed update lands far behind", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 900,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "Chunk one");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollHeight(1080);
+    emitStreamingMessage(controller, "Chunk two");
+
+    // Only run the scheduled auto-scroll frame, not the whole animation.
+    raf.step(1);
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
   it("lets the user break away during reasoning streaming", () => {
     const raf = installRafMock();
     const mount = createMount();

package/src/ui.ts

@@ -54,6 +54,7 @@ import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } fr
 import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
+import { formatElapsedMs } from "./utils/formatting";
 import { createApprovalBubble } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
@@ -1989,8 +1990,13 @@ export const createAgentExperience = (
   let isAutoScrolling = false;
   let hasPendingAutoScroll = false;
 
-  const USER_SCROLL_THRESHOLD = 1;
-  const BOTTOM_THRESHOLD = 8;
+  // Scroll events caused by layout, scroll anchoring, and smooth-scroll
+  // easing can easily move by a couple pixels. Keep manual wheel intent
+  // responsive, but require a slightly larger raw scroll delta before we
+  // treat a plain scroll event as the user breaking away.
+  const USER_SCROLL_THRESHOLD = 4;
+  const BOTTOM_THRESHOLD = 24;
+  const AUTO_SCROLL_SNAP_THRESHOLD = 80;
   const messageState = new Map<
     string,
     { streaming?: boolean; role: AgentWidgetMessage["role"] }
@@ -2177,6 +2183,18 @@ export const createAgentExperience = (
       return;
     }
 
+    // If the transcript has fallen noticeably behind, catch up immediately
+    // instead of easing over multiple frames. This keeps fast streaming /
+    // bursty tool and reasoning updates pinned to the bottom.
+    if (Math.abs(distance) >= AUTO_SCROLL_SNAP_THRESHOLD) {
+      cancelSmoothScroll();
+      isAutoScrolling = true;
+      element.scrollTop = target;
+      lastScrollTop = element.scrollTop;
+      isAutoScrolling = false;
+      return;
+    }
+
     // Cancel any ongoing smooth scroll animation
     cancelSmoothScroll();
 
@@ -2960,9 +2978,33 @@ export const createAgentExperience = (
     };
   }
 
+  // Global timer for live-updating tool elapsed time spans.
+  // Runs at 100ms while any [data-tool-elapsed] span exists in the message area,
+  // auto-stops when none remain. Operates on real DOM after morph, not temp elements.
+  let toolElapsedTimerId: ReturnType<typeof setInterval> | null = null;
+  const ensureToolElapsedTimer = () => {
+    if (toolElapsedTimerId != null) return;
+    toolElapsedTimerId = setInterval(() => {
+      const spans = messagesWrapper.querySelectorAll<HTMLElement>("[data-tool-elapsed]");
+      if (spans.length === 0) {
+        clearInterval(toolElapsedTimerId!);
+        toolElapsedTimerId = null;
+        return;
+      }
+      const now = Date.now();
+      spans.forEach((span) => {
+        const startedAt = Number(span.getAttribute("data-tool-elapsed"));
+        if (!startedAt) return;
+        span.textContent = formatElapsedMs(now - startedAt);
+      });
+    }, 100);
+  };
+
   session = new AgentWidgetSession(config, {
     onMessagesChanged(messages) {
       renderMessagesWithPlugins(messagesWrapper, messages, postprocess);
+      // Start elapsed timer if any active tool has a live duration span
+      ensureToolElapsedTimer();
       // Re-render suggestions to hide them after first user message
       // Pass messages directly to avoid calling session.getMessages() during construction
       if (session) {
@@ -5716,6 +5758,10 @@ export const createAgentExperience = (
       return session.submitNPSFeedback(rating, comment);
     },
     destroy() {
+      if (toolElapsedTimerId != null) {
+        clearInterval(toolElapsedTimerId);
+        toolElapsedTimerId = null;
+      }
       destroyCallbacks.forEach((cb) => cb());
       wrapper.remove();
       launcherButtonInstance?.destroy();