@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/api/observability/traces/route.ts

@@ -0,0 +1,205 @@
+/**
+ * GET /api/langchain/observability/traces
+ *
+ * List traces with pagination and filters.
+ * Admin access required (superadmin or developer).
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import type { Trace } from '../../../types/observability.types'
+
+interface TraceRow {
+  traceId: string
+  userId: string
+  teamId: string
+  sessionId: string | null
+  agentName: string
+  agentType: string | null
+  parentId: string | null
+  input: string
+  output: string | null
+  status: 'running' | 'success' | 'error'
+  error: string | null
+  errorType: string | null
+  errorStack: string | null
+  startedAt: Date
+  endedAt: Date | null
+  durationMs: number | null
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+  totalCost: number
+  llmCalls: number
+  toolCalls: number
+  metadata: Record<string, unknown>
+  tags: string[] | null
+  createdAt: Date
+}
+
+export async function GET(req: NextRequest) {
+  // 1. Authenticate (superadmin only)
+  const authResult = await authenticateRequest(req)
+  if (!authResult.success || !authResult.user) {
+    return NextResponse.json(
+      { success: false, error: 'Unauthorized' },
+      { status: 401 }
+    )
+  }
+
+  // Check if user has admin-level access (superadmin or developer)
+  const adminRoles = ['superadmin', 'developer']
+  if (!adminRoles.includes(authResult.user.role)) {
+    return NextResponse.json(
+      { success: false, error: 'Forbidden: Admin access required' },
+      { status: 403 }
+    )
+  }
+
+  try {
+    // 2. Parse query parameters
+    const { searchParams } = new URL(req.url)
+    const status = searchParams.get('status')
+    const agent = searchParams.get('agent')
+    const teamId = searchParams.get('teamId')
+    const from = searchParams.get('from')
+    const to = searchParams.get('to')
+    const limit = Math.min(parseInt(searchParams.get('limit') || '50'), 100)
+    const cursor = searchParams.get('cursor')
+
+    // 3. Build query
+    const conditions: string[] = []
+    const params: unknown[] = []
+    let paramIndex = 1
+
+    if (status) {
+      conditions.push(`status = $${paramIndex}`)
+      params.push(status)
+      paramIndex++
+    }
+
+    if (agent) {
+      conditions.push(`"agentName" = $${paramIndex}`)
+      params.push(agent)
+      paramIndex++
+    }
+
+    if (teamId) {
+      conditions.push(`"teamId" = $${paramIndex}`)
+      params.push(teamId)
+      paramIndex++
+    }
+
+    if (from) {
+      conditions.push(`"startedAt" >= $${paramIndex}`)
+      params.push(from)
+      paramIndex++
+    }
+
+    if (to) {
+      conditions.push(`"startedAt" <= $${paramIndex}`)
+      params.push(to)
+      paramIndex++
+    }
+
+    if (cursor) {
+      conditions.push(`"createdAt" < $${paramIndex}`)
+      params.push(cursor)
+      paramIndex++
+    }
+
+    // Always filter to show only root traces (no parent)
+    conditions.push(`"parentId" IS NULL`)
+
+    const whereClause = `WHERE ${conditions.join(' AND ')}`
+
+    // Add limit + 1 to check if there are more results
+    params.push(limit + 1)
+    const limitClause = `LIMIT $${paramIndex}`
+
+    const query = `
+      SELECT
+        "traceId",
+        "userId",
+        "teamId",
+        "sessionId",
+        "agentName",
+        "agentType",
+        "parentId",
+        input,
+        output,
+        status,
+        error,
+        "errorType",
+        "errorStack",
+        "startedAt",
+        "endedAt",
+        "durationMs",
+        "inputTokens",
+        "outputTokens",
+        "totalTokens",
+        "totalCost",
+        "llmCalls",
+        "toolCalls",
+        metadata,
+        tags,
+        "createdAt"
+      FROM public."langchain_traces"
+      ${whereClause}
+      ORDER BY "createdAt" DESC
+      ${limitClause}
+    `
+
+    const rows = await queryWithRLS<TraceRow>(query, params, authResult.user.id)
+
+    // Check if there are more results
+    const hasMore = rows.length > limit
+    const traces = hasMore ? rows.slice(0, limit) : rows
+    const nextCursor = hasMore ? traces[traces.length - 1].createdAt.toISOString() : undefined
+
+    // 4. Format response
+    const formattedTraces: Trace[] = traces.map((row) => ({
+      traceId: row.traceId,
+      userId: row.userId,
+      teamId: row.teamId,
+      sessionId: row.sessionId || undefined,
+      agentName: row.agentName,
+      agentType: row.agentType || undefined,
+      parentId: row.parentId || undefined,
+      input: row.input,
+      output: row.output || undefined,
+      status: row.status,
+      error: row.error || undefined,
+      errorType: row.errorType || undefined,
+      errorStack: row.errorStack || undefined,
+      startedAt: row.startedAt.toISOString(),
+      endedAt: row.endedAt?.toISOString(),
+      durationMs: row.durationMs || undefined,
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      totalTokens: row.totalTokens,
+      totalCost: row.totalCost,
+      llmCalls: row.llmCalls,
+      toolCalls: row.toolCalls,
+      metadata: row.metadata,
+      tags: row.tags || undefined,
+      createdAt: row.createdAt.toISOString(),
+    }))
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        traces: formattedTraces,
+        hasMore,
+        nextCursor,
+      },
+    })
+  } catch (error) {
+    console.error('[Observability API] List traces error:', error)
+    return NextResponse.json(
+      { success: false, error: 'Failed to list traces' },
+      { status: 500 }
+    )
+  }
+}

package/api/sessions/route.ts

@@ -0,0 +1,332 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { dbMemoryStore, CONVERSATION_LIMITS } from '../../lib/db-memory-store'
+import { config } from '../../plugin.config'
+import type {
+    CreateConversationRequest,
+    UpdateConversationRequest,
+    ConversationInfo,
+} from '../../types/langchain.types'
+
+/**
+ * Convert Date to ISO string for API responses
+ */
+function toApiConversationInfo(conv: {
+    sessionId: string
+    name: string | null
+    messageCount: number
+    firstMessage: string | null
+    isPinned: boolean
+    createdAt: Date
+    updatedAt: Date
+}): ConversationInfo {
+    return {
+        ...conv,
+        createdAt: conv.createdAt.toISOString(),
+        updatedAt: conv.updatedAt.toISOString(),
+    }
+}
+
+/**
+ * GET - List all conversations or get single conversation
+ *
+ * Query params:
+ * - id: Session ID to get specific conversation
+ *
+ * Without id: returns list of all conversations
+ * With id: returns single conversation details
+ */
+export async function GET(req: NextRequest) {
+    // 1. Auth
+    const authResult = await authenticateRequest(req)
+    if (!authResult.success || !authResult.user) {
+        return NextResponse.json(
+            { success: false, error: 'Unauthorized' },
+            { status: 401 }
+        )
+    }
+
+    const userId = authResult.user.id
+
+    // 2. Team context
+    const teamId = req.headers.get('x-team-id')
+    if (!teamId) {
+        return NextResponse.json(
+            { success: false, error: 'Team context required', code: 'TEAM_CONTEXT_REQUIRED' },
+            { status: 400 }
+        )
+    }
+
+    const context = { userId, teamId }
+
+    try {
+        // Check if requesting specific session
+        const { searchParams } = new URL(req.url)
+        const sessionId = searchParams.get('id')
+
+        if (sessionId) {
+            // Get single conversation
+            const session = await dbMemoryStore.getSession(sessionId, context)
+
+            if (!session) {
+                return NextResponse.json(
+                    { success: false, error: 'Conversation not found' },
+                    { status: 404 }
+                )
+            }
+
+            return NextResponse.json({
+                success: true,
+                data: toApiConversationInfo(session),
+            })
+        }
+
+        // List all conversations
+        const sessions = await dbMemoryStore.listSessions(context)
+
+        return NextResponse.json({
+            success: true,
+            data: {
+                sessions: sessions.map(toApiConversationInfo),
+                count: sessions.length,
+                maxAllowed: CONVERSATION_LIMITS.MAX_CONVERSATIONS,
+            },
+        })
+    } catch (error) {
+        if (config.debug) {
+            console.error('[LangChain Plugin] List sessions error:', error)
+        }
+        return NextResponse.json(
+            { success: false, error: 'Failed to list conversations' },
+            { status: 500 }
+        )
+    }
+}
+
+/**
+ * POST - Create a new conversation
+ *
+ * Body:
+ * - name: Optional name for the conversation
+ */
+export async function POST(req: NextRequest) {
+    // 1. Auth
+    const authResult = await authenticateRequest(req)
+    if (!authResult.success || !authResult.user) {
+        return NextResponse.json(
+            { success: false, error: 'Unauthorized' },
+            { status: 401 }
+        )
+    }
+
+    const userId = authResult.user.id
+
+    // 2. Team context
+    const teamId = req.headers.get('x-team-id')
+    if (!teamId) {
+        return NextResponse.json(
+            { success: false, error: 'Team context required', code: 'TEAM_CONTEXT_REQUIRED' },
+            { status: 400 }
+        )
+    }
+
+    const context = { userId, teamId }
+
+    try {
+        // 3. Check conversation limit
+        const currentCount = await dbMemoryStore.countSessions(context)
+
+        if (currentCount >= CONVERSATION_LIMITS.MAX_CONVERSATIONS) {
+            const oldestSession = await dbMemoryStore.getOldestSession(context)
+
+            return NextResponse.json({
+                success: false,
+                error: 'CONVERSATION_LIMIT_REACHED',
+                message: `Maximum of ${CONVERSATION_LIMITS.MAX_CONVERSATIONS} conversations reached. Delete an existing conversation to create a new one.`,
+                data: {
+                    currentCount,
+                    maxAllowed: CONVERSATION_LIMITS.MAX_CONVERSATIONS,
+                    oldestSession: oldestSession
+                        ? {
+                              sessionId: oldestSession.sessionId,
+                              name: oldestSession.name,
+                              updatedAt: oldestSession.updatedAt.toISOString(),
+                          }
+                        : null,
+                },
+            }, { status: 400 })
+        }
+
+        // 4. Parse body
+        const body: CreateConversationRequest = await req.json().catch(() => ({}))
+        const { name } = body
+
+        // 5. Create session
+        const result = await dbMemoryStore.createSession(context, name)
+
+        return NextResponse.json({
+            success: true,
+            data: {
+                sessionId: result.sessionId,
+                name: name || null,
+                createdAt: result.createdAt.toISOString(),
+            },
+        }, { status: 201 })
+    } catch (error) {
+        if (config.debug) {
+            console.error('[LangChain Plugin] Create session error:', error)
+        }
+        return NextResponse.json(
+            { success: false, error: 'Failed to create conversation' },
+            { status: 500 }
+        )
+    }
+}
+
+/**
+ * PATCH - Update a conversation (rename, pin/unpin)
+ *
+ * Body:
+ * - sessionId: Session ID to update (required)
+ * - name: New name (optional)
+ * - isPinned: New pin status (optional)
+ */
+export async function PATCH(req: NextRequest) {
+    // 1. Auth
+    const authResult = await authenticateRequest(req)
+    if (!authResult.success || !authResult.user) {
+        return NextResponse.json(
+            { success: false, error: 'Unauthorized' },
+            { status: 401 }
+        )
+    }
+
+    const userId = authResult.user.id
+
+    // 2. Team context
+    const teamId = req.headers.get('x-team-id')
+    if (!teamId) {
+        return NextResponse.json(
+            { success: false, error: 'Team context required', code: 'TEAM_CONTEXT_REQUIRED' },
+            { status: 400 }
+        )
+    }
+
+    const context = { userId, teamId }
+
+    try {
+        // 3. Parse body
+        const body: UpdateConversationRequest = await req.json()
+        const { sessionId, name, isPinned } = body
+
+        if (!sessionId) {
+            return NextResponse.json(
+                { success: false, error: 'Session ID is required' },
+                { status: 400 }
+            )
+        }
+
+        // 4. Check if session exists
+        const existingSession = await dbMemoryStore.getSession(sessionId, context)
+        if (!existingSession) {
+            return NextResponse.json(
+                { success: false, error: 'Conversation not found' },
+                { status: 404 }
+            )
+        }
+
+        // 5. Update fields
+        if (name !== undefined) {
+            await dbMemoryStore.renameSession(sessionId, name, context)
+        }
+
+        if (isPinned !== undefined) {
+            await dbMemoryStore.togglePinSession(sessionId, isPinned, context)
+        }
+
+        // 6. Get updated session
+        const updatedSession = await dbMemoryStore.getSession(sessionId, context)
+
+        return NextResponse.json({
+            success: true,
+            data: updatedSession ? toApiConversationInfo(updatedSession) : null,
+        })
+    } catch (error) {
+        if (config.debug) {
+            console.error('[LangChain Plugin] Update session error:', error)
+        }
+        return NextResponse.json(
+            { success: false, error: 'Failed to update conversation' },
+            { status: 500 }
+        )
+    }
+}
+
+/**
+ * DELETE - Delete a conversation
+ *
+ * Body:
+ * - sessionId: Session ID to delete (required)
+ */
+export async function DELETE(req: NextRequest) {
+    // 1. Auth
+    const authResult = await authenticateRequest(req)
+    if (!authResult.success || !authResult.user) {
+        return NextResponse.json(
+            { success: false, error: 'Unauthorized' },
+            { status: 401 }
+        )
+    }
+
+    const userId = authResult.user.id
+
+    // 2. Team context
+    const teamId = req.headers.get('x-team-id')
+    if (!teamId) {
+        return NextResponse.json(
+            { success: false, error: 'Team context required', code: 'TEAM_CONTEXT_REQUIRED' },
+            { status: 400 }
+        )
+    }
+
+    const context = { userId, teamId }
+
+    try {
+        // 3. Parse body
+        const body: { sessionId?: string } = await req.json()
+        const { sessionId } = body
+
+        if (!sessionId) {
+            return NextResponse.json(
+                { success: false, error: 'Session ID is required' },
+                { status: 400 }
+            )
+        }
+
+        // 4. Check if session exists
+        const existingSession = await dbMemoryStore.getSession(sessionId, context)
+        if (!existingSession) {
+            return NextResponse.json(
+                { success: false, error: 'Conversation not found' },
+                { status: 404 }
+            )
+        }
+
+        // 5. Delete session
+        await dbMemoryStore.clearSession(sessionId, context)
+
+        return NextResponse.json({
+            success: true,
+            message: 'Conversation deleted successfully',
+            sessionId,
+        })
+    } catch (error) {
+        if (config.debug) {
+            console.error('[LangChain Plugin] Delete session error:', error)
+        }
+        return NextResponse.json(
+            { success: false, error: 'Failed to delete conversation' },
+            { status: 500 }
+        )
+    }
+}

