Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

24.0 KB
Raw Blame
import { useId, useRef, useMemo, useState, useEffect, useCallback, useDeferredValue } from 'react';
import axios from 'axios';
import { useAtom } from 'jotai';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { QueryKeys, resolveTraceViewerConfig } from 'librechat-data-provider';
import { Button, Spinner, EmptyState, FilterInput, buttonVariants } from '@librechat/client';
import {
  X,
  Clock,
  Layers,
  ZoomIn,
  ZoomOut,
  RefreshCw,
  ExternalLink,
  ChevronsUpDown,
  ChevronsDownUp,
  TriangleAlert,
  ChartNoAxesGantt,
} from 'lucide-react';
import type {
  TMessage,
  TTraceRecord,
  TTraceErrorCode,
  TTraceErrorResponse,
} from 'librechat-data-provider';
import type { KeyboardEvent } from 'react';
import type { TraceNode, TraceWindow } from './model';
import type { TranslationKeys } from '~/hooks';
import {
  keepNewestTracePage,
  useGetStartupConfig,
  fetchConversationMessages,
  useGetLangfuseSessionLinkQuery,
  useConversationTraceRecordsQuery,
} from '~/data-provider';
import {
  boundsOf,
  ZOOM_STEP,
  zoomWindow,
  flattenRows,
  minimumSpan,
  rebaseWindow,
  buildTraceModel,
  collapsibleKeys,
} from './model';
import { alignTurns, buildPreviews, buildPreviewIndex, buildActivityIndex } from './preview';
import { useMCPIconMap, useMCPServerNames } from '~/hooks/MCP';
import { traceModeAtom, traceScaleAtom } from './store';
import { presentTool, presentRecord } from './present';
import { appearanceOf, STATUS_LABEL } from './kinds';
import { useAgentsMapContext } from '~/Providers';
import { useTraceFormat } from './format';
import { useLocalize } from '~/hooks';
import Inspector from './Inspector';
import Timeline from './Timeline';
import Summary from './Summary';
import Ledger from './Ledger';
import { cn } from '~/utils';

const ERROR_MESSAGES: Partial<Record<TTraceErrorCode, TranslationKeys>> = {
  invalid_request: 'com_ui_trace_error_changed',
  not_found: 'com_ui_trace_error_not_found',
  rate_limited: 'com_ui_trace_error_rate_limited',
  timeout: 'com_ui_trace_error_timeout',
  unauthorized: 'com_ui_trace_error_unauthorized',
  unsupported: 'com_ui_trace_error_unsupported',
};

const PRESSED = 'bg-surface-active-alt';
/** A response's header quotes the question it answered; the row truncates what does not fit. */
const ASKED_LENGTH = 120;

function errorCodeOf(error: unknown): TTraceErrorCode | undefined {
  return axios.isAxiosError<TTraceErrorResponse>(error)
    ? error.response?.data?.errorCode
    : undefined;
}

function errorMessageKey(error: unknown): TranslationKeys {
  const code = errorCodeOf(error);
  return (code != null ? ERROR_MESSAGES[code] : undefined) ?? 'com_ui_trace_error_generic';
}

/**
 * The conversation trace: a summary, a pinned overview of every loaded record,
 * the record ledger and an inspector. It covers the chat surface and returns
 * focus to whatever opened it when it closes.
 */
