Gateway

# Request lifecycle — every HTTP request passes through in order
1. securityHeaders()       X-Content-Type-Options, HSTS, CSP, X-Frame-Options, Referrer-Policy
2. correlationId()         Reads or generates X-Request-ID, echoes it in response
3. cors()                  Production: ALLOWED_ORIGINS allowlist; dev: allow all
4. express.json()          1 MB limit, captures rawBody for HMAC verification
5. csrfProtection()        Double-submit cookie (Bearer token holders exempt)
6. requestLogger()         Structured JSON log: method / path / status / duration / uid

# Agent-scoped routes add these after global middleware:
7. jwtAuth()               Validates Bearer JWT, attaches req.uid
8. tokenBudget()           Per-user token budget — hard cap → 429, soft cap → override model
9. workspaceResolver()     X-Workspace-Id header → validates membership, attaches req.workspace
10. rateLimiter()          Postgres-backed sliding window (30 req / 60s), in-memory fallback
11. userRateLimit()        In-memory per-uid: USER_RATE_LIMIT_RPM (default 60) + burst (10)
12. requestTimeout()       Hard 120s timeout — SSE streams closed gracefully

// Inbound: client → server
{ type: "message", id: "req-1", agentId: "chad", message: "Hello",
  surface: "chat", surfaceId: "main" }
{ type: "ping" }

// Outbound: server → client
{ type: "connected",        timestamp }
{ type: "session_resolved", id, sessionId, isNew }
{ type: "stream_chunk",     id, content }
{ type: "tool_call",        id, index, toolCallId, name }
{ type: "tool_result",      id, name, durationMs, error }
{ type: "stream_done",      id, content, sessionId, usage, toolsUsed }
{ type: "presence",         agentId, sessionId, status, currentTool }
{ type: "error",            id, message }
{ type: "pong" }

event: session_resolved
data: { "sessionId": "ses_abc", "isNew": true }

event: content
data: { "content": "Here's what I found..." }

event: tool_call
data: { "index": 0, "name": "web_search", "toolCallId": "tc_1" }

event: tool_call_complete
data: { "index": 0, "name": "web_search", "arguments": "{...}" }

event: tool_result
data: { "name": "web_search", "durationMs": 320 }

event: done
data: { "content": "...", "sessionId": "ses_abc", "usage": {...}, "toolsUsed": [...] }

starting → streaming → tool_calling → completed
                                              ↘ error

// GET /health — no auth required
{
  "status": "ok",           // "ok" | "degraded"
  "checks": {
    "typesense": true,
    "postgres": true
  },
  "wsConnections": 42,
  "timestamp": "2026-02-27T12:00:00.000Z"
}

// GET /readiness — Kubernetes probe
{ "ready": true }           // 200 if both Postgres + Typesense reachable, 503 otherwise

// GET /metrics — operational dashboard
{
  "uptime": 86400,
  "wsConnections": 42,
  "tools": 106,
  "skills": 48,
  "sessions": { "active": 15, "total": 1240 },
  "messages": 28400,
  "billing": { "month": "2026-02", "totalCost": 12.40 }
}

// All domain errors extend AppError → structured JSON response
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT",
  "status": 429,
  "details": {
    "retryAfter": 12,
    "limit": 30,
    "window": "60s"
  }
}

// Error subclasses:
// AuthError (401)  ForbiddenError (403)  ValidationError (400)
// NotFoundError (404)  ConflictError (409)  RateLimitError (429)
// AgentError (500)  ToolError (500)  QuotaExceededError (429)
// InferenceError (502)  ConfigError (500)