@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/components/observability/SpansList.tsx

@@ -0,0 +1,210 @@
+'use client'
+
+import { useState, useMemo } from 'react'
+import { useTranslations } from 'next-intl'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+import type { Span } from '../../types/observability.types'
+import { TraceStatusBadge } from './TraceStatusBadge'
+
+// Internal chain patterns to filter (LangChain infrastructure noise)
+const INTERNAL_CHAIN_PATTERNS = [
+  /^Chain:\s*(Runnable|Channel|Compiled)/i,
+  /^RunnableSequence$/i,
+  /^RunnableLambda$/i,
+  /^ChannelWrite$/i,
+  /^ChannelRead$/i,
+]
+
+interface SpansListProps {
+  spans: Span[]
+  className?: string
+}
+
+export function SpansList({ spans, className = '' }: SpansListProps) {
+  const t = useTranslations('observability')
+  const [expandedSpans, setExpandedSpans] = useState<Set<string>>(new Set())
+  const [showInternalChains, setShowInternalChains] = useState(false)
+
+  // Filter internal chain spans
+  const { displaySpans, hiddenCount } = useMemo(() => {
+    if (showInternalChains) {
+      return { displaySpans: spans, hiddenCount: 0 }
+    }
+
+    const filtered = spans.filter((span) => {
+      // Always show non-chain spans
+      if (span.type !== 'chain') return true
+      // Always show chains with errors
+      if (span.error) return true
+      // Filter internal chains by pattern
+      return !INTERNAL_CHAIN_PATTERNS.some((pattern) => pattern.test(span.name))
+    })
+
+    return {
+      displaySpans: filtered,
+      hiddenCount: spans.length - filtered.length,
+    }
+  }, [spans, showInternalChains])
+
+  const toggleSpan = (spanId: string) => {
+    setExpandedSpans((prev) => {
+      const next = new Set(prev)
+      if (next.has(spanId)) {
+        next.delete(spanId)
+      } else {
+        next.add(spanId)
+      }
+      return next
+    })
+  }
+
+  const formatDuration = (ms?: number) => {
+    if (!ms) return '-'
+    if (ms < 1000) return `${ms}ms`
+    return `${(ms / 1000).toFixed(2)}s`
+  }
+
+  const formatTokens = (input?: number, output?: number) => {
+    if (!input && !output) return null
+    return `${input || 0}/${output || 0} tokens`
+  }
+
+  const getSpanTypeLabel = (type: string) => {
+    return type.toUpperCase()
+  }
+
+  if (spans.length === 0) {
+    return (
+      <div className="text-center py-8 text-muted-foreground" data-cy="spans-list-empty">
+        {t('detail.noSpans')}
+      </div>
+    )
+  }
+
+  return (
+    <div className={className} data-cy="spans-list">
+      {/* Filter toggle */}
+      {hiddenCount > 0 && (
+        <div className="flex items-center justify-between mb-3 p-2 bg-muted/50 rounded-lg" data-cy="spans-filter-info">
+          <span className="text-sm text-muted-foreground">
+            {t('detail.hiddenSpans', { count: hiddenCount })}
+          </span>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => setShowInternalChains(!showInternalChains)}
+            data-cy="toggle-internal-chains"
+          >
+            {showInternalChains ? t('detail.hideInternalChains') : t('detail.showInternalChains')}
+          </Button>
+        </div>
+      )}
+      {showInternalChains && hiddenCount > 0 && (
+        <div className="flex justify-end mb-3">
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => setShowInternalChains(false)}
+            data-cy="hide-internal-chains"
+          >
+            {t('detail.hideInternalChains')}
+          </Button>
+        </div>
+      )}
+
+      <div className="space-y-2">
+        {displaySpans.map((span) => {
+        const isExpanded = expandedSpans.has(span.spanId)
+        const hasDetails =
+          (span.toolInput !== undefined && span.toolInput !== null) ||
+          (span.toolOutput !== undefined && span.toolOutput !== null) ||
+          !!span.error
+
+        return (
+          <div
+            key={span.spanId}
+            className="border border-border rounded-lg p-3 bg-card"
+            data-cy={`span-item-${span.spanId}`}
+            style={{ marginLeft: `${span.depth * 24}px` }}
+          >
+            <div className="flex items-start justify-between gap-4">
+              <div className="flex-1">
+                <div className="flex items-center gap-2 mb-1">
+                  <span className="text-[10px] font-mono uppercase tracking-wider text-muted-foreground bg-muted px-1.5 py-0.5 rounded" data-cy="span-type">
+                    {getSpanTypeLabel(span.type)}
+                  </span>
+                  <span className="font-medium text-foreground" data-cy="span-name">
+                    {span.name}
+                  </span>
+                  <TraceStatusBadge status={span.status} />
+                </div>
+
+                <div className="flex items-center gap-4 text-sm text-muted-foreground">
+                  {span.provider && (
+                    <span data-cy="span-provider">
+                      {span.provider} / {span.model}
+                    </span>
+                  )}
+
+                  {span.toolName && <span data-cy="span-tool-name">{span.toolName}</span>}
+
+                  <span data-cy="span-duration">{formatDuration(span.durationMs)}</span>
+
+                  {formatTokens(span.inputTokens, span.outputTokens) && (
+                    <span data-cy="span-tokens">{formatTokens(span.inputTokens, span.outputTokens)}</span>
+                  )}
+                </div>
+
+                {hasDetails && (
+                  <button
+                    onClick={() => toggleSpan(span.spanId)}
+                    className="mt-2 text-sm text-primary hover:underline"
+                    data-cy={`span-toggle-${span.spanId}`}
+                  >
+                    {isExpanded ? t('detail.hideDetails') : t('detail.showDetails')}
+                  </button>
+                )}
+
+                {isExpanded && (
+                  <div className="mt-3 space-y-2" data-cy={`span-details-${span.spanId}`}>
+                    {span.toolInput !== undefined && span.toolInput !== null && (
+                      <div>
+                        <div className="text-sm font-medium text-foreground mb-1">
+                          {t('detail.toolInput')}
+                        </div>
+                        <pre className="text-xs bg-muted p-2 rounded overflow-x-auto">
+                          {JSON.stringify(span.toolInput, null, 2)}
+                        </pre>
+                      </div>
+                    )}
+
+                    {span.toolOutput !== undefined && span.toolOutput !== null && (
+                      <div>
+                        <div className="text-sm font-medium text-foreground mb-1">
+                          {t('detail.toolOutput')}
+                        </div>
+                        <pre className="text-xs bg-muted p-2 rounded overflow-x-auto">
+                          {JSON.stringify(span.toolOutput, null, 2)}
+                        </pre>
+                      </div>
+                    )}
+
+                    {span.error && (
+                      <div>
+                        <div className="text-sm font-medium text-destructive mb-1">{t('detail.error')}</div>
+                        <pre className="text-xs bg-destructive/10 text-destructive p-2 rounded overflow-x-auto">
+                          {span.error}
+                        </pre>
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+            </div>
+          </div>
+        )
+      })}
+      </div>
+    </div>
+  )
+}

package/components/observability/TraceDetail.tsx

@@ -0,0 +1,335 @@
+'use client'
+
+import { useMemo } from 'react'
+import { useTranslations } from 'next-intl'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@nextsparkjs/core/components/ui/card'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@nextsparkjs/core/components/ui/accordion'
+import type { Trace, Span } from '../../types/observability.types'
+import { TraceStatusBadge } from './TraceStatusBadge'
+import { SpansList } from './SpansList'
+import { ConversationFlow } from './ConversationFlow'
+import { CompactTimeline } from './CompactTimeline'
+
+interface ParentTraceInfo {
+  traceId: string
+  agentName: string
+}
+
+interface TraceDetailProps {
+  trace: Trace
+  spans: Span[]
+  childTraces?: Trace[]
+  childSpansMap?: Record<string, Span[]>
+  parentTrace?: ParentTraceInfo
+  onBack: () => void
+  onSelectChildTrace?: (traceId: string) => void
+  onSelectParentTrace?: (traceId: string) => void
+  className?: string
+}
+
+export function TraceDetail({ trace, spans, childTraces = [], childSpansMap = {}, parentTrace, onBack, onSelectChildTrace, onSelectParentTrace, className = '' }: TraceDetailProps) {
+  const t = useTranslations('observability')
+
+  const formatDuration = (ms?: number) => {
+    if (!ms) return '-'
+    if (ms < 1000) return `${ms}ms`
+    return `${(ms / 1000).toFixed(2)}s`
+  }
+
+  const formatTokens = (tokens: number) => {
+    if (tokens === 0) return '-'
+    return tokens.toLocaleString()
+  }
+
+  // Extract unique tools used in this trace
+  const toolsUsed = useMemo(() => {
+    return [...new Set(
+      spans
+        .filter((s) => s.type === 'tool' && s.toolName)
+        .map((s) => s.toolName!)
+    )]
+  }, [spans])
+
+  // Extract model info from LLM spans
+  const modelInfo = useMemo(() => {
+    const llmSpan = spans.find((s) => s.type === 'llm' && s.model)
+    if (!llmSpan) return null
+    return {
+      model: llmSpan.model,
+      provider: llmSpan.provider,
+    }
+  }, [spans])
+
+  return (
+    <div className={className} data-cy="trace-detail">
+      <div className="mb-6">
+        <div className="flex items-center gap-2 mb-4">
+          <Button variant="ghost" onClick={onBack} data-cy="trace-back-button">
+            ← {t('detail.back')}
+          </Button>
+          {parentTrace && onSelectParentTrace && (
+            <>
+              <span className="text-muted-foreground">/</span>
+              <Button
+                variant="link"
+                onClick={() => onSelectParentTrace(parentTrace.traceId)}
+                className="text-primary hover:underline p-0 h-auto font-medium"
+                data-cy="parent-trace-link"
+              >
+                {parentTrace.agentName}
+              </Button>
+              <span className="text-muted-foreground">/</span>
+              <span className="font-medium">{trace.agentName}</span>
+            </>
+          )}
+        </div>
+
+        <div className="flex items-start justify-between">
+          <div>
+            <h2 className="text-2xl font-bold mb-2">{t('detail.title')}</h2>
+            <p className="text-sm text-muted-foreground font-mono">{trace.traceId}</p>
+          </div>
+          <TraceStatusBadge status={trace.status} />
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4 mb-6">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium text-muted-foreground">
+              {t('detail.agent')}
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-lg font-semibold" data-cy="trace-agent">
+              {trace.agentName}
+            </p>
+            {trace.agentType && (
+              <p className="text-sm text-muted-foreground">{trace.agentType}</p>
+            )}
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium text-muted-foreground">
+              {t('detail.model')}
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-lg font-semibold" data-cy="trace-model">
+              {modelInfo?.model || '-'}
+            </p>
+            {modelInfo?.provider && (
+              <p className="text-sm text-muted-foreground" data-cy="trace-provider">
+                {modelInfo.provider}
+              </p>
+            )}
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium text-muted-foreground">
+              {t('detail.duration')}
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-lg font-semibold" data-cy="trace-duration">
+              {formatDuration(trace.durationMs)}
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium text-muted-foreground">
+              {t('detail.tokens')}
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-lg font-semibold" data-cy="trace-tokens">
+              {formatTokens(trace.totalTokens)}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              {formatTokens(trace.inputTokens)} in / {formatTokens(trace.outputTokens)} out
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium text-muted-foreground">
+              {t('detail.calls')}
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-lg font-semibold" data-cy="trace-calls">
+              {trace.llmCalls} LLM / {trace.toolCalls} {t('detail.tools')}
+            </p>
+            {toolsUsed.length > 0 && (
+              <p className="text-xs text-muted-foreground mt-1" data-cy="trace-tools-used">
+                {toolsUsed.join(', ')}
+              </p>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+
+      <div className="space-y-6">
+        {/* Error box - shown first when there's an error */}
+        {trace.error && (
+          <Card className="border-destructive">
+            <CardHeader>
+              <CardTitle className="text-destructive">{t('detail.error')}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre
+                className="text-sm bg-destructive/10 text-destructive p-4 rounded-lg overflow-x-auto whitespace-pre-wrap"
+                data-cy="trace-error"
+              >
+                {trace.error}
+              </pre>
+              {trace.errorStack && (
+                <details className="mt-4">
+                  <summary className="cursor-pointer text-sm font-medium mb-2">
+                    {t('detail.stackTrace')}
+                  </summary>
+                  <pre className="text-xs bg-destructive/10 text-destructive p-3 rounded overflow-x-auto">
+                    {trace.errorStack}
+                  </pre>
+                </details>
+              )}
+            </CardContent>
+          </Card>
+        )}
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t('detail.input')}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <pre
+              className="text-sm bg-muted p-4 rounded-lg overflow-x-auto whitespace-pre-wrap"
+              data-cy="trace-input"
+            >
+              {trace.input}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Conversation Flow - Human-readable execution view */}
+        <ConversationFlow trace={trace} spans={spans} />
+
+        {/* Child Traces - Sub-agent invocations with accordion */}
+        {childTraces.length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardTitle>{t('detail.childTraces')}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <Accordion type="multiple" className="w-full" data-cy="child-traces-list">
+                {childTraces.map((child) => (
+                  <AccordionItem
+                    key={child.traceId}
+                    value={child.traceId}
+                    className="border rounded-lg mb-3 last:mb-0"
+                    data-cy={`child-trace-${child.agentName}`}
+                  >
+                    <AccordionTrigger className="px-4 hover:no-underline">
+                      <div className="flex items-center justify-between w-full pr-4">
+                        <div className="flex items-center gap-3">
+                          <TraceStatusBadge status={child.status} />
+                          <div className="text-left">
+                            <p className="font-medium">{child.agentName}</p>
+                            <p className="text-xs text-muted-foreground font-mono">
+                              {child.traceId.slice(0, 8)}...
+                            </p>
+                          </div>
+                        </div>
+                        <div className="text-right text-sm">
+                          <p>{formatDuration(child.durationMs)}</p>
+                          <p className="text-xs text-muted-foreground">
+                            {formatTokens(child.totalTokens)} tokens
+                          </p>
+                        </div>
+                      </div>
+                    </AccordionTrigger>
+                    <AccordionContent className="px-4">
+                      <div className="space-y-4 pt-2">
+                        {/* Stats row */}
+                        <div className="grid grid-cols-3 gap-4 text-sm">
+                          <div className="bg-muted/50 rounded p-2">
+                            <p className="text-muted-foreground text-xs">{t('detail.duration')}</p>
+                            <p className="font-medium">{formatDuration(child.durationMs)}</p>
+                          </div>
+                          <div className="bg-muted/50 rounded p-2">
+                            <p className="text-muted-foreground text-xs">{t('detail.tokens')}</p>
+                            <p className="font-medium">
+                              {formatTokens(child.inputTokens)} / {formatTokens(child.outputTokens)}
+                            </p>
+                          </div>
+                          <div className="bg-muted/50 rounded p-2">
+                            <p className="text-muted-foreground text-xs">{t('detail.calls')}</p>
+                            <p className="font-medium">
+                              {child.llmCalls} LLM / {child.toolCalls} tools
+                            </p>
+                          </div>
+                        </div>
+
+                        {/* Compact Timeline - execution flow visualization */}
+                        {childSpansMap[child.traceId] && childSpansMap[child.traceId].length > 0 && (
+                          <div className="bg-muted/30 rounded-lg p-3">
+                            <CompactTimeline spans={childSpansMap[child.traceId]} />
+                          </div>
+                        )}
+
+                        {/* Error if exists */}
+                        {child.error && (
+                          <div className="bg-destructive/10 border border-destructive/20 rounded-lg p-3">
+                            <p className="text-sm font-medium text-destructive mb-1">{t('detail.error')}</p>
+                            <pre className="text-xs text-destructive whitespace-pre-wrap">
+                              {child.error}
+                            </pre>
+                          </div>
+                        )}
+
+                        {/* Input */}
+                        <div>
+                          <p className="text-sm font-medium mb-2">{t('detail.input')}</p>
+                          <pre className="text-sm bg-muted p-3 rounded-lg overflow-x-auto whitespace-pre-wrap max-h-40 overflow-y-auto">
+                            {child.input}
+                          </pre>
+                        </div>
+
+                        {/* Output */}
+                        {child.output && (
+                          <div>
+                            <p className="text-sm font-medium mb-2">{t('detail.output')}</p>
+                            <pre className="text-sm bg-muted p-3 rounded-lg overflow-x-auto whitespace-pre-wrap max-h-60 overflow-y-auto">
+                              {child.output}
+                            </pre>
+                          </div>
+                        )}
+                      </div>
+                    </AccordionContent>
+                  </AccordionItem>
+                ))}
+              </Accordion>
+            </CardContent>
+          </Card>
+        )}
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t('detail.spans')}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <SpansList spans={spans} />
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/components/observability/TraceStatusBadge.tsx

@@ -0,0 +1,39 @@
+'use client'
+
+import { useTranslations } from 'next-intl'
+import type { TraceStatus } from '../../types/observability.types'
+
+interface TraceStatusBadgeProps {
+  status: TraceStatus
+  className?: string
+}
+
+export function TraceStatusBadge({ status, className = '' }: TraceStatusBadgeProps) {
+  const t = useTranslations('observability')
+
+  const statusConfig = {
+    running: {
+      label: t('status.running'),
+      className: 'bg-muted text-muted-foreground border-border',
+    },
+    success: {
+      label: t('status.success'),
+      className: 'bg-muted text-foreground border-border',
+    },
+    error: {
+      label: t('status.error'),
+      className: 'bg-destructive/10 text-destructive border-destructive/20',
+    },
+  }
+
+  const config = statusConfig[status]
+
+  return (
+    <span
+      className={`inline-flex items-center px-2 py-1 rounded-md text-xs font-medium border ${config.className} ${className}`}
+      data-cy={`trace-status-${status}`}
+    >
+      {config.label}
+    </span>
+  )
+}

package/components/observability/TracesTable.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+import { useTranslations } from 'next-intl'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@nextsparkjs/core/components/ui/table'
+import type { Trace } from '../../types/observability.types'
+import { TraceStatusBadge } from './TraceStatusBadge'
+
+interface TracesTableProps {
+  traces: Trace[]
+  onSelect: (traceId: string) => void
+  className?: string
+}
+
+export function TracesTable({ traces, onSelect, className = '' }: TracesTableProps) {
+  const t = useTranslations('observability')
+
+  const formatDuration = (ms?: number) => {
+    if (!ms) return '-'
+    if (ms < 1000) return `${ms}ms`
+    return `${(ms / 1000).toFixed(2)}s`
+  }
+
+  const formatTokens = (tokens: number) => {
+    if (tokens === 0) return '-'
+    return tokens.toLocaleString()
+  }
+
+  const truncateTraceId = (traceId: string) => {
+    return `${traceId.substring(0, 8)}...${traceId.substring(traceId.length - 4)}`
+  }
+
+  const truncateInput = (input: string, maxLength = 60) => {
+    if (!input) return '-'
+    if (input.length <= maxLength) return input
+    return `${input.substring(0, maxLength)}...`
+  }
+
+  if (traces.length === 0) {
+    return (
+      <div className="text-center py-12" data-cy="traces-table-empty">
+        <p className="text-muted-foreground">{t('table.empty')}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className={className} data-cy="traces-table">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{t('table.traceId')}</TableHead>
+            <TableHead className="min-w-[200px]">{t('table.input')}</TableHead>
+            <TableHead>{t('table.agent')}</TableHead>
+            <TableHead>{t('table.status')}</TableHead>
+            <TableHead>{t('table.duration')}</TableHead>
+            <TableHead>{t('table.tokens')}</TableHead>
+            <TableHead>{t('table.startedAt')}</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {traces.map((trace) => (
+            <TableRow
+              key={trace.traceId}
+              onClick={() => onSelect(trace.traceId)}
+              className="cursor-pointer hover:bg-muted/50"
+              data-cy="trace-row"
+              data-trace-id={trace.traceId}
+            >
+              <TableCell className="font-mono text-xs" data-cy="trace-id">
+                {truncateTraceId(trace.traceId)}
+              </TableCell>
+              <TableCell className="text-sm max-w-[300px]" data-cy="trace-input" title={trace.input}>
+                {truncateInput(trace.input)}
+              </TableCell>
+              <TableCell data-cy="trace-agent">{trace.agentName}</TableCell>
+              <TableCell data-cy="trace-status">
+                <TraceStatusBadge status={trace.status} />
+              </TableCell>
+              <TableCell data-cy="trace-duration">{formatDuration(trace.durationMs)}</TableCell>
+              <TableCell data-cy="trace-tokens">{formatTokens(trace.totalTokens)}</TableCell>
+              <TableCell className="text-sm text-muted-foreground" data-cy="trace-started-at">
+                {new Date(trace.startedAt).toLocaleString()}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}

package/components/observability/index.ts

@@ -0,0 +1,7 @@
+export { ObservabilityDashboard } from './ObservabilityDashboard'
+export { TracesTable } from './TracesTable'
+export { TraceDetail } from './TraceDetail'
+export { SpansList } from './SpansList'
+export { FiltersPanel } from './FiltersPanel'
+export { TraceStatusBadge } from './TraceStatusBadge'
+export { DisabledMessage } from './DisabledMessage'