package/components/observability/CollapsibleJson.tsx

@@ -0,0 +1,71 @@
+'use client'
+
+import { useState } from 'react'
+import { useTranslations } from 'next-intl'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+
+interface CollapsibleJsonProps {
+  data: unknown
+  maxPreviewLength?: number
+  className?: string
+}
+
+/**
+ * Collapsible JSON viewer that shows a truncated preview by default.
+ * Useful for long JSON objects in conversation flows.
+ */
+export function CollapsibleJson({ data, maxPreviewLength = 100, className = '' }: CollapsibleJsonProps) {
+  const t = useTranslations('observability')
+  const [isExpanded, setIsExpanded] = useState(false)
+
+  // Format the JSON
+  const formattedJson = JSON.stringify(data, null, 2)
+
+  // Check if content is long enough to need collapsing
+  const needsCollapsing = formattedJson.length > maxPreviewLength
+
+  // Create preview (first maxPreviewLength chars + ellipsis)
+  const preview = needsCollapsing
+    ? formattedJson.slice(0, maxPreviewLength) + '...'
+    : formattedJson
+
+  // Check if content contains error-related keywords
+  const hasError =
+    formattedJson.toLowerCase().includes('"error"') ||
+    formattedJson.toLowerCase().includes('"error_type"') ||
+    formattedJson.toLowerCase().includes('failed') ||
+    formattedJson.toLowerCase().includes('exception')
+
+  const textColorClass = hasError
+    ? 'text-destructive'
+    : 'text-foreground'
+
+  const bgColorClass = hasError
+    ? 'bg-destructive/10'
+    : 'bg-muted'
+
+  if (!needsCollapsing) {
+    return (
+      <pre className={`text-xs p-2 rounded overflow-x-auto whitespace-pre-wrap ${bgColorClass} ${textColorClass} ${className}`}>
+        {formattedJson}
+      </pre>
+    )
+  }
+
+  return (
+    <div className={className}>
+      <pre className={`text-xs p-2 rounded overflow-x-auto whitespace-pre-wrap ${bgColorClass} ${textColorClass}`}>
+        {isExpanded ? formattedJson : preview}
+      </pre>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => setIsExpanded(!isExpanded)}
+        className="mt-1 h-6 text-xs"
+        data-cy="toggle-json"
+      >
+        {isExpanded ? t('flow.collapse') : t('flow.showFull')}
+      </Button>
+    </div>
+  )
+}