export default function Viewer({
  conversationId,
  onClose,
}: {
  conversationId: string;
  onClose: () => void;
}) {
  const localize = useLocalize();
  const queryClient = useQueryClient();
  const format = useTraceFormat();
  const headingId = useId();
  const searchId = useId();
  const closeRef = useRef<HTMLButtonElement>(null);
  const treeRef = useRef<HTMLDivElement>(null);
  const { data: startupConfig } = useGetStartupConfig();
  const settings = resolveTraceViewerConfig(startupConfig?.interface?.traceViewer);
  const showCost = startupConfig?.interface?.contextCost === true;
  const currency = startupConfig?.interface?.currency;

  const recordsQuery = useConversationTraceRecordsQuery(conversationId, true);
  const { data: langfuseSession } = useGetLangfuseSessionLinkQuery(
    conversationId,
    startupConfig?.langfuseConnectionAccess === true,
  );
  /** The chat's own messages, already loaded underneath the trace; they are only read, never fetched here. */
  const { data: messages } = useQuery<TMessage[]>(
    [QueryKeys.messages, conversationId],
    () => fetchConversationMessages(conversationId),
    { enabled: false },
  );

  const [mode, setMode] = useAtom(traceModeAtom);
  const [scale, setScale] = useAtom(traceScaleAtom);
  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set());
  const [query, setQuery] = useState('');
  const [view, setView] = useState<TraceWindow | null>(null);
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [lastRead, setLastRead] = useState<'refresh' | 'older'>('refresh');
  /** Rereads only the newest page; older pages cannot change and reload on demand. */
  const refresh = useCallback(() => {
    setLastRead('refresh');
    keepNewestTracePage(queryClient, conversationId);
    recordsQuery.refetch();
    /** An open record may have finished or finished ingesting since its detail loaded. */
    queryClient.invalidateQueries([QueryKeys.conversationTraceRecord, conversationId]);
  }, [queryClient, conversationId, recordsQuery]);
  const loadOlder = useCallback(() => {
    setLastRead('older');
    recordsQuery.fetchNextPage();
  }, [recordsQuery]);
  const deferredQuery = useDeferredValue(query);

  const pages = recordsQuery.data?.pages;
  const records = useMemo(() => pages?.flatMap((page) => page.records) ?? [], [pages]);
  const recordSources = useMemo(() => {
    const sources = new Map<string, string>();
    for (const page of pages ?? []) {
      for (const record of page.records) {
        if (page.sourceId != null) {
          sources.set(record.id, page.sourceId);
        }
      }
    }
    return sources;
  }, [pages]);
  /** The session link opens one project; offer it only when that project served every loaded page. */
  const langfuseUrl =
    langfuseSession?.url != null &&
    langfuseSession.destinationId != null &&
    pages != null &&
    pages.length > 0 &&
    pages.every((page) => page.sourceId === langfuseSession.destinationId)
      ? langfuseSession.url
      : undefined;
  const hasOlder = recordsQuery.hasNextPage === true;
  const model = useMemo(() => buildTraceModel(records, mode, hasOlder), [records, mode, hasOlder]);
  const bounds = useMemo(() => boundsOf(model, scale), [model, scale]);
  const minSpan = minimumSpan(bounds, scale);
  const previews = useMemo(() => buildPreviews(messages), [messages]);
  /** Pages split a response at the oldest loaded turn, whose earlier steps are still unloaded;
   *  its rounds cannot be numbered against the message until they are. */
  const partialMessageId =
    recordsQuery.hasNextPage === true ? model.turns[0]?.messageId : undefined;
  const alignments = useMemo(
    () => alignTurns(model, previews, partialMessageId),
    [model, previews, partialMessageId],
  );
  const previewIndex = useMemo(
    () => buildPreviewIndex(model, previews, partialMessageId, alignments),
    [model, previews, partialMessageId, alignments],
  );
  const previewOf = useCallback(
    (node: TraceNode) => previewIndex.get(node.record.id),
    [previewIndex],
  );
  const activity = useMemo(
    () => buildActivityIndex(model, previews, partialMessageId, alignments),
    [model, previews, partialMessageId, alignments],
  );
  const agentsMap = useAgentsMapContext();
  const mcpIconMap = useMCPIconMap();
  const mcpServerNames = useMCPServerNames();
  const agentOf = useCallback((agentId: string) => agentsMap?.[agentId], [agentsMap]);
  const presentFor = useMemo(() => {
    const sources = { localize, activity, previewOf, mcpServerNames, agentOf };
    const presented = new Map<string, ReturnType<typeof presentRecord>>();
    return (node: TraceNode) => {
      const cached = presented.get(node.record.id);
      if (cached != null) {
        return cached;
      }
      const presentation = presentRecord(node, sources);
      presented.set(node.record.id, presentation);
      return presentation;
    };
  }, [localize, activity, previewOf, mcpServerNames, agentOf]);
  const toolFor = useCallback(
    (name: string) => presentTool(name, { localize, mcpServerNames }),
    [localize, mcpServerNames],
  );
  const toolTitleFor = useCallback((name: string) => toolFor(name).title, [toolFor]);
  /** The user message each response answered: what tells one response from another in the ledger. */
  const askedByResponse = useMemo(() => {
    const textById = new Map<string, string>();
    const asked = new Map<string, string>();
    for (const message of messages ?? []) {
      if (message.isCreatedByUser) {
        textById.set(message.messageId, message.text);
      }
    }
    for (const message of messages ?? []) {
      const text = message.isCreatedByUser
        ? undefined
        : textById.get(message.parentMessageId ?? '')?.trim();
      if (text) {
        asked.set(message.messageId, text.replace(/\s+/g, ' ').slice(0, ASKED_LENGTH));
      }
    }
    return asked;
  }, [messages]);
  const askedFor = useCallback(
    (messageId: string) => askedByResponse.get(messageId),
    [askedByResponse],
  );
  const labelsFor = useCallback(
    (record: TTraceRecord) => {
      const node = model.nodes.get(record.id);
      const presentation = node != null ? presentFor(node) : undefined;
      return [
        localize(appearanceOf(record).label),
        localize(STATUS_LABEL[record.status]),
        ...[presentation?.title, presentation?.caption, presentation?.preview].filter(
          (label): label is string => label != null,
        ),
      ];
    },
    [localize, model, presentFor],
  );
  const rows = useMemo(
    () => flattenRows(model, { collapsed, query: deferredQuery, window: view, scale, labelsFor }),
    [model, collapsed, deferredQuery, view, scale, labelsFor],
  );
  /** A refresh or a settled run trims the cache to its newest page, an older page renumbers the
   *  sequence, and a mode change hides records. A selection or interval on records no longer
   *  listed would leave an inspector on nothing, or hide every row, so both follow the records. */
  const previousModel = useRef(model);
  useEffect(() => {
    const previous = previousModel.current;
    previousModel.current = model;
    /** An agent is opened from its response's header, which lists it whether or not the mode does. */
    setSelectedId((id) => {
      const node = id != null ? model.nodes.get(id) : undefined;
      return node != null && (node.shown || node.record.role === 'agent') ? id : null;
    });
    setView((current) =>
      current != null ? rebaseWindow(current, previous, model, scale) : current,
    );
  }, [model, scale]);
  /** Positions mean something else on the other scale or with other records shown. */
  useEffect(() => {
    setView(null);
  }, [scale, mode]);
  /** Older responses arrive folded to their summary; the newest one opens, since it is what the user just ran. */
  const seenTurns = useRef(new Set<string>());
  useEffect(() => {
    const newest = model.turns[model.turns.length - 1]?.key;
    const fold = model.turns
      .filter((turn) => !seenTurns.current.has(turn.key) && turn.key !== newest)
      .map((turn) => turn.key);
    for (const turn of model.turns) {
      seenTurns.current.add(turn.key);
    }
    if (fold.length > 0) {
      setCollapsed((current) => new Set([...current, ...fold]));
    }
  }, [model]);
  const selectedNode = selectedId != null ? model.nodes.get(selectedId) : undefined;
  const selectedTurnStart =
    model.turns.find((turn) => turn.messageId === selectedNode?.record.messageId)?.start ??
    model.start;

  useEffect(() => {
    const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;
    closeRef.current?.focus();
    return () => {
      /** Only reclaim focus the trace took with it; a close caused by navigating
       *  elsewhere leaves focus wherever that navigation put it. */
      const active = document.activeElement;
      if (active != null && active !== document.body) {
        return;
      }
      const target = opener?.isConnected ? opener : document.getElementById('header-menu-button');
      target?.focus();
    };
  }, []);

  const toggle = useCallback((key: string) => {
    setCollapsed((current) => {
      const next = new Set(current);
      if (next.has(key)) {
        next.delete(key);
      } else {
        next.add(key);
      }
      return next;
    });
  }, []);

  const closeInspector = useCallback(() => {
    setSelectedId(null);
    /** A filter that matches nothing unmounts the tree; the search field is what is left to return to. */
    (treeRef.current ?? document.getElementById(searchId))?.focus();
  }, [searchId]);

  const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {
    if (event.key !== 'Escape' || event.defaultPrevented) {
      return;
    }
    event.preventDefault();
    if (selectedId != null) {
      closeInspector();
      return;
    }
    onClose();
  };

  const refreshButton = (
    <Button
      size="icon-sm"
      variant="outline"
      aria-label={localize('com_ui_trace_refresh')}
      disabled={recordsQuery.isFetching}
      onClick={refresh}
    >
      <RefreshCw
        aria-hidden="true"
        className={cn(
          'size-4',
          recordsQuery.isFetching && 'animate-spin motion-reduce:animate-none',
        )}
      />
    </Button>
  );

  const selectionText = () => {
    if (view == null) {
      return null;
    }
    if (scale === 'sequence') {
      return localize('com_ui_trace_selection_records', {
        0: String(Math.floor(view.start) + 1),
        1: String(Math.ceil(view.end)),
      });
    }
    return localize('com_ui_trace_selection', {
      0: format.duration(view.start - model.start),
      1: format.duration(view.end - model.start),
    });
  };

  const renderBody = () => {
    if (recordsQuery.isLoading) {
      return (
        <div role="status" className="flex flex-1 items-center justify-center gap-2">
          <Spinner tone="secondary" className="size-5" />
          <span className="sr-only">{localize('com_ui_trace_loading')}</span>
        </div>
      );
    }

    if (recordsQuery.isError && recordsQuery.data == null) {
      return (
        <div className="flex flex-1 items-center justify-center p-4">
          <EmptyState
            icon={TriangleAlert}
            title={localize('com_ui_trace_error_title')}
            description={localize(errorMessageKey(recordsQuery.error))}
            action={
              <Button size="sm" variant="outline" onClick={refresh}>
                {localize('com_ui_retry')}
              </Button>
            }
          />
        </div>
      );
    }

    if (model.nodes.size === 0 && recordsQuery.hasNextPage !== true) {
      return (
        <div className="flex flex-1 items-center justify-center p-4">
          <EmptyState
            icon={ChartNoAxesGantt}
            title={localize('com_ui_trace_empty_title')}
            description={localize('com_ui_trace_empty_description')}
            action={
              <Button size="sm" variant="outline" onClick={refresh}>
                {localize('com_ui_trace_refresh')}
              </Button>
            }
          />
        </div>
      );
    }

    /** A refresh or an older page failed while earlier results stay on screen. */
    const cachedReadFailed = recordsQuery.isError && recordsQuery.data != null;
    return (
      <>
        <div className="border-border-light flex flex-col gap-3 border-b px-3 py-3 md:px-4">
          <div className="flex flex-wrap items-center justify-between gap-2">
            <Summary
              summary={model.summary}
              unrecordedCalls={activity.unrecordedCalls}
              showCost={showCost}
              currency={currency}
            />
            {recordsQuery.hasNextPage === true && (
              <p className="text-text-secondary text-xs">
                {localize('com_ui_trace_partial', { 0: String(records.length) })}
              </p>
            )}
          </div>
          <Timeline model={model} scale={scale} view={view} onViewChange={setView} />
          <div className="flex flex-wrap items-center gap-2">
            <FilterInput
              inputId={searchId}
              label={localize('com_ui_trace_search')}
              value={query}
              onChange={(event) => setQuery(event.target.value)}
              onKeyDown={(event) => {
                if (event.key === 'Escape' && query !== '') {
                  event.preventDefault();
                  setQuery('');
                }
              }}
              containerClassName="min-w-[10rem] flex-1 md:max-w-xs"
            />
            <Button
              size="sm"
              variant="outline"
              aria-label={localize('com_ui_trace_expand_all')}
              onClick={() => setCollapsed(new Set())}
              disabled={collapsed.size === 0}
            >
              <ChevronsUpDown className="size-4" aria-hidden="true" />
              <span className="hidden sm:inline">{localize('com_ui_trace_expand_all')}</span>
            </Button>
            <Button
              size="sm"
              variant="outline"
              aria-label={localize('com_ui_trace_collapse_all')}
              onClick={() => setCollapsed(new Set(collapsibleKeys(model)))}
            >
              <ChevronsDownUp className="size-4" aria-hidden="true" />
              <span className="hidden sm:inline">{localize('com_ui_trace_collapse_all')}</span>
            </Button>
            <Button
              size="sm"
              variant="outline"
              aria-label={localize('com_ui_trace_scale_duration')}
              aria-pressed={scale === 'time'}
              title={localize('com_ui_trace_scale_duration_description')}
              className={cn(scale === 'time' && PRESSED)}
              onClick={() => setScale(scale === 'time' ? 'sequence' : 'time')}
            >
              <Clock className="size-4" aria-hidden="true" />
              <span className="hidden sm:inline">{localize('com_ui_trace_scale_duration')}</span>
            </Button>
            <Button
              size="sm"
              variant="outline"
              aria-label={localize('com_ui_trace_all_spans')}
              aria-pressed={mode === 'full'}
              title={localize('com_ui_trace_all_spans_description')}
              className={cn(mode === 'full' && PRESSED)}
              onClick={() => setMode(mode === 'full' ? 'simple' : 'full')}
            >
              <Layers className="size-4" aria-hidden="true" />
              <span className="hidden sm:inline">{localize('com_ui_trace_all_spans')}</span>
            </Button>
            <div className="ms-auto flex items-center gap-1">
              {view != null && (
                <span className="text-text-secondary text-xs tabular-nums" aria-live="polite">
                  {selectionText()}
                </span>
              )}
              <Button
                size="icon-sm"
                variant="ghost"
                aria-label={localize('com_ui_zoom_out')}
                disabled={view == null}
                onClick={() => setView(zoomWindow(bounds, view, 1 / ZOOM_STEP, undefined, minSpan))}
              >
                <ZoomOut className="size-4" aria-hidden="true" />
              </Button>
              <Button
                size="icon-sm"
                variant="ghost"
                aria-label={localize('com_ui_zoom_in')}
                onClick={() => setView(zoomWindow(bounds, view, ZOOM_STEP, undefined, minSpan))}
              >
                <ZoomIn className="size-4" aria-hidden="true" />
              </Button>
              {view != null && (
                <Button size="sm" variant="ghost" onClick={() => setView(null)}>
                  {localize('com_ui_trace_clear_selection')}
                </Button>
              )}
            </div>
          </div>
        </div>
        <div className="relative flex min-h-0 flex-1">
          <div className="flex min-h-0 min-w-0 flex-1 flex-col">
            {rows.length === 0 ? (
              <p role="status" className="text-text-secondary p-4 text-sm">
                {localize('com_ui_trace_no_matches')}
              </p>
            ) : (
              <Ledger
                rows={rows}
                model={model}
                scale={scale}
                view={view}
                selectedId={selectedId}
                treeRef={treeRef}
                presentFor={presentFor}
                askedFor={askedFor}
                toolTitleFor={toolTitleFor}
                agentOf={agentOf}
                unrecordedCalls={activity.unrecordedCalls}
                stepOffsets={activity.stepOffsets}
                mcpIconMap={mcpIconMap}
                showCost={showCost}
                currency={currency}
                onSelect={setSelectedId}
                onToggle={toggle}
              />
            )}
            {(recordsQuery.hasNextPage === true || cachedReadFailed) && (
              <div className="border-border-light flex flex-wrap items-center justify-center gap-2 border-t p-2">
                {cachedReadFailed && (
                  <>
                    <span role="alert" className="text-status-error text-xs">
                      {localize(errorMessageKey(recordsQuery.error))}
                    </span>
                    <Button
                      size="sm"
                      variant="outline"
                      disabled={recordsQuery.isFetching}
                      onClick={
                        /** A continuation the trace no longer matches can only be reloaded from the newest page. */
                        lastRead === 'older' &&
                        errorCodeOf(recordsQuery.error) !== 'invalid_request'
                          ? loadOlder
                          : refresh
                      }
                    >
                      {localize('com_ui_retry')}
                    </Button>
                  </>
                )}
                {recordsQuery.hasNextPage === true && (
                  <Button
                    size="sm"
                    variant="outline"
                    disabled={recordsQuery.isFetchingNextPage}
                    onClick={loadOlder}
                  >
                    {recordsQuery.isFetchingNextPage && <Spinner className="size-3.5" />}
                    {localize('com_ui_trace_load_older')}
                  </Button>
                )}
              </div>
            )}
          </div>
          {selectedNode && (
            <Inspector
              node={selectedNode}
              presentation={presentFor(selectedNode)}
              mcpIconMap={mcpIconMap}
              toolFor={toolFor}
              turnStart={selectedTurnStart}
              sourceId={recordSources.get(selectedNode.record.id)}
              conversationId={conversationId}
              showContent={settings.showInputOutput}
              showCost={showCost}
              currency={currency}
              onClose={closeInspector}
            />
          )}
        </div>
      </>
    );
  };

  return (
    <section
      aria-labelledby={headingId}
      data-testid="trace-viewer"
      onKeyDown={handleKeyDown}
      className="bg-surface-primary-alt text-text-primary absolute inset-0 z-20 flex flex-col"
    >
      <div className="border-border-light flex h-[52px] shrink-0 items-center gap-2 border-b px-2 md:px-4">
        <h2 id={headingId} className="text-base font-semibold">
          {localize('com_ui_trace_title')}
        </h2>
        <div className="ms-auto flex items-center gap-2">
          {langfuseUrl != null && (
            <a
              href={langfuseUrl}
              target="_blank"
              rel="noopener noreferrer"
              className={buttonVariants({ variant: 'outline', size: 'sm' })}
            >
              <ExternalLink className="size-4" aria-hidden="true" />
              <span className="hidden sm:inline">{localize('com_ui_trace_open_langfuse')}</span>
              <span className="sr-only sm:hidden">{localize('com_ui_trace_open_langfuse')}</span>
            </a>
          )}
          {refreshButton}
          <Button
            ref={closeRef}
            size="icon-sm"
            variant="outline"
            aria-label={localize('com_ui_trace_close')}
            onClick={onClose}
          >
            <X className="size-4" aria-hidden="true" />
          </Button>
        </div>
      </div>
      {renderBody()}
    </section>
  );
}