Add tool call observability

2026-07-14 08:26:07 +00:00 · 2026-07-02 15:52:46 +08:00
parent b1bc05d5d3
commit c809e3d14f
19 changed files with 1351 additions and 65 deletions
@@ -191,45 +191,47 @@ export default function BotDetailContent({ id }: { id: string }) {
          onValueChange={setActiveTab}
          className="flex flex-1 flex-col min-h-0"
        >
-          <TabsList className="shrink-0">
-            <TabsTrigger value="config" className="gap-1.5">
-              <Settings className="size-3.5" />
-              {t('bots.configuration')}
-            </TabsTrigger>
-            <TabsTrigger value="logs" className="gap-1.5">
-              <FileText className="size-3.5" />
-              {t('bots.logs')}
-            </TabsTrigger>
-            <TabsTrigger value="sessions" className="gap-1.5">
-              <Users className="size-3.5" />
-              {t('bots.sessionMonitor.title')}
-              {activeTab === 'sessions' && (
-                <button
-                  type="button"
-                  className="inline-flex items-center justify-center ml-0.5"
-                  onPointerDown={(e) => e.stopPropagation()}
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    e.preventDefault();
-                    if (isRefreshingSessions) return;
-                    setIsRefreshingSessions(true);
-                    const minDelay = new Promise((r) => setTimeout(r, 500));
-                    Promise.all([
-                      sessionMonitorRef.current?.refreshSessions(),
-                      minDelay,
-                    ]).finally(() => setIsRefreshingSessions(false));
-                  }}
-                >
-                  <RefreshCw
-                    className={cn(
-                      'size-3 text-muted-foreground hover:text-foreground transition-colors',
-                      isRefreshingSessions && 'animate-spin',
-                    )}
-                  />
-                </button>
-              )}
-            </TabsTrigger>
-          </TabsList>
+          <div className="flex shrink-0 items-center gap-1">
+            <TabsList>
+              <TabsTrigger value="config" className="gap-1.5">
+                <Settings className="size-3.5" />
+                {t('bots.configuration')}
+              </TabsTrigger>
+              <TabsTrigger value="logs" className="gap-1.5">
+                <FileText className="size-3.5" />
+                {t('bots.logs')}
+              </TabsTrigger>
+              <TabsTrigger value="sessions" className="gap-1.5">
+                <Users className="size-3.5" />
+                {t('bots.sessionMonitor.title')}
+              </TabsTrigger>
+            </TabsList>
+            {activeTab === 'sessions' && (
+              <button
+                type="button"
+                aria-label={t('bots.sessionMonitor.refresh')}
+                title={t('bots.sessionMonitor.refresh')}
+                className="inline-flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-50"
+                disabled={isRefreshingSessions}
+                onClick={() => {
+                  if (isRefreshingSessions) return;
+                  setIsRefreshingSessions(true);
+                  const minDelay = new Promise((r) => setTimeout(r, 500));
+                  Promise.all([
+                    sessionMonitorRef.current?.refreshSessions(),
+                    minDelay,
+                  ]).finally(() => setIsRefreshingSessions(false));
+                }}
+              >
+                <RefreshCw
+                  className={cn(
+                    'size-3.5',
+                    isRefreshingSessions && 'animate-spin',
+                  )}
+                />
+              </button>
+            )}
+          </div>

          {/* Tab: Configuration */}
          <TabsContent
@@ -3,6 +3,7 @@ import React, {
  useEffect,
  useRef,
  useCallback,
+  useMemo,
  forwardRef,
  useImperativeHandle,
 } from 'react';