package/components/observability/CompactTimeline.tsx

@@ -0,0 +1,75 @@
+'use client'
+
+import type { Span } from '../../types/observability.types'
+
+interface CompactTimelineProps {
+  spans: Span[]
+  className?: string
+}
+
+/**
+ * Compact horizontal timeline showing execution flow with icons.
+ * Shows: User → LLM → Tool (name) ✓/✗ → LLM → Response
+ */
+export function CompactTimeline({ spans, className = '' }: CompactTimelineProps) {
+  // Filter to show only meaningful spans (LLM and tool)
+  const meaningfulSpans = spans.filter(
+    (span) => span.type === 'llm' || span.type === 'tool'
+  )
+
+  if (meaningfulSpans.length === 0) {
+    return null
+  }
+
+  const getSpanIcon = (span: Span) => {
+    if (span.type === 'llm') return '🧠'
+    if (span.type === 'tool') return '🔧'
+    return '📦'
+  }
+
+  const getStatusIcon = (status: string) => {
+    if (status === 'success') return '✓'
+    if (status === 'error') return '✗'
+    return '...'
+  }
+
+  const getStatusColor = (status: string) => {
+    if (status === 'success') return 'text-green-600 dark:text-green-400'
+    if (status === 'error') return 'text-red-600 dark:text-red-400'
+    return 'text-yellow-600 dark:text-yellow-400'
+  }
+
+  return (
+    <div className={`flex flex-wrap items-center gap-1 text-sm ${className}`} data-cy="compact-timeline">
+      {/* User icon at start */}
+      <span className="text-base" title="User input">👤</span>
+      <span className="text-muted-foreground">→</span>
+
+      {meaningfulSpans.map((span, index) => (
+        <div key={span.spanId} className="flex items-center gap-1">
+          <span className="text-base" title={span.name}>
+            {getSpanIcon(span)}
+          </span>
+
+          {span.type === 'tool' && span.toolName && (
+            <span className="text-xs text-muted-foreground bg-muted px-1 rounded">
+              {span.toolName}
+            </span>
+          )}
+
+          <span className={`text-xs font-bold ${getStatusColor(span.status)}`}>
+            {getStatusIcon(span.status)}
+          </span>
+
+          {index < meaningfulSpans.length - 1 && (
+            <span className="text-muted-foreground ml-1">→</span>
+          )}
+        </div>
+      ))}
+
+      {/* Response icon at end */}
+      <span className="text-muted-foreground">→</span>
+      <span className="text-base" title="AI Response">🤖</span>
+    </div>
+  )
+}