Add agent validation system with remote API endpoint

Implements agent name validation to prevent invalid agent references:
- New GET /api/agents/validate-name endpoint with 5-min cache
- Client-side validation with graceful network error handling
- Validates against built-in and published agents
- Exits early on unknown agents with clear error message

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

backend/src/api/__tests__/validate-agent-name.test.ts

@@ -0,0 +1,130 @@
+import { AGENT_PERSONAS } from '@codebuff/common/constants/agents'
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  spyOn,
+  mock,
+} from 'bun:test'
+
+import * as agentRegistry from '../../templates/agent-registry'
+import { validateAgentNameHandler } from '../agents'
+
+import type {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+  NextFunction,
+} from 'express'
+
+function createMockReq(query: Record<string, any>): Partial<ExpressRequest> {
+  return { query } as any
+}
+
+function createMockRes() {
+  const res: Partial<ExpressResponse> & {
+    statusCode?: number
+    jsonPayload?: any
+  } = {}
+  res.status = mock((code: number) => {
+    res.statusCode = code
+    return res as ExpressResponse
+  }) as any
+  res.json = mock((payload: any) => {
+    res.jsonPayload = payload
+    return res as ExpressResponse
+  }) as any
+  return res as ExpressResponse & { statusCode?: number; jsonPayload?: any }
+}
+
+const noopNext: NextFunction = () => {}
+
+describe('validateAgentNameHandler', () => {
+  const builtinAgentId = Object.keys(AGENT_PERSONAS)[0] || 'file-picker'
+
+  beforeEach(() => {
+    mock.restore()
+  })
+
+  afterEach(() => {
+    mock.restore()
+  })
+
+  it('returns valid=true for builtin agent ids', async () => {
+    const req = createMockReq({ agentId: builtinAgentId })
+    const res = createMockRes()
+
+    await validateAgentNameHandler(req as any, res as any, noopNext)
+
+    expect(res.status).toHaveBeenCalledWith(200)
+    expect(res.json).toHaveBeenCalled()
+    expect(res.jsonPayload.valid).toBe(true)
+    expect(res.jsonPayload.source).toBe('builtin')
+    expect(res.jsonPayload.normalizedId).toBe(builtinAgentId)
+  })
+
+  it('returns valid=true for published agent ids (publisher/name)', async () => {
+    const agentId = 'codebuff/file-explorer'
+
+    const spy = spyOn(agentRegistry, 'getAgentTemplate')
+    spy.mockResolvedValueOnce({ id: 'codebuff/file-explorer@0.0.1' } as any)
+
+    const req = createMockReq({ agentId })
+    const res = createMockRes()
+
+    await validateAgentNameHandler(req as any, res as any, noopNext)
+
+    expect(spy).toHaveBeenCalledWith(agentId, {})
+    expect(res.status).toHaveBeenCalledWith(200)
+    expect(res.jsonPayload.valid).toBe(true)
+    expect(res.jsonPayload.source).toBe('published')
+    expect(res.jsonPayload.normalizedId).toBe('codebuff/file-explorer@0.0.1')
+  })
+
+  it('returns valid=true for versioned published agent ids (publisher/name@version)', async () => {
+    const agentId = 'codebuff/file-explorer@0.0.1'
+
+    const spy = spyOn(agentRegistry, 'getAgentTemplate')
+    spy.mockResolvedValueOnce({ id: agentId } as any)
+
+    const req = createMockReq({ agentId })
+    const res = createMockRes()
+
+    await validateAgentNameHandler(req as any, res as any, noopNext)
+
+    expect(spy).toHaveBeenCalledWith(agentId, {})
+    expect(res.status).toHaveBeenCalledWith(200)
+    expect(res.jsonPayload.valid).toBe(true)
+    expect(res.jsonPayload.source).toBe('published')
+    expect(res.jsonPayload.normalizedId).toBe(agentId)
+  })
+
+  it('returns valid=false for unknown agents', async () => {
+    const agentId = 'someorg/not-a-real-agent'
+
+    const spy = spyOn(agentRegistry, 'getAgentTemplate')
+    spy.mockResolvedValueOnce(null)
+
+    const req = createMockReq({ agentId })
+    const res = createMockRes()
+
+    await validateAgentNameHandler(req as any, res as any, noopNext)
+
+    expect(spy).toHaveBeenCalledWith(agentId, {})
+    expect(res.status).toHaveBeenCalledWith(200)
+    expect(res.jsonPayload.valid).toBe(false)
+  })
+
+  it('returns 400 for invalid requests (missing agentId)', async () => {
+    const req = createMockReq({})
+    const res = createMockRes()
+
+    await validateAgentNameHandler(req as any, res as any, noopNext)
+
+    // Handler normalizes zod errors to 400
+    expect(res.status).toHaveBeenCalledWith(400)
+    expect(res.jsonPayload.valid).toBe(false)
+    expect(res.jsonPayload.message).toBe('Invalid request')
+  })
+})

