Add /api/agents/metrics endpoint for client-side metrics loading

- New endpoint returns metrics keyed by publisherId/agentName
- Supports progressive loading pattern for store page
- Metrics load client-side while basic agent info loads server-side

Author: brandonkachen

web/src/app/api/agents/metrics/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from 'next/server'
+
+import { logger } from '@/util/logger'
+import { applyCacheHeaders } from '@/server/apply-cache-headers'
+import { getCachedAgentsMetrics } from '@/server/agents-data'
+
+// ISR Configuration for API route - metrics can be cached
+export const revalidate = 600 // Cache for 10 minutes
+export const dynamic = 'force-static'
+
+export async function GET() {
+  try {
+    const metrics = await getCachedAgentsMetrics()
+
+    const response = NextResponse.json(metrics)
+    return applyCacheHeaders(response)
+  } catch (error) {
+    logger.error({ error }, 'Error fetching agent metrics')
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 },
+    )
+  }
+}

web/src/app/store/page.tsx

@@ -1,6 +1,6 @@
 import { Metadata } from 'next'
 import { env } from '@codebuff/common/env'
-import { getCachedAgentsLite } from '@/server/agents-data'
+import { getCachedAgentsBasicInfo } from '@/server/agents-data'
 import AgentStoreClient from './store-client'
 
 interface PublisherProfileResponse {
@@ -16,7 +16,7 @@ export async function generateMetadata(): Promise<Metadata> {
     publisher?: { avatar_url?: string | null }
   }> = []
   try {
-    agents = await getCachedAgentsLite()
+    agents = await getCachedAgentsBasicInfo()
   } catch (error) {
     console.error('[Store] Failed to fetch agents for metadata:', error)
     agents = []
@@ -92,10 +92,11 @@ function StoreJsonLd({ agentCount }: { agentCount: number }) {
 
 export default async function StorePage({ searchParams }: StorePageProps) {
   const resolvedSearchParams = await searchParams
-  // Fetch agents data on the server with ISR cache
+  // Fetch only basic agent info on the server - metrics load client-side
+  // This keeps the initial payload small and cacheable
   let agentsData: any[] = []
   try {
-    agentsData = await getCachedAgentsLite()
+    agentsData = await getCachedAgentsBasicInfo()
   } catch (error) {
     console.error('[Store] Failed to fetch agents data:', error)
     agentsData = []

web/src/app/store/store-client.tsx

@@ -35,7 +35,8 @@ import { cn } from '@/lib/utils'
 import type { Session } from 'next-auth'
 import { create } from 'zustand'
 
-interface AgentData {
+// Basic agent info from SSR (no metrics)
+interface AgentBasicInfo {
   id: string
   name: string
   description?: string
@@ -47,15 +48,29 @@ interface AgentData {
   }
   version: string
   created_at: string
+  tags?: string[]
+}
+
+// Metrics loaded client-side
+interface AgentMetrics {
+  usage_count: number
+  weekly_runs: number
+  weekly_spent: number
+  total_spent: number
+  avg_cost_per_invocation: number
+  unique_users: number
+  last_used?: string
+}
+
+// Combined data for display
+interface AgentData extends AgentBasicInfo {
   usage_count?: number
   weekly_runs?: number
   weekly_spent?: number
   total_spent?: number
   avg_cost_per_invocation?: number
   unique_users?: number
   last_used?: string
-  version_stats?: Record<string, any>
-  tags?: string[]
 }
 
 interface AgentStoreState {
@@ -92,7 +107,7 @@ interface PublisherProfileResponse {
 }
 
 interface AgentStoreClientProps {
-  initialAgents: AgentData[]
+  initialAgents: AgentBasicInfo[]
   initialPublishers: PublisherProfileResponse[]
   session: Session | null
   searchParams: { [key: string]: string | string[] | undefined }
@@ -199,24 +214,42 @@ export default function AgentStoreClient({
     loadingStateRef.current = { isLoadingMore, hasMore }
   }, [isLoadingMore, hasMore])
 
-  // Hydrate agents client-side if SSR provided none (build-time fallback)
-  const { data: hydratedAgents } = useQuery<AgentData[]>({
-    queryKey: ['agents'],
+  // Fetch metrics client-side - this is the progressive loading part
+  const { data: metricsMap, isLoading: isLoadingMetrics } = useQuery<
+    Record<string, AgentMetrics>
+  >({
+    queryKey: ['agents-metrics'],
     queryFn: async () => {
-      const response = await fetch('/api/agents')
+      const response = await fetch('/api/agents/metrics')
       if (!response.ok) {
-        throw new Error(`Failed to fetch agents: ${response.statusText}`)
+        throw new Error(`Failed to fetch metrics: ${response.statusText}`)
       }
       return response.json()
     },
-    enabled: (initialAgents?.length ?? 0) === 0,
     staleTime: 600000, // 10 minutes
   })
 
-  // Prefer hydrated data if present; else use SSR data
-  const agents = useMemo(() => {
-    return hydratedAgents ?? initialAgents
-  }, [hydratedAgents, initialAgents])
+  // Combine basic agent info with metrics when available
+  const agents: AgentData[] = useMemo(() => {
+    if (!initialAgents?.length) return []
+
+    return initialAgents.map((agent) => {
+      // Key matches how metrics are stored: publisherId/agentName
+      const metricsKey = `${agent.publisher.id}/${agent.name}`
+      const metrics = metricsMap?.[metricsKey]
+
+      return {
+        ...agent,
+        usage_count: metrics?.usage_count,
+        weekly_runs: metrics?.weekly_runs,
+        weekly_spent: metrics?.weekly_spent,
+        total_spent: metrics?.total_spent,
+        avg_cost_per_invocation: metrics?.avg_cost_per_invocation,
+        unique_users: metrics?.unique_users,
+        last_used: metrics?.last_used,
+      }
+    })
+  }, [initialAgents, metricsMap])
 
   const editorsChoice = useMemo(() => {
     return agents.filter((agent) => EDITORS_CHOICE_AGENTS.includes(agent.id))
@@ -503,55 +536,75 @@ export default function AgentStoreClient({
                     </Badge>
                   )}
                 </div>
-                {agent.last_used && (
-                  <span
-                    className="text-xs text-muted-foreground/60"
-                    title={new Date(agent.last_used).toLocaleString()}
-                  >
-                    Used <RelativeTime date={agent.last_used} />
-                  </span>
+                {isLoadingMetrics ? (
+                  <div className="h-4 w-20 bg-muted/30 rounded animate-pulse" />
+                ) : (
+                  agent.last_used && (
+                    <span
+                      className="text-xs text-muted-foreground/60"
+                      title={new Date(agent.last_used).toLocaleString()}
+                    >
+                      Used <RelativeTime date={agent.last_used} />
+                    </span>
+                  )
                 )}
               </div>
             </div>
 
-            {/* Metrics Grid - Redesigned for better readability */}
+            {/* Metrics Grid - Shows skeleton while loading */}
             <div className="grid grid-cols-2 gap-3 py-3 border-t border-border/30">
               <div className="space-y-1">
                 <div className="flex items-center gap-2">
                   <TrendingUp className="h-4 w-4 text-emerald-400" />
-                  <span className="font-semibold text-emerald-400">
-                    {formatCurrency(agent.weekly_spent)}
-                  </span>
+                  {isLoadingMetrics ? (
+                    <div className="h-5 w-12 bg-muted/50 rounded animate-pulse" />
+                  ) : (
+                    <span className="font-semibold text-emerald-400">
+                      {formatCurrency(agent.weekly_spent)}
+                    </span>
+                  )}
                 </div>
                 <p className="text-xs text-muted-foreground">Weekly spend</p>
               </div>
 
               <div className="space-y-1">
                 <div className="flex items-center gap-2">
                   <Play className="h-4 w-4 text-muted-foreground" />
-                  <span className="font-semibold">
-                    {formatUsageCount(agent.weekly_runs)}
-                  </span>
+                  {isLoadingMetrics ? (
+                    <div className="h-5 w-10 bg-muted/50 rounded animate-pulse" />
+                  ) : (
+                    <span className="font-semibold">
+                      {formatUsageCount(agent.weekly_runs)}
+                    </span>
+                  )}
                 </div>
                 <p className="text-xs text-muted-foreground">Weekly runs</p>
               </div>
 
               <div className="space-y-1">
                 <div className="flex items-center gap-2">
                   <DollarSign className="h-4 w-4 text-muted-foreground" />
-                  <span className="font-semibold">
-                    {formatCurrency(agent.avg_cost_per_invocation)}
-                  </span>
+                  {isLoadingMetrics ? (
+                    <div className="h-5 w-12 bg-muted/50 rounded animate-pulse" />
+                  ) : (
+                    <span className="font-semibold">
+                      {formatCurrency(agent.avg_cost_per_invocation)}
+                    </span>
+                  )}
                 </div>
                 <p className="text-xs text-muted-foreground">Per run</p>
               </div>
 
               <div className="space-y-1">
                 <div className="flex items-center gap-2">
                   <Users className="h-4 w-4 text-muted-foreground" />
-                  <span className="font-semibold">
-                    {agent.unique_users || 0}
-                  </span>
+                  {isLoadingMetrics ? (
+                    <div className="h-5 w-8 bg-muted/50 rounded animate-pulse" />
+                  ) : (
+                    <span className="font-semibold">
+                      {agent.unique_users || 0}
+                    </span>
+                  )}
                 </div>
                 <p className="text-xs text-muted-foreground">Users</p>
               </div>

web/src/server/__tests__/agents-transform.test.ts

@@ -3,6 +3,7 @@ import {
   buildAgentsData,
   buildAgentsDataLite,
   type AgentRow,
+  type AgentRowSlim,
 } from '../agents-transform'
 
 describe('buildAgentsData', () => {
@@ -262,11 +263,14 @@ describe('buildAgentsData', () => {
 
 describe('buildAgentsDataLite', () => {
   it('dedupes by latest, merges metrics, and omits version_stats', () => {
-    const agents: AgentRow[] = [
+    // AgentRowSlim has pre-extracted fields (name, description, tags) instead of data blob
+    const agents: AgentRowSlim[] = [
       {
         id: 'base',
         version: '1.0.0',
-        data: { name: 'Base', description: 'desc', tags: ['x'] },
+        name: 'Base',
+        description: 'desc',
+        tags: ['x'],
         created_at: '2025-01-01T00:00:00.000Z',
         publisher: {
           id: 'codebuff',
@@ -279,7 +283,9 @@ describe('buildAgentsDataLite', () => {
       {
         id: 'base-old',
         version: '0.9.0',
-        data: { name: 'Base', description: 'old' },
+        name: 'Base',
+        description: 'old',
+        tags: null,
         created_at: '2024-12-01T00:00:00.000Z',
         publisher: {
           id: 'codebuff',
@@ -291,7 +297,9 @@ describe('buildAgentsDataLite', () => {
       {
         id: 'reviewer',
         version: '2.1.0',
-        data: { name: 'Reviewer' },
+        name: 'Reviewer',
+        description: null,
+        tags: null,
         created_at: '2025-01-03T00:00:00.000Z',
         publisher: {
           id: 'codebuff',
@@ -365,11 +373,14 @@ describe('buildAgentsDataLite', () => {
   })
 
   it('handles missing metrics gracefully and omits version_stats', () => {
-    const agents = [
+    // AgentRowSlim with null name (should fall back to id)
+    const agents: AgentRowSlim[] = [
       {
         id: 'solo',
         version: '0.1.0',
-        data: { description: 'no name provided' },
+        name: null,
+        description: 'no name provided',
+        tags: null,
         created_at: new Date('2025-02-01T00:00:00.000Z'),
         publisher: {
           id: 'codebuff',
@@ -378,7 +389,7 @@ describe('buildAgentsDataLite', () => {
           avatar_url: null,
         },
       },
-    ] as any
+    ]
 
     const out = buildAgentsDataLite({
       agents,