@@ -15,11 +16,14 @@ import {
  Bot,
  Copy,
  Check,
+  ChevronDown,
+  ChevronRight,
  Workflow,
  ThumbsUp,
  ThumbsDown,
  ShieldCheck,
  ShieldOff,
+  Wrench,
 } from 'lucide-react';
 import { toast } from 'sonner';
 import BotAdminsDialog, {
@@ -76,6 +80,35 @@ interface SessionFeedback {
  stream_id?: string | null;
 }

+interface SessionToolCall {
+  id: string;
+  timestamp: string;
+  tool_name: string;
+  tool_source: string;
+  duration: number;
+  status: string;
+  message_id?: string | null;
+  arguments?: string | null;
+  result?: string | null;
+  error_message?: string | null;
+}
+
+type SessionTimelineItem =
+  | {
+      id: string;
+      type: 'message';
+      timestamp: number;
+      order: number;
+      message: SessionMessage;
+    }
+  | {
+      id: string;
+      type: 'tool';
+      timestamp: number;
+      order: number;
+      toolCall: SessionToolCall;
+    };
+
 export interface BotSessionMonitorHandle {
  refreshSessions: () => Promise<void>;
 }
@@ -100,6 +133,10 @@ const BotSessionMonitor = forwardRef<
  const [feedbackMap, setFeedbackMap] = useState<
    Record<string, SessionFeedback>
  >({});
+  const [toolCalls, setToolCalls] = useState<SessionToolCall[]>([]);
+  const [expandedToolCallIds, setExpandedToolCallIds] = useState<
+    Record<string, boolean>
+  >({});
  const messagesContainerRef = useRef<HTMLDivElement>(null);
  const { admins, reload: reloadAdmins } = useBotAdmins(botId);
  const [adminsDialogOpen, setAdminsDialogOpen] = useState(false);
@@ -189,6 +226,7 @@ const BotSessionMonitor = forwardRef<
  const loadMessages = useCallback(
    async (sessionId: string) => {
      setLoadingMessages(true);
+      setExpandedToolCallIds({});
      try {
        const messagesRes = await httpClient.getSessionMessages(sessionId);
        const sorted = (messagesRes.messages ?? []).sort(
@@ -197,6 +235,18 @@ const BotSessionMonitor = forwardRef<
        );
        setMessages(sorted);

+        try {
+          const analysisRes = await httpClient.get<{
+            tool_calls?: SessionToolCall[];
+          }>(
+            `/api/v1/monitoring/sessions/${encodeURIComponent(sessionId)}/analysis`,
+          );
+          setToolCalls(analysisRes?.tool_calls ?? []);
+        } catch (analysisError) {
+          console.error('Failed to load session tool calls:', analysisError);
+          setToolCalls([]);
+        }
+
        // Collect user message IDs for feedback matching
        const userMsgIds = new Set(
          sorted.filter((m) => !m.role || m.role === 'user').map((m) => m.id),
@@ -240,11 +290,14 @@ const BotSessionMonitor = forwardRef<
      loadMessages(selectedSessionId);
    } else {
      setMessages([]);
+      setToolCalls([]);
+      setExpandedToolCallIds({});
+      setFeedbackMap({});
    }
  }, [selectedSessionId, loadMessages]);

  useEffect(() => {
-    if (messages.length === 0) return;
+    if (messages.length === 0 && toolCalls.length === 0) return;
    // Wait for DOM to render the new messages before scrolling
    requestAnimationFrame(() => {
      const container = messagesContainerRef.current;
@@ -256,7 +309,7 @@ const BotSessionMonitor = forwardRef<
        scrollTarget.scrollTop = scrollTarget.scrollHeight;
      }
    });
-  }, [messages]);
+  }, [messages, toolCalls]);

  const parseMessageChain = (content: string): MessageChainComponent[] => {
    try {
@@ -431,6 +484,69 @@ const BotSessionMonitor = forwardRef<
    return `${diffDays}d`;
  };

+  const formatDuration = (durationMs: number): string => {
+    if (!durationMs) return '0ms';
+    if (durationMs < 1000) return `${durationMs}ms`;
+    return `${(durationMs / 1000).toFixed(2)}s`;
+  };
+
+  const truncateToolDetail = (value?: string | null): string => {
+    if (!value) return '';
+    return value.length > 600 ? `${value.slice(0, 600)}...` : value;
+  };
+
+  const toggleToolCallDetails = (toolCallId: string) => {
+    setExpandedToolCallIds((previous) => ({
+      ...previous,
+      [toolCallId]: !previous[toolCallId],
+    }));
+  };
+
+  const feedbackByMessageId = useMemo(() => {
+    const map: Record<string, SessionFeedback> = {};
+
+    for (let index = 0; index < messages.length; index++) {
+      const msg = messages[index];
+      if (isUserMessage(msg)) continue;
+
+      for (let previousIndex = index - 1; previousIndex >= 0; previousIndex--) {
+        const previousMessage = messages[previousIndex];
+        if (isUserMessage(previousMessage)) {
+          const feedback = feedbackMap[previousMessage.id];
+          if (feedback) {
+            map[msg.id] = feedback;
+          }
+          break;
+        }
+      }
+    }
+
+    return map;
+  }, [feedbackMap, messages]);
+
+  const timelineItems = useMemo<SessionTimelineItem[]>(() => {
+    const messageItems: SessionTimelineItem[] = messages.map(
+      (message, index) => ({
+        id: `message-${message.id}`,
+        type: 'message',
+        timestamp: parseTimestamp(message.timestamp).getTime(),
+        order: index * 2,
+        message,
+      }),
+    );
+    const toolItems: SessionTimelineItem[] = toolCalls.map((toolCall, index) => ({
+      id: `tool-${toolCall.id}`,
+      type: 'tool',
+      timestamp: parseTimestamp(toolCall.timestamp).getTime(),
+      order: index * 2 + 1,
+      toolCall,
+    }));
+
+    return [...messageItems, ...toolItems].sort(
+      (a, b) => a.timestamp - b.timestamp || a.order - b.order,
+    );
+  }, [messages, toolCalls]);
+
  const selectedSession = sessions.find(
    (s) => s.session_id === selectedSessionId,
  );
@@ -612,29 +728,164 @@ const BotSessionMonitor = forwardRef<
                    <div className="text-center text-muted-foreground py-12 text-sm">
                      {t('bots.sessionMonitor.loading')}
                    </div>
-                  ) : messages.length === 0 ? (
+                  ) : timelineItems.length === 0 ? (
                    <div className="text-center text-muted-foreground py-12 text-sm">
                      {t('bots.sessionMonitor.noMessages')}
                    </div>
                  ) : (
-                    messages.map((msg, msgIndex) => {
+                    timelineItems.map((item) => {
+                      if (item.type === 'tool') {
+                        const call = item.toolCall;
+                        const hasToolDetails = Boolean(
+                          call.arguments || call.result || call.error_message,
+                        );
+                        const expandedToolCall = Boolean(
+                          expandedToolCallIds[call.id],
+                        );
+                        const detailsId = `tool-call-details-${call.id}`;
+                        return (
+                          <div key={item.id} className="flex justify-start">
+                            <div className="max-w-3xl rounded-2xl rounded-bl-sm border bg-muted px-3 py-2 text-sm">
+                              <button
+                                type="button"
+                                className={cn(
+                                  'flex w-full items-start justify-between gap-3 rounded-lg text-left outline-none transition-colors',
+                                  hasToolDetails &&
+                                    'cursor-pointer hover:bg-background/50 focus-visible:ring-2 focus-visible:ring-ring',
+                                )}
+                                aria-expanded={
+                                  hasToolDetails ? expandedToolCall : undefined
+                                }
+                                aria-controls={
+                                  hasToolDetails ? detailsId : undefined
+                                }
+                                aria-disabled={!hasToolDetails}
+                                onClick={() =>
+                                  hasToolDetails &&
+                                  toggleToolCallDetails(call.id)
+                                }
+                              >
+                                <div className="flex min-w-0 flex-wrap items-center gap-1.5">
+                                  {hasToolDetails &&
+                                    (expandedToolCall ? (
+                                      <ChevronDown className="mt-0.5 h-3.5 w-3.5 text-muted-foreground" />
+                                    ) : (
+                                      <ChevronRight className="mt-0.5 h-3.5 w-3.5 text-muted-foreground" />
+                                    ))}
+                                  <Wrench className="mt-0.5 h-3.5 w-3.5 text-muted-foreground" />
+                                  <span className="min-w-0 max-w-[18rem] truncate font-medium text-foreground">
+                                    {call.tool_name}
+                                  </span>
+                                  <span className="rounded bg-background px-1.5 py-0.5 text-[11px] text-muted-foreground">
+                                    {call.tool_source}
+                                  </span>
+                                  <span
+                                    className={cn(
+                                      'rounded px-1.5 py-0.5 text-[11px] font-medium',
+                                      call.status === 'success'
+                                        ? 'bg-green-100 text-green-700 dark:bg-green-950 dark:text-green-300'
+                                        : 'bg-red-100 text-red-700 dark:bg-red-950 dark:text-red-300',
+                                    )}
+                                  >
+                                    {call.status}
+                                  </span>
+                                </div>
+                                <span className="shrink-0 text-[11px] tabular-nums text-muted-foreground">
+                                  {formatDuration(call.duration)}
+                                </span>
+                              </button>
+
+                              {hasToolDetails && expandedToolCall && (
+                                <div
+                                  id={detailsId}
+                                  className="mt-2 space-y-1.5"
+                                >
+                                  {(call.arguments || call.result) && (
+                                    <div className="space-y-1.5">
+                                      {call.arguments && (
+                                        <div>
+                                          <div className="mb-1 text-[11px] font-medium text-muted-foreground">
+                                            {t(
+                                              'monitoring.toolCalls.arguments',
+                                              {
+                                                defaultValue: '参数',
+                                              },
+                                            )}
+                                          </div>
+                                          <pre className="whitespace-pre-wrap break-words rounded bg-background/80 p-2 font-mono text-[11px] leading-4 text-muted-foreground">
+                                            {truncateToolDetail(
+                                              call.arguments,
+                                            )}
+                                          </pre>
+                                        </div>
+                                      )}
+                                      {call.result && (
+                                        <div>
+                                          <div className="mb-1 text-[11px] font-medium text-muted-foreground">
+                                            {t('monitoring.toolCalls.result', {
+                                              defaultValue: '结果',
+                                            })}
+                                          </div>
+                                          <pre className="whitespace-pre-wrap break-words rounded bg-background/80 p-2 font-mono text-[11px] leading-4 text-muted-foreground">
+                                            {truncateToolDetail(call.result)}
+                                          </pre>
+                                        </div>
+                                      )}
+                                    </div>
+                                  )}
+
+                                  {call.error_message && (
+                                    <div className="whitespace-pre-wrap break-words rounded bg-red-50 p-2 text-[11px] text-red-600 dark:bg-red-950/40 dark:text-red-400">
+                                      {call.error_message}
+                                    </div>
+                                  )}
+                                </div>
+                              )}
+
+                              <div className="mt-1.5 flex items-center gap-1.5 text-[11px] text-muted-foreground">
+                                <span>
+                                  {t('monitoring.toolCalls.title', {
+                                    defaultValue: '工具调用',
+                                  })}
+                                </span>
+                                <span className="tabular-nums">
+                                  {formatTime(call.timestamp)}
+                                </span>
+                                {hasToolDetails && (
+                                  <>
+                                    <span>·</span>
+                                    <span>
+                                      {expandedToolCall
+                                        ? t(
+                                            'monitoring.toolCalls.hideDetails',
+                                            {
+                                              defaultValue: '隐藏详情',
+                                            },
+                                          )
+                                        : t(
+                                            'monitoring.toolCalls.showDetails',
+                                            {
+                                              defaultValue: '查看详情',
+                                            },
+                                          )}
+                                    </span>
+                                  </>
+                                )}
+                              </div>
+                            </div>
+                          </div>
+                        );
+                      }
+
+                      const msg = item.message;
                      const isUser = isUserMessage(msg);
                      const isDiscarded =
                        msg.status === 'discarded' ||
                        msg.pipeline_id === PIPELINE_DISCARD;
-                      // For bot replies, find feedback linked to the preceding user message
-                      let msgFeedback: SessionFeedback | undefined;
-                      if (!isUser) {
-                        for (let i = msgIndex - 1; i >= 0; i--) {
-                          if (isUserMessage(messages[i])) {
-                            msgFeedback = feedbackMap[messages[i].id];
-                            break;
-                          }
-                        }
-                      }
+                      const msgFeedback = feedbackByMessageId[msg.id];
                      return (
                        <div
-                          key={msg.id}
+                          key={item.id}
                          className={cn(
                            'flex',
                            isUser ? 'justify-end' : 'justify-start',
@@ -9,6 +9,7 @@ import {
  Cpu,
  Hash,
  User,
+  Wrench,
 } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { MessageContentRenderer } from './MessageContentRenderer';
@@ -36,6 +37,11 @@ function formatDuration(ms: number) {
  return `${(ms / 1000).toFixed(2)}s`;
 }

+function truncateDetail(value?: string) {
+  if (!value) return '';
+  return value.length > 1200 ? `${value.slice(0, 1200)}...` : value;
+}
+
 function roleLabel(message: MonitoringMessage | undefined) {
  const role = message?.role?.toLowerCase();
  if (role === 'assistant') return 'assistant';
@@ -147,6 +153,16 @@ export function ConversationTurnList({
  onToggleTurn,
 }: ConversationTurnListProps) {
  const { t } = useTranslation();
+  const [expandedToolCallIds, setExpandedToolCallIds] = React.useState<
+    Record<string, boolean>
+  >({});
+
+  const toggleToolCallDetails = (toolCallKey: string) => {
+    setExpandedToolCallIds((previous) => ({
+      ...previous,
+      [toolCallKey]: !previous[toolCallKey],
+    }));
+  };

  return (
    <div className="space-y-4">
@@ -268,6 +284,12 @@ export function ConversationTurnList({
                      icon={<Cpu className="h-3.5 w-3.5" />}
                      label={`${turn.llmCalls.length} LLM`}
                    />
+                    {turn.toolCalls.length > 0 && (
+                      <Metric
+                        icon={<Wrench className="h-3.5 w-3.5" />}
+                        label={`${turn.toolCalls.length} tools`}
+                      />
+                    )}
                    <Metric
                      icon={<Hash className="h-3.5 w-3.5" />}
                      label={`${turn.totalTokens.toLocaleString()} tokens`}
@@ -434,6 +456,157 @@ export function ConversationTurnList({
                    </div>
                  </section>

+                  <section>
+                    <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold text-foreground">
+                      <Wrench className="h-4 w-4" />
+                      {t('monitoring.toolCalls.title', {
+                        defaultValue: '工具调用',
+                      })}{' '}
+                      ({turn.toolCalls.length})
+                    </h4>
+
+                    <div className="grid grid-cols-2 gap-2 lg:grid-cols-3">
+                      <MetaItem
+                        label={t('monitoring.toolCalls.totalCalls', {
+                          defaultValue: '调用次数',
+                        })}
+                        value={String(turn.toolCalls.length)}
+                      />
+                      <MetaItem
+                        label={t('monitoring.toolCalls.duration', {
+                          defaultValue: '工具耗时',
+                        })}
+                        value={formatDuration(turn.totalToolDuration)}
+                      />
+                      <MetaItem
+                        label={t('monitoring.toolCalls.errorCalls', {
+                          defaultValue: '失败次数',
+                        })}
+                        value={String(
+                          turn.toolCalls.filter(
+                            (call) => call.status === 'error',
+                          ).length,
+                        )}
+                      />
+                    </div>
+
+                    <div className="mt-3 rounded-lg bg-background px-3 py-3">
+                      {turn.toolCalls.length > 0 ? (
+                        turn.toolCalls.map((call, index) => {
+                          const toolCallKey = `${turn.id}:${call.id}`;
+                          const hasToolDetails = Boolean(
+                            call.arguments || call.result || call.errorMessage,
+                          );
+                          const expandedToolCall = Boolean(
+                            expandedToolCallIds[toolCallKey],
+                          );
+                          const detailsId = `monitoring-tool-call-details-${call.id}`;
+
+                          return (
+                            <div
+                              key={call.id}
+                              className="border-t border-border/70 py-2 first:border-t-0 first:pt-0 last:pb-0"
+                            >
+                              <button
+                                type="button"
+                                className={cn(
+                                  'flex w-full items-start justify-between gap-3 rounded-md px-2 py-2 text-left outline-none transition-colors',
+                                  hasToolDetails &&
+                                    'cursor-pointer hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-ring',
+                                )}
+                                aria-expanded={
+                                  hasToolDetails ? expandedToolCall : undefined
+                                }
+                                aria-controls={
+                                  hasToolDetails ? detailsId : undefined
+                                }
+                                aria-disabled={!hasToolDetails}
+                                onClick={() =>
+                                  hasToolDetails &&
+                                  toggleToolCallDetails(toolCallKey)
+                                }
+                              >
+                                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                                  {hasToolDetails &&
+                                    (expandedToolCall ? (
+                                      <ChevronDown className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+                                    ) : (
+                                      <ChevronRight className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+                                    ))}
+                                  <span className="min-w-0 truncate text-sm font-medium text-foreground">
+                                    #{index + 1} {call.toolName}
+                                  </span>
+                                  <span className="rounded-md bg-muted px-2 py-1 text-xs font-medium text-muted-foreground">
+                                    {call.toolSource}
+                                  </span>
+                                  <span
+                                    className={cn(
+                                      'rounded-md px-2 py-1 text-xs font-medium',
+                                      call.status === 'success'
+                                        ? 'bg-green-100 text-green-700 dark:bg-green-950 dark:text-green-300'
+                                        : 'bg-red-100 text-red-700 dark:bg-red-950 dark:text-red-300',
+                                    )}
+                                  >
+                                    {call.status}
+                                  </span>
+                                  <span className="font-mono text-xs text-muted-foreground">
+                                    ID: {shortId(call.id)}
+                                  </span>
+                                </div>
+                                <span className="shrink-0 text-xs text-muted-foreground">
+                                  {formatDuration(call.duration)}
+                                </span>
+                              </button>
+
+                              {hasToolDetails && expandedToolCall && (
+                                <div
+                                  id={detailsId}
+                                  className="mt-1 grid gap-2 px-2 pb-2 text-xs lg:grid-cols-2"
+                                >
+                                  {call.arguments && (
+                                    <div className="min-w-0 rounded-md bg-muted/50 p-2">
+                                      <div className="mb-1 font-medium text-foreground">
+                                        {t('monitoring.toolCalls.arguments', {
+                                          defaultValue: '参数',
+                                        })}
+                                      </div>
+                                      <pre className="whitespace-pre-wrap break-words font-mono text-muted-foreground">
+                                        {truncateDetail(call.arguments)}
+                                      </pre>
+                                    </div>
+                                  )}
+                                  {call.result && (
+                                    <div className="min-w-0 rounded-md bg-muted/50 p-2">
+                                      <div className="mb-1 font-medium text-foreground">
+                                        {t('monitoring.toolCalls.result', {
+                                          defaultValue: '结果',
+                                        })}
+                                      </div>
+                                      <pre className="whitespace-pre-wrap break-words font-mono text-muted-foreground">
+                                        {truncateDetail(call.result)}
+                                      </pre>
+                                    </div>
+                                  )}
+                                  {call.errorMessage && (
+                                    <div className="min-w-0 whitespace-pre-wrap break-words rounded-md bg-red-50 p-2 text-red-600 dark:bg-red-950/40 dark:text-red-400 lg:col-span-2">
+                                      {call.errorMessage}
+                                    </div>
+                                  )}
+                                </div>
+                              )}
+                            </div>
+                          );
+                        })
+                      ) : (
+                        <div className="py-4 text-center text-sm text-muted-foreground">
+                          {t('monitoring.toolCalls.noToolCalls', {
+                            defaultValue: '未记录工具调用',
+                          })}
+                        </div>
+                      )}
+                    </div>
+                  </section>
+
                  {turn.errors.length > 0 && (
                    <section>
                      <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold text-red-700 dark:text-red-300">
@@ -106,6 +106,9 @@ export function useMonitoringData(filterState: FilterState) {
      const llmCalls = Array.isArray(response?.llmCalls)
        ? response.llmCalls
        : [];
+      const toolCalls = Array.isArray(response?.toolCalls)
+        ? response.toolCalls
+        : [];
      const embeddingCalls = Array.isArray(response?.embeddingCalls)
        ? response.embeddingCalls
        : [];
@@ -116,6 +119,7 @@ export function useMonitoringData(filterState: FilterState) {
      const totalCount = response?.totalCount ?? {
        messages: messages.length,
        llmCalls: llmCalls.length,
+        toolCalls: toolCalls.length,
        embeddingCalls: embeddingCalls.length,
        sessions: sessions.length,
        errors: errors.length,
@@ -207,6 +211,41 @@ export function useMonitoringData(filterState: FilterState) {
            messageId: call.message_id,
          }),
        ),
+        toolCalls: toolCalls.map(
+          (call: {
+            id: string;
+            timestamp: string;
+            tool_name: string;
+            tool_source: string;
+            duration: number;
+            status: string;
+            bot_id: string;
+            bot_name: string;
+            pipeline_id: string;
+            pipeline_name: string;
+            session_id?: string;
+            message_id?: string;
+            arguments?: string;
+            result?: string;
+            error_message?: string;
+          }) => ({
+            id: call.id,
+            timestamp: parseUTCTimestamp(call.timestamp),
+            toolName: call.tool_name,
+            toolSource: call.tool_source,
+            duration: call.duration,
+            status: call.status as 'success' | 'error',
+            botId: call.bot_id,
+            botName: call.bot_name,
+            pipelineId: call.pipeline_id,
+            pipelineName: call.pipeline_name,
+            sessionId: call.session_id,
+            messageId: call.message_id,
+            arguments: call.arguments,
+            result: call.result,
+            errorMessage: call.error_message,
+          }),
+        ),
        embeddingCalls: embeddingCalls.map(
          (call: {
            id: string;
@@ -300,6 +339,7 @@ export function useMonitoringData(filterState: FilterState) {
        totalCount: {
          messages: totalCount.messages,
          llmCalls: totalCount.llmCalls,
+          toolCalls: totalCount.toolCalls ?? toolCalls.length,
          embeddingCalls: totalCount.embeddingCalls || 0,
          sessions: totalCount.sessions,
          errors: totalCount.errors,
@@ -104,8 +104,9 @@ function MonitoringPageContent() {
        data?.messages || [],
        data?.llmCalls || [],
        data?.errors || [],
+        data?.toolCalls || [],
      ),
-    [data?.messages, data?.llmCalls, data?.errors],
+    [data?.messages, data?.llmCalls, data?.errors, data?.toolCalls],
  );

  // State for expanded errors
@@ -38,6 +38,24 @@ export interface LLMCall {
  messageId?: string;
 }

+export interface ToolCall {
+  id: string;
+  timestamp: Date;
+  toolName: string;
+  toolSource: 'native' | 'plugin' | 'mcp' | 'skill' | string;
+  duration: number;
+  status: 'success' | 'error';
+  botId: string;
+  botName: string;
+  pipelineId: string;
+  pipelineName: string;
+  sessionId?: string;
+  messageId?: string;
+  arguments?: string;
+  result?: string;
+  errorMessage?: string;
+}
+
 export interface EmbeddingCall {
  id: string;
  timestamp: Date;
@@ -202,6 +220,7 @@ export interface MonitoringData {
  overview: OverviewMetrics;
  messages: MonitoringMessage[];
  llmCalls: LLMCall[];
+  toolCalls: ToolCall[];
  embeddingCalls: EmbeddingCall[];
  modelCalls: ModelCall[];
  sessions: SessionInfo[];
@@ -211,6 +230,7 @@ export interface MonitoringData {
  totalCount: {
    messages: number;
    llmCalls: number;
+    toolCalls?: number;
    embeddingCalls: number;
    sessions: number;
    errors: number;
@@ -1,4 +1,9 @@
-import { ErrorLog, LLMCall, MonitoringMessage } from '../types/monitoring';
+import {
+  ErrorLog,
+  LLMCall,
+  MonitoringMessage,
+  ToolCall,
+} from '../types/monitoring';

 type MessageRole = 'user' | 'assistant' | 'unknown';

@@ -19,6 +24,7 @@ export interface ConversationTurn {
  assistantMessages: MonitoringMessage[];
  messages: MonitoringMessage[];
  llmCalls: LLMCall[];
+  toolCalls: ToolCall[];
  errors: ErrorLog[];
  status: 'success' | 'error' | 'pending';
  level: 'info' | 'warning' | 'error' | 'debug';
@@ -26,6 +32,7 @@ export interface ConversationTurn {
  outputTokens: number;
  totalTokens: number;
  totalDuration: number;
+  totalToolDuration: number;
 }

 function normalizeRole(
@@ -91,6 +98,7 @@ function createTurn(message: MonitoringMessage): ConversationTurn {
    assistantMessages: [],
    messages: [],
    llmCalls: [],
+    toolCalls: [],
    errors: [],
    status: message.status,
    level: message.level,
@@ -98,6 +106,7 @@ function createTurn(message: MonitoringMessage): ConversationTurn {
    outputTokens: 0,
    totalTokens: 0,
    totalDuration: 0,
+    totalToolDuration: 0,
  };
 }

@@ -174,12 +183,16 @@ export function buildConversationTurns(
  messages: MonitoringMessage[],
  llmCalls: LLMCall[],
  errors: ErrorLog[],
+  toolCalls: ToolCall[] = [],
 ): ConversationTurn[] {
-  const llmMessageIds = new Set(
-    llmCalls
+  const activityMessageIds = new Set([
+    ...llmCalls
      .map((call) => call.messageId)
      .filter((messageId): messageId is string => Boolean(messageId)),
-  );
+    ...toolCalls
+      .map((call) => call.messageId)
+      .filter((messageId): messageId is string => Boolean(messageId)),
+  ]);
  const visibleMessages = messages
    .filter((message) => hasRenderableMessageContent(message.messageContent))
    .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
@@ -189,7 +202,7 @@ export function buildConversationTurns(
  const messageIdToTurn = new Map<string, ConversationTurn>();

  for (const message of visibleMessages) {
-    const role = normalizeRole(message, llmMessageIds);
+    const role = normalizeRole(message, activityMessageIds);
    const previousTurn = lastTurnBySession.get(message.sessionId);
    const shouldStartTurn = role === 'user' || !previousTurn;
    const turn = shouldStartTurn ? createTurn(message) : previousTurn;
@@ -229,6 +242,25 @@ export function buildConversationTurns(
    }
  }

+  for (const call of toolCalls) {
+    const turn =
+      (call.messageId ? messageIdToTurn.get(call.messageId) : undefined) ??
+      findTurnBySessionTime(sessionTurns, call.sessionId, call.timestamp);
+
+    if (!turn) {
+      continue;
+    }
+
+    turn.toolCalls.push(call);
+    turn.totalToolDuration += call.duration;
+    updateTurnActivity(turn, call.timestamp);
+
+    if (call.status === 'error') {
+      turn.status = 'error';
+      turn.level = 'error';
+    }
+  }
+
  for (const error of errors) {
    const turn =
      (error.messageId ? messageIdToTurn.get(error.messageId) : undefined) ??
@@ -250,6 +282,9 @@ export function buildConversationTurns(
      (a, b) => a.timestamp.getTime() - b.timestamp.getTime(),
    );
    turn.llmCalls.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    turn.toolCalls.sort(
+      (a, b) => a.timestamp.getTime() - b.timestamp.getTime(),
+    );
    turn.errors.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
  }

@@ -1199,8 +1199,10 @@ export class BackendClient extends BaseHttpClient {
      level: string;
      platform?: string;
      user_id?: string;
+      user_name?: string;
      runner_name?: string;
      variables?: string;
+      role?: string;
    }>;
    llmCalls: Array<{
      id: string;
@@ -1216,9 +1218,27 @@ export class BackendClient extends BaseHttpClient {
      bot_name: string;
      pipeline_id: string;
      pipeline_name: string;
+      session_id?: string;
      error_message?: string;
      message_id?: string;
    }>;
+    toolCalls: Array<{
+      id: string;
+      timestamp: string;
+      tool_name: string;
+      tool_source: string;
+      duration: number;
+      status: string;
+      bot_id: string;
+      bot_name: string;
+      pipeline_id: string;
+      pipeline_name: string;
+      session_id?: string;
+      message_id?: string;
+      arguments?: string;
+      result?: string;
+      error_message?: string;
+    }>;
    embeddingCalls: Array<{
      id: string;
      timestamp: string;
@@ -1263,6 +1283,7 @@ export class BackendClient extends BaseHttpClient {
    totalCount: {
      messages: number;
      llmCalls: number;
+      toolCalls?: number;
      embeddingCalls: number;
      sessions: number;
      errors: number;
@@ -1357,6 +1357,15 @@ const enUS = {
      avgDuration: 'Avg Duration',
      calls: 'Calls',
    },
+    toolCalls: {
+      title: 'Tool Calls',
+      totalCalls: 'Calls',
+      duration: 'Tool Duration',
+      errorCalls: 'Failed Calls',
+      arguments: 'Arguments',
+      result: 'Result',
+      noToolCalls: 'No tool calls recorded',
+    },
    tokens: {
      totalTokens: 'Total Tokens',
      inputTokens: 'Input Tokens',
@@ -1294,6 +1294,15 @@ const zhHans = {
      avgDuration: '平均耗时',
      calls: '调用次数',
    },
+    toolCalls: {
+      title: '工具调用',
+      totalCalls: '调用次数',
+      duration: '工具耗时',
+      errorCalls: '失败次数',
+      arguments: '参数',
+      result: '结果',
+      noToolCalls: '未记录工具调用',
+    },
    tokens: {
      totalTokens: '总 Token 数',
      inputTokens: '输入 Token',
@@ -0,0 +1,179 @@
+import { expect, test } from '@playwright/test';
+
+import { installLangBotApiMocks } from './fixtures/langbot-api';
+
+const botId = 'bot-tool-timeline';
+const sessionId = 'person-tool-timeline-user';
+const botName = 'Tool Timeline Bot';
+const pipelineId = 'pipeline-tool-timeline';
+const pipelineName = 'Tool Timeline Pipeline';
+
+function at(minute: number, second = 0) {
+  return `2026-07-02T10:${String(minute).padStart(2, '0')}:${String(
+    second,
+  ).padStart(2, '0')}Z`;
+}
+
+function sessionMessage(
+  id: string,
+  role: 'user' | 'assistant',
+  minute: number,
+  content: string,
+) {
+  return {
+    id,
+    timestamp: at(minute),
+    bot_id: botId,
+    bot_name: botName,
+    pipeline_id: pipelineId,
+    pipeline_name: pipelineName,
+    message_content: content,
+    session_id: sessionId,
+    status: 'success',
+    level: 'info',
+    platform: role === 'user' ? 'person' : 'bot',
+    user_id: 'timeline-user',
+    user_name: 'Timeline User',
+    runner_name: role === 'assistant' ? 'local-agent' : null,
+    variables: '{}',
+    role,
+  };
+}
+
+function toolCall(
+  id: string,
+  minute: number,
+  toolName: string,
+  duration: number,
+  status: 'success' | 'error' = 'success',
+) {
+  return {
+    id,
+    timestamp: at(minute, 30),
+    tool_name: toolName,
+    tool_source: 'native',
+    duration,
+    status,
+    bot_id: botId,
+    bot_name: botName,
+    pipeline_id: pipelineId,
+    pipeline_name: pipelineName,
+    session_id: sessionId,
+    message_id: 'user-message',
+    arguments: JSON.stringify({ target: toolName }),
+    result: status === 'success' ? JSON.stringify({ ok: true }) : null,
+    error_message: status === 'error' ? 'Tool execution failed' : null,
+  };
+}
+
+test.describe('bot session monitor tool timeline', () => {
+  test('renders tool calls as left-side agent events interleaved with messages', async ({
+    page,
+  }) => {
+    await installLangBotApiMocks(page, {
+      authenticated: true,
+      monitoringSessions: [
+        {
+          session_id: sessionId,
+          bot_id: botId,
+          bot_name: botName,
+          pipeline_id: pipelineId,
+          pipeline_name: pipelineName,
+          message_count: 3,
+          start_time: at(0),
+          last_activity: at(4),
+          is_active: true,
+          platform: 'person',
+          user_id: 'timeline-user',
+          user_name: 'Timeline User',
+        },
+      ],
+      sessionMessages: {
+        [sessionId]: [
+          sessionMessage('user-message', 'user', 0, 'Need a timeline check'),
+          sessionMessage(
+            'assistant-step-1',
+            'assistant',
+            2,
+            'Agent step 1: inspected repository files',
+          ),
+          sessionMessage(
+            'assistant-step-2',
+            'assistant',
+            4,
+            'Agent step 2: test suite finished',
+          ),
+        ],
+      },
+      sessionAnalyses: {
+        [sessionId]: {
+          session_id: sessionId,
+          found: true,
+          tool_calls: [
+            toolCall('tool-repo-read', 1, 'repo_file_read', 80),
+            toolCall('tool-test-run', 3, 'run_test_suite', 140),
+          ],
+        },
+      },
+    });
+
+    await page.goto(`/home/bots?id=${botId}`);
+    await page.getByRole('tab', { name: /Sessions/ }).click();
+    await page.getByRole('button', { name: /Timeline User/ }).click();
+
+    await expect(page.getByText('Need a timeline check')).toBeVisible();
+    await expect(
+      page.getByText('repo_file_read', { exact: true }),
+    ).toBeVisible();
+    await expect(
+      page.getByText('Agent step 1: inspected repository files'),
+    ).toBeVisible();
+    await expect(
+      page.getByText('run_test_suite', { exact: true }),
+    ).toBeVisible();
+    await expect(
+      page.getByText('Agent step 2: test suite finished'),
+    ).toBeVisible();
+    await expect(page.getByText('{"target":"repo_file_read"}')).toHaveCount(0);
+    await expect(page.getByText('{"ok":true}')).toHaveCount(0);
+
+    await expect(
+      page.locator('div.flex.justify-start').filter({
+        hasText: 'repo_file_read',
+      }),
+    ).toHaveCount(1);
+    await expect(
+      page.locator('div.flex.justify-start').filter({
+        hasText: 'run_test_suite',
+      }),
+    ).toHaveCount(1);
+    await expect(
+      page.locator('div.flex.justify-end').filter({
+        hasText: 'repo_file_read',
+      }),
+    ).toHaveCount(0);
+    await expect(
+      page.locator('div.flex.justify-end').filter({
+        hasText: 'run_test_suite',
+      }),
+    ).toHaveCount(0);
+
+    const text = await page.locator('body').innerText();
+    expect(text.indexOf('Need a timeline check')).toBeLessThan(
+      text.indexOf('repo_file_read'),
+    );
+    expect(text.indexOf('repo_file_read')).toBeLessThan(
+      text.indexOf('Agent step 1: inspected repository files'),
+    );
+    expect(
+      text.indexOf('Agent step 1: inspected repository files'),
+    ).toBeLessThan(text.indexOf('run_test_suite'));
+    expect(text.indexOf('run_test_suite')).toBeLessThan(
+      text.indexOf('Agent step 2: test suite finished'),
+    );
+
+    await page.getByText('repo_file_read', { exact: true }).click();
+    await expect(page.getByText('{"target":"repo_file_read"}')).toBeVisible();
+    await expect(page.getByText('{"ok":true}').first()).toBeVisible();
+  });
+});
@@ -73,7 +73,10 @@ interface LangBotApiMockState {
  knowledgeBases: KnowledgeBaseMock[];
  mcpServers: MCPServerMock[];
  monitoringData: unknown;
+  monitoringSessions: unknown[];
  pipelines: PipelineMock[];
+  sessionAnalyses: Record<string, unknown>;
+  sessionMessages: Record<string, unknown[]>;
  skills: SkillMock[];
 }

@@ -123,12 +126,14 @@ function emptyMonitoringData() {
    },
    messages: [],
    llmCalls: [],
+    toolCalls: [],
    embeddingCalls: [],
    sessions: [],
    errors: [],
    totalCount: {
      messages: 0,
      llmCalls: 0,
+      toolCalls: 0,
      embeddingCalls: 0,
      sessions: 0,
      errors: 0,
@@ -693,6 +698,37 @@ async function handleBackendApi(route: Route, state: LangBotApiMockState) {
    return fulfillJson(route, state.monitoringData);
  }

+  if (path === '/api/v1/monitoring/sessions') {
+    return fulfillJson(route, {
+      sessions: state.monitoringSessions,
+      total: state.monitoringSessions.length,
+    });
+  }
+
+  if (path === '/api/v1/monitoring/messages') {
+    const sessionId = url.searchParams.get('sessionId') || '';
+    const messages = state.sessionMessages[sessionId] || [];
+    return fulfillJson(route, {
+      messages,
+      total: messages.length,
+    });
+  }
+
+  const sessionAnalysisMatch = path.match(
+    /^\/api\/v1\/monitoring\/sessions\/([^/]+)\/analysis$/,
+  );
+  if (sessionAnalysisMatch) {
+    const sessionId = decodeURIComponent(sessionAnalysisMatch[1]);
+    return fulfillJson(
+      route,
+      state.sessionAnalyses[sessionId] || {
+        session_id: sessionId,
+        found: true,
+        tool_calls: [],
+      },
+    );
+  }
+
  if (path === '/api/v1/monitoring/overview') {
    const data = state.monitoringData as { overview?: unknown };
    return fulfillJson(route, data.overview || emptyMonitoringData().overview);
@@ -803,17 +839,30 @@ export async function installLangBotApiMocks(
  options: {
    authenticated?: boolean;
    monitoringData?: unknown;
+    monitoringSessions?: unknown[];
+    sessionAnalyses?: Record<string, unknown>;
+    sessionMessages?: Record<string, unknown[]>;
    storage?: JsonRecord;
  } = {},
 ) {
-  const { authenticated = false, monitoringData, storage = {} } = options;
+  const {
+    authenticated = false,
+    monitoringData,
+    monitoringSessions,
+    sessionAnalyses,
+    sessionMessages,
+    storage = {},
+  } = options;
  const state: LangBotApiMockState = {
    bots: [],
    counters: {},
    knowledgeBases: [],
    mcpServers: [],
    monitoringData: monitoringData || emptyMonitoringData(),
+    monitoringSessions: monitoringSessions || [],
    pipelines: [],
+    sessionAnalyses: sessionAnalyses || {},
+    sessionMessages: sessionMessages || {},
    skills: [],
  };

@@ -6,6 +6,7 @@ import {
  ErrorLog,
  LLMCall,
  MonitoringMessage,
+  ToolCall,
 } from '../../src/app/home/monitoring/types/monitoring';

 const bot = {
@@ -93,6 +94,34 @@ function errorLog(id: string, minute: number, messageId: string): ErrorLog {
  };
 }

+function toolCall(
+  id: string,
+  minute: number,
+  messageId: string | undefined,
+  toolName: string,
+  duration: number,
+  sessionId = 'session-agent',
+  status: 'success' | 'error' = 'success',
+): ToolCall {
+  return {
+    id,
+    timestamp: time(minute),
+    toolName,
+    toolSource: 'native',
+    duration,
+    status,
+    botId: bot.id,
+    botName: bot.name,
+    pipelineId: pipeline.id,
+    pipelineName: pipeline.name,
+    sessionId,
+    messageId,
+    arguments: JSON.stringify({ query: toolName }),
+    result: status === 'success' ? JSON.stringify({ ok: true }) : undefined,
+    errorMessage: status === 'error' ? 'Tool failed' : undefined,
+  };
+}
+
 function rawMessage(message: MonitoringMessage) {
  return {
    id: message.id,
@@ -151,6 +180,26 @@ function rawError(error: ErrorLog) {
  };
 }

+function rawToolCall(call: ToolCall) {
+  return {
+    id: call.id,
+    timestamp: call.timestamp.toISOString(),
+    tool_name: call.toolName,
+    tool_source: call.toolSource,
+    duration: call.duration,
+    status: call.status,
+    bot_id: call.botId,
+    bot_name: call.botName,
+    pipeline_id: call.pipelineId,
+    pipeline_name: call.pipelineName,
+    session_id: call.sessionId,
+    message_id: call.messageId,
+    arguments: call.arguments,
+    result: call.result,
+    error_message: call.errorMessage,
+  };
+}
+
 function monitoringScenario() {
  const messages = [
    message(
@@ -179,10 +228,16 @@ function monitoringScenario() {
    llmCall('agent-call-4', 20, 'agent-user-2', 50, 25, 80),
  ];
  const errors = [errorLog('agent-error-1', 12, 'agent-user-1')];
+  const toolCalls = [
+    toolCall('agent-tool-1', 11, 'agent-user-1', 'repo_search', 90),
+    toolCall('agent-tool-2', 12, 'agent-user-1', 'run_tests', 150),
+    toolCall('agent-tool-3', 20, 'agent-user-2', 'rollback_lookup', 70),
+  ];

  return {
    messages,
    llmCalls,
+    toolCalls,
    errors,
  };
 }
@@ -201,12 +256,14 @@ function rawMonitoringData() {
    },
    messages: scenario.messages.map(rawMessage),
    llmCalls: scenario.llmCalls.map(rawLlmCall),
+    toolCalls: scenario.toolCalls.map(rawToolCall),
    embeddingCalls: [],
    sessions: [],
    errors: scenario.errors.map(rawError),
    totalCount: {
      messages: scenario.messages.length,
      llmCalls: scenario.llmCalls.length,
+      toolCalls: scenario.toolCalls.length,
      embeddingCalls: 0,
      sessions: 0,
      errors: scenario.errors.length,
@@ -240,6 +297,7 @@ test.describe('monitoring conversation turn grouping', () => {
      scenario.messages,
      scenario.llmCalls,
      scenario.errors,
+      scenario.toolCalls,
    );

    const agentTurn = turns.find((turn) => turn.id === 'agent-user-1');
@@ -254,9 +312,11 @@ test.describe('monitoring conversation turn grouping', () => {
      'Final answer: deployment plan ready',
    ]);
    expect(agentTurn?.llmCalls).toHaveLength(3);
+    expect(agentTurn?.toolCalls).toHaveLength(2);
    expect(agentTurn?.errors).toHaveLength(1);
    expect(agentTurn?.totalTokens).toBe(790);
    expect(agentTurn?.totalDuration).toBe(600);
+    expect(agentTurn?.totalToolDuration).toBe(240);
  });

  test('starts a new turn for each later user message in the same session', () => {
@@ -314,6 +374,30 @@ test.describe('monitoring conversation turn grouping', () => {
    expect(turns[0].totalTokens).toBe(30);
  });

+  test('attaches tool calls without message ids by session time', () => {
+    const user = message('tool-fallback-user', 'user', 1, 'Use tool fallback');
+    const assistant = message(
+      'tool-fallback-assistant',
+      'assistant',
+      2,
+      'Tool fallback reply',
+    );
+    const call = toolCall(
+      'tool-fallback-call',
+      2,
+      undefined,
+      'memory_lookup',
+      45,
+    );
+
+    const turns = buildConversationTurns([user, assistant], [], [], [call]);
+
+    expect(turns).toHaveLength(1);
+    expect(turns[0].toolCalls).toHaveLength(1);
+    expect(turns[0].toolCalls[0].id).toBe(call.id);
+    expect(turns[0].totalToolDuration).toBe(45);
+  });
+
  test('renders user-only, multi-agent, and multi-turn cases in the monitoring page', async ({
    page,
  }) => {
@@ -333,6 +417,7 @@ test.describe('monitoring conversation turn grouping', () => {
    await expect(page.getByText('Agent step 1: inspect repo')).toBeVisible();
    await expect(page.getByText('Assistant +2')).toBeVisible();
    await expect(page.getByText('3 LLM')).toBeVisible();
+    await expect(page.getByText('2 tools')).toBeVisible();
    await expect(page.getByText('790 tokens')).toBeVisible();
    await expect(page.getByText('1 errors')).toBeVisible();
    await expect(page.getByText('Continue with rollback plan')).toBeVisible();
@@ -354,6 +439,15 @@ test.describe('monitoring conversation turn grouping', () => {
    await expect(page.getByText('In: 300')).toBeVisible();
    await expect(page.getByText('Out: 90')).toBeVisible();
    await expect(page.getByText('Total: 390')).toBeVisible();
+    await expect(page.getByText('Tool Calls (2)')).toBeVisible();
+    await expect(page.getByText('#1 repo_search')).toBeVisible();
+    await expect(page.getByText('#2 run_tests')).toBeVisible();
+    await expect(page.getByText('Arguments')).toHaveCount(0);
+    await expect(page.getByText('Result')).toHaveCount(0);
+
+    await page.getByText('#1 repo_search').click();
+    await expect(page.getByText('Arguments').first()).toBeVisible();
+    await expect(page.getByText('Result').first()).toBeVisible();
    await expect(page.getByText('Tool retry failed')).toBeVisible();
  });
 });