backend/src/api/agents.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod/v4'
+import type {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+  NextFunction,
+} from 'express'
+import { logger } from '../util/logger'
+import { AGENT_PERSONAS } from '@codebuff/common/constants/agents'
+import { getAgentTemplate } from '../templates/agent-registry'
+
+// Add short-lived cache for positive validations
+const AGENT_VALIDATION_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+type CacheEntry = {
+  result: { valid: true; source?: string; normalizedId?: string }
+  expiresAt: number
+}
+
+const agentValidationCache = new Map<string, CacheEntry>()
+
+// Simple request schema
+const validateAgentRequestSchema = z.object({
+  agentId: z.string().min(1),
+})
+
+// GET /api/agents/validate-name
+export async function validateAgentNameHandler(
+  req: ExpressRequest,
+  res: ExpressResponse,
+  next: NextFunction,
+): Promise<void | ExpressResponse> {
+  try {
+    // Log authentication headers if present (for debugging)
+    const hasAuthHeader = !!req.headers.authorization
+    const hasApiKey = !!req.headers['x-api-key']
+    
+    if (hasAuthHeader || hasApiKey) {
+      logger.info(
+        { 
+          hasAuthHeader,
+          hasApiKey,
+          agentId: req.query.agentId,
+        },
+        'Agent validation request with authentication',
+      )
+    }
+    
+    // Parse from query instead (GET)
+    const { agentId } = validateAgentRequestSchema.parse({
+      agentId: String((req.query as any)?.agentId ?? ''),
+    })
+
+    // Check cache (positive results only)
+    const cached = agentValidationCache.get(agentId)
+    if (cached && cached.expiresAt > Date.now()) {
+      return res.status(200).json({ ...cached.result, cached: true })
+    } else if (cached) {
+      agentValidationCache.delete(agentId)
+    }
+
+    // Check built-in agents first
+    if (AGENT_PERSONAS[agentId as keyof typeof AGENT_PERSONAS]) {
+      const result = { valid: true as const, source: 'builtin', normalizedId: agentId }
+      agentValidationCache.set(agentId, {
+        result,
+        expiresAt: Date.now() + AGENT_VALIDATION_CACHE_TTL_MS,
+      })
+      return res.status(200).json(result)
+    }
+
+    // Check published agents (database)
+    const found = await getAgentTemplate(agentId, {})
+    if (found) {
+      const result = {
+        valid: true as const,
+        source: 'published',
+        normalizedId: found.id,
+      }
+      agentValidationCache.set(agentId, {
+        result,
+        expiresAt: Date.now() + AGENT_VALIDATION_CACHE_TTL_MS,
+      })
+      return res.status(200).json(result)
+    }
+
+    return res.status(200).json({ valid: false })
+  } catch (error) {
+    logger.error(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Error validating agent name',
+    )
+    if (error instanceof z.ZodError) {
+      return res.status(400).json({ valid: false, message: 'Invalid request', issues: error.issues })
+    }
+    next(error)
+    return
+  }
+}

backend/src/index.ts

@@ -10,6 +10,7 @@ import {
   getTracesForUserHandler,
   relabelForUserHandler,
 } from './admin/relabelRuns'
+import { validateAgentNameHandler } from './api/agents'
 import { isRepoCoveredHandler } from './api/org'
 import usageHandler from './api/usage'
 import { checkAdmin } from './util/check-auth'
@@ -35,6 +36,7 @@ app.get('/healthz', (req, res) => {
 
 app.post('/api/usage', usageHandler)
 app.post('/api/orgs/is-repo-covered', isRepoCoveredHandler)
+app.get('/api/agents/validate-name', validateAgentNameHandler)
 
 // Enable CORS for preflight requests to the admin relabel endpoint
 app.options('/api/admin/relabel-for-user', cors())

npm-app/src/__tests__/validate-agent-passthrough.test.ts

@@ -0,0 +1,54 @@
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  spyOn,
+  mock,
+} from 'bun:test'
+
+import { validateAgent } from '../index'
+import * as SpinnerMod from '../utils/spinner'
+
+describe('validateAgent agent pass-through', () => {
+  let fetchSpy: ReturnType<typeof spyOn>
+  let spinnerSpy: ReturnType<typeof spyOn>
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis as any, 'fetch').mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true }),
+    } as any)
+
+    spinnerSpy = spyOn(SpinnerMod.Spinner, 'get').mockReturnValue({
+      start: () => {},
+      stop: () => {},
+    } as any)
+  })
+
+  afterEach(() => {
+    mock.restore()
+  })
+
+  it('passes published agent id unchanged to backend (publisher/name@version)', async () => {
+    const agent = 'codebuff/file-explorer@0.0.1'
+    await validateAgent(agent, {})
+
+    expect(fetchSpy).toHaveBeenCalled()
+    const url = (fetchSpy.mock.calls[0] as any[])[0] as string
+    const u = new URL(url)
+    expect(u.searchParams.get('agentId')).toBe(agent)
+  })
+
+  it('short-circuits when agent is found locally (by id)', async () => {
+    const agent = 'codebuff/file-explorer@0.0.1'
+    fetchSpy.mockClear()
+
+    await validateAgent(agent, {
+      [agent]: { displayName: 'File Explorer' },
+    })
+
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+})