@open-mercato/ai-assistant 0.4.9-develop-de525127d6 → 0.4.9-develop-31d1a87765

package/src/modules/ai_assistant/lib/http-server.ts

@@ -12,6 +12,7 @@ import { jsonSchemaToZod, toSafeZodSchema } from './schema-utils'
 import type { McpServerConfig, McpToolContext } from './types'
 import type { SearchService } from '@open-mercato/search/service'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import type { ApiKey } from '@open-mercato/core/modules/api_keys/data/entities'
 import { findApiKeyBySecret, findSessionApiKeyWithSecret } from '@open-mercato/core/modules/api_keys/services/apiKeyService'
 
 /**
@@ -90,6 +91,56 @@ async function resolveSessionContext(
   }
 }
 
+/**
+ * Resolve user context from the server-level API key (header-based auth fallback).
+ * Used when no session token is provided — loads the API key's ACL for RBAC.
+ */
+async function resolveApiKeyContext(
+  apiKeyRecord: ApiKey,
+  baseContext: McpToolContext,
+  debug?: boolean
+): Promise<McpToolContext | null> {
+  try {
+    const rbacService = baseContext.container.resolve<RbacService>('rbacService')
+    const userId = apiKeyRecord.sessionUserId ?? apiKeyRecord.createdBy
+    if (!userId) {
+      if (debug) {
+        console.error(`[MCP HTTP] API key has no associated user`)
+      }
+      return null
+    }
+
+    const acl = await rbacService.loadAcl(`api_key:${apiKeyRecord.id}`, {
+      tenantId: apiKeyRecord.tenantId ?? null,
+      organizationId: apiKeyRecord.organizationId ?? null,
+    })
+
+    if (debug) {
+      console.error(`[MCP HTTP] API key context resolved for user ${userId}:`, {
+        tenantId: apiKeyRecord.tenantId,
+        organizationId: apiKeyRecord.organizationId,
+        features: acl.features.length,
+        isSuperAdmin: acl.isSuperAdmin,
+      })
+    }
+
+    return {
+      tenantId: apiKeyRecord.tenantId ?? null,
+      organizationId: apiKeyRecord.organizationId ?? null,
+      userId,
+      container: baseContext.container,
+      userFeatures: acl.features,
+      isSuperAdmin: acl.isSuperAdmin,
+      apiKeySecret: baseContext.apiKeySecret,
+    }
+  } catch (error) {
+    if (debug) {
+      console.error(`[MCP HTTP] Error resolving API key context:`, error)
+    }
+    return null
+  }
+}
+
 /**
  * Create a stateless MCP server instance for a single request.
  * Tools are registered without pre-filtering - permission checks happen at execution time
@@ -97,7 +148,8 @@ async function resolveSessionContext(
  */
 function createMcpServerForRequest(
   config: McpServerConfig,
-  toolContext: McpToolContext
+  toolContext: McpToolContext,
+  apiKeyRecord: ApiKey
 ): McpServer {
   const server = new McpServer(
     { name: config.name, version: config.version },
@@ -130,7 +182,7 @@ function createMcpServerForRequest(
         const properties = (jsonSchema.properties ?? {}) as Record<string, unknown>
         properties._sessionToken = {
           type: 'string',
-          description: 'Session authorization token (REQUIRED for all tool calls)',
+          description: 'Session authorization token. If omitted, the server API key roles are used instead.',
         }
         jsonSchema.properties = properties
 
@@ -183,8 +235,8 @@ function createMcpServerForRequest(
           if (sessionToken) {
             const sessionContext = await resolveSessionContext(sessionToken, toolContext, config.debug)
             if (sessionContext) {
-              // Session context includes the decrypted API key secret
-              effectiveContext = sessionContext
+              // Session context includes the decrypted API key secret + session ID for memory layer
+              effectiveContext = { ...sessionContext, sessionId: sessionToken }
             } else {
               // Session token expired - return user-friendly error for AI to relay
               return {
@@ -201,14 +253,17 @@ function createMcpServerForRequest(
               }
             }
           } else {
-            // No session token provided - reject if base context has no permissions
-            if (!effectiveContext.userId && effectiveContext.userFeatures.length === 0) {
+            // No session token — fall back to header API key auth
+            const apiKeyContext = await resolveApiKeyContext(apiKeyRecord, toolContext, config.debug)
+            if (apiKeyContext) {
+              effectiveContext = apiKeyContext
+            } else if (!effectiveContext.userId && effectiveContext.userFeatures.length === 0) {
               return {
                 content: [
                   {
                     type: 'text' as const,
                     text: JSON.stringify({
-                      error: 'Session token required (_sessionToken parameter)',
+                      error: 'Authentication failed: provide a session token (_sessionToken) or a valid API key with assigned roles',
                       code: 'UNAUTHORIZED',
                     }),
                   },
@@ -216,6 +271,15 @@ function createMcpServerForRequest(
                 isError: true,
               }
             }
+
+            // Derive a fallback sessionId from the API key so all tool calls
+            // within the same MCP connection share a session memory cache
+            if (!effectiveContext.sessionId && effectiveContext.apiKeySecret) {
+              effectiveContext = {
+                ...effectiveContext,
+                sessionId: 'apikey_' + effectiveContext.apiKeySecret.slice(0, 16),
+              }
+            }
           }
 
           // Check if user has required permissions for this tool
@@ -358,6 +422,19 @@ export async function runMcpHttpServer(options: McpHttpServerOptions): Promise<v
     console.error('[MCP HTTP] Entity graph generation skipped:', error instanceof Error ? error.message : error)
   }
 
+  // Pre-cache rich OpenAPI spec for Code Mode search tool (prefers runtime module registry over static JSON)
+  try {
+    const { loadRichOpenApiSpec } = await import('./api-endpoint-index')
+    const spec = await loadRichOpenApiSpec()
+    if (spec) {
+      console.error('[MCP HTTP] Rich OpenAPI spec cached for Code Mode (with requestBody schemas)')
+    } else {
+      console.error('[MCP HTTP] OpenAPI spec not available')
+    }
+  } catch (error) {
+    console.error('[MCP HTTP] OpenAPI spec caching skipped:', error instanceof Error ? error.message : error)
+  }
+
   // Index tools, API endpoints, and entity schemas for hybrid search discovery (if search service available)
   try {
     const searchService = container.resolve('searchService') as SearchService
@@ -460,7 +537,7 @@ export async function runMcpHttpServer(options: McpHttpServerOptions): Promise<v
       })
 
       // Create new server for this request
-      const mcpServer = createMcpServerForRequest(config, toolContext)
+      const mcpServer = createMcpServerForRequest(config, toolContext, apiKeyRecord)
 
       if (config.debug) {
         // Check registered tools on the server
@@ -521,7 +598,7 @@ export async function runMcpHttpServer(options: McpHttpServerOptions): Promise<v
   console.error(`[MCP HTTP] Tools registered: ${toolCount}`)
   console.error(`[MCP HTTP] Mode: Stateless (new server per request)`)
   console.error(`[MCP HTTP] Server Auth: API key validated against database (x-api-key header)`)
-  console.error(`[MCP HTTP] User Auth: Session token in _sessionToken parameter`)
+  console.error(`[MCP HTTP] User Auth: Session token (_sessionToken) preferred, falls back to API key roles`)
 
   // Return a Promise that keeps the process alive until shutdown
   return new Promise<void>((resolve) => {

package/src/modules/ai_assistant/lib/mcp-dev-server.ts

@@ -265,6 +265,19 @@ export async function runMcpDevServer(): Promise<void> {
     log('Entity graph generation skipped:', error instanceof Error ? error.message : error)
   }
 
+  // Pre-cache rich OpenAPI spec for Code Mode search tool (prefers runtime module registry over static JSON)
+  try {
+    const { loadRichOpenApiSpec } = await import('./api-endpoint-index')
+    const spec = await loadRichOpenApiSpec()
+    if (spec) {
+      log('Rich OpenAPI spec cached for Code Mode (with requestBody schemas)')
+    } else {
+      log('OpenAPI spec not available')
+    }
+  } catch (error) {
+    log('OpenAPI spec caching skipped:', error instanceof Error ? error.message : error)
+  }
+
   // Index tools, API endpoints, and entity schemas for search (if search service available)
   try {
     const searchService = container.resolve('searchService') as SearchService
@@ -294,6 +307,11 @@ export async function runMcpDevServer(): Promise<void> {
     log('Search indexing skipped (search service not available)')
   }
 
+  // Generate a stable session ID for dev mode (enables session memory / caching)
+  const { randomBytes } = await import('node:crypto')
+  const devSessionId = 'dev_' + randomBytes(8).toString('hex')
+  log(`Session ID: ${devSessionId} (stable for this server instance)`)
+
   // Create tool context from auth result
   const toolContext: McpToolContext = {
     tenantId: authResult.tenantId,
@@ -303,6 +321,7 @@ export async function runMcpDevServer(): Promise<void> {
     userFeatures: authResult.features,
     isSuperAdmin: authResult.isSuperAdmin,
     apiKeySecret: apiKey,
+    sessionId: devSessionId,
   }
 
   const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {

package/src/modules/ai_assistant/lib/mcp-server.ts

@@ -160,6 +160,27 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
  * 2. Manual context: Provide `context` with tenant/org/user
  */
 export async function runMcpServer(options: McpServerOptions): Promise<void> {
+  // Generate entity graph for Code Mode search tool
+  try {
+    const { extractEntityGraph, cacheEntityGraph } = await import('./entity-graph')
+    const { getOrm } = await import('@open-mercato/shared/lib/db/mikro')
+    const orm = await getOrm()
+    const graph = await extractEntityGraph(orm)
+    cacheEntityGraph(graph)
+    console.error(`[MCP Server] Entity graph: ${graph.nodes.length} entities`)
+  } catch (error) {
+    console.error('[MCP Server] Entity graph skipped:', error instanceof Error ? error.message : error)
+  }
+
+  // Pre-cache raw OpenAPI spec for Code Mode search tool
+  try {
+    const { getRawOpenApiSpec } = await import('./api-endpoint-index')
+    await getRawOpenApiSpec()
+    console.error('[MCP Server] Raw OpenAPI spec cached for Code Mode')
+  } catch (error) {
+    console.error('[MCP Server] Raw OpenAPI spec caching skipped:', error instanceof Error ? error.message : error)
+  }
+
   // Load tools from all modules before starting
   await loadAllModuleTools()
 

package/src/modules/ai_assistant/lib/opencode-handlers.ts

@@ -251,6 +251,15 @@ export async function handleOpenCodeMessageStreaming(
   const { message, sessionId, model } = request
   const startTime = Date.now()
 
+  // Accumulators for usage summary
+  const usageStats = {
+    toolCalls: 0,
+    toolNames: [] as string[],
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    messageCount: 0,
+  }
+
   if (!message) {
     await onEvent({ type: 'error', error: 'Message is required' })
     return
@@ -332,6 +341,8 @@ export async function handleOpenCodeMessageStreaming(
             } else if (status.status === 'idle') {
               // Session is explicitly idle and no questions - complete
               resolved = true
+              const durationMs = Date.now() - startTime
+              console.error(`[AI Usage] Session complete (heartbeat): sessionId=${targetSessionId.slice(0, 16)}... duration=${durationMs}ms tokens={in:${usageStats.totalInputTokens},out:${usageStats.totalOutputTokens}} toolCalls=${usageStats.toolCalls} tools=[${usageStats.toolNames.join(',')}] messages=${usageStats.messageCount}`)
               try {
                 await onEvent({ type: 'done', sessionId: targetSessionId })
               } catch (err) {
@@ -457,6 +468,8 @@ export async function handleOpenCodeMessageStreaming(
                         } else {
                           // Truly idle - complete the stream
                           resolved = true
+                          const durationMs = Date.now() - startTime
+                          console.error(`[AI Usage] Session complete: sessionId=${targetSessionId.slice(0, 16)}... duration=${durationMs}ms tokens={in:${usageStats.totalInputTokens},out:${usageStats.totalOutputTokens}} toolCalls=${usageStats.toolCalls} tools=[${usageStats.toolNames.join(',')}] messages=${usageStats.messageCount}`)
                           await onEvent({ type: 'done', sessionId: targetSessionId })
                           cleanup()
                           clearTimeout(timeout)
@@ -517,6 +530,15 @@ export async function handleOpenCodeMessageStreaming(
                       provider: info.providerID,
                       tokens: info.tokens,
                     }
+
+                    // Accumulate token usage
+                    usageStats.messageCount++
+                    if (info.tokens) {
+                      usageStats.totalInputTokens += info.tokens.input || 0
+                      usageStats.totalOutputTokens += info.tokens.output || 0
+                      console.error(`[AI Usage] Tokens (message ${usageStats.messageCount}): input=${info.tokens.input} output=${info.tokens.output} model=${info.modelID || 'unknown'}`)
+                    }
+
                     // Emit intermediate metadata for visibility
                     await onEvent({
                       type: 'debug',
@@ -548,8 +570,16 @@ export async function handleOpenCodeMessageStreaming(
                       await onEvent({ type: 'text', content: delta })
                     }
                     break
+                  case 'thinking':
+                    // Extended thinking blocks — route to debug panel only, never to chat
+                    console.error(`[OpenCode SSE] Thinking block received (${(delta || part.text || '').length} chars)`)
+                    await onEvent({ type: 'debug', partType: 'thinking', data: { text: delta || part.text } })
+                    break
                   case 'tool_use':
                     if (part.name) {
+                      usageStats.toolCalls++
+                      usageStats.toolNames.push(part.name)
+                      console.error(`[AI Usage] Tool call #${usageStats.toolCalls}: ${part.name}`)
                       await onEvent({
                         type: 'tool-call',
                         id: part.id,
@@ -572,6 +602,16 @@ export async function handleOpenCodeMessageStreaming(
                 }
                 break
               }
+
+              case 'message.part.delta': {
+                const part = properties.part as { type?: string } | undefined
+                const delta = properties.delta as string | undefined
+                // Filter out thinking deltas — only stream text part deltas to chat
+                if (delta && part?.type !== 'thinking') {
+                  await onEvent({ type: 'text', content: delta })
+                }
+                break
+              }
             }
           } catch (err) {
             console.error('[OpenCode SSE] Error processing event:', err)

package/src/modules/ai_assistant/lib/sandbox.ts

@@ -0,0 +1,192 @@
+/**
+ * Sandboxed Code Execution Engine
+ *
+ * Uses node:vm to run AI-generated JavaScript in a restricted sandbox.
+ * Only whitelisted globals are available — no file system, network, or process access.
+ */
+
+import vm from 'node:vm'
+
+export interface SandboxOptions {
+  /** Execution timeout in milliseconds (default: 30_000) */
+  timeout?: number
+  /** Maximum output size in bytes (default: 1_048_576 / 1MB) */
+  maxOutputSize?: number
+  /** Maximum number of api.request() calls allowed (default: 50) */
+  maxApiCalls?: number
+}
+
+export interface SandboxResult {
+  result: unknown
+  error?: string
+  logs: string[]
+  durationMs: number
+  apiCallCount?: number
+}
+
+const MAX_LOG_ENTRIES = 100
+const MAX_LOG_ENTRY_LENGTH = 1000
+
+/**
+ * Create a sandboxed execution environment.
+ *
+ * @param globals - Custom globals to inject (e.g., spec, api, context)
+ * @param options - Sandbox configuration
+ */
+export function createSandbox(
+  globals: Record<string, unknown>,
+  options: SandboxOptions = {}
+) {
+  const { timeout = 30_000, maxApiCalls = 50 } = options
+
+  return {
+    async execute(code: string): Promise<SandboxResult> {
+      const logs: string[] = []
+      const start = Date.now()
+
+      // Capture console output
+      const consolProxy = {
+        log: (...args: unknown[]) => pushLog(logs, args),
+        info: (...args: unknown[]) => pushLog(logs, args),
+        warn: (...args: unknown[]) => pushLog(logs, args),
+        error: (...args: unknown[]) => pushLog(logs, args),
+        debug: (...args: unknown[]) => pushLog(logs, args),
+      }
+
+      // Build context with safe globals + caller-provided globals
+      const contextGlobals: Record<string, unknown> = {
+        // Safe built-ins
+        JSON,
+        Object,
+        Array,
+        Map,
+        Set,
+        Promise,
+        Math,
+        Date,
+        RegExp,
+        String,
+        Number,
+        Boolean,
+        parseInt,
+        parseFloat,
+        isNaN,
+        isFinite,
+        encodeURIComponent,
+        decodeURIComponent,
+        Error,
+        TypeError,
+        RangeError,
+        undefined,
+        NaN,
+        Infinity,
+
+        // Sandboxed console
+        console: consolProxy,
+
+        // Blocked — explicitly set to undefined
+        require: undefined,
+        process: undefined,
+        global: undefined,
+        globalThis: undefined,
+        fetch: undefined,
+        XMLHttpRequest: undefined,
+        WebSocket: undefined,
+        Buffer: undefined,
+        setTimeout: undefined,
+        setInterval: undefined,
+        __dirname: undefined,
+        __filename: undefined,
+
+        // Caller-provided globals (spec, api, context, etc.)
+        ...globals,
+      }
+
+      const ctx = vm.createContext(contextGlobals)
+
+      try {
+        const normalized = normalizeCode(code)
+
+        // Invoke the normalized async function directly
+        const wrapped = `(${normalized})()`
+
+        const script = new vm.Script(wrapped, {
+          filename: 'sandbox.js',
+        })
+
+        // Run the script — returns a Promise
+        const promise = script.runInContext(ctx, { timeout })
+
+        // Await with secondary timeout (for async operations like api.request)
+        const result = await Promise.race([
+          promise,
+          new Promise((_, reject) =>
+            // Use global setTimeout (not the blocked sandbox one)
+            globalThis.setTimeout(
+              () => reject(new Error(`Execution timed out after ${timeout}ms`)),
+              timeout
+            )
+          ),
+        ])
+
+        return {
+          result,
+          logs,
+          durationMs: Date.now() - start,
+        }
+      } catch (error) {
+        return {
+          result: null,
+          error: error instanceof Error ? error.message : String(error),
+          logs,
+          durationMs: Date.now() - start,
+        }
+      }
+    },
+  }
+}
+
+/**
+ * Normalize AI-generated code: strip markdown fencing and validate shape.
+ */
+export function normalizeCode(code: string): string {
+  let normalized = code.trim()
+
+  // Strip markdown code fences
+  normalized = normalized
+    .replace(/^```(?:javascript|js|typescript|ts)?\s*\n?/i, '')
+    .replace(/\n?```\s*$/, '')
+    .trim()
+
+  // Auto-wrap bare code into async arrow functions
+  if (!/^\s*async\s*\(/.test(normalized)) {
+    // Detect statement-leading keywords — these cannot follow `return`
+    const isStatement = /^\s*(const|let|var|for|while|if|try|switch|return|throw|class|function)\b/.test(normalized)
+    normalized = isStatement
+      ? `async () => { ${normalized} }`
+      : `async () => { return ${normalized} }`
+  }
+
+  return normalized
+}
+
+function pushLog(logs: string[], args: unknown[]): void {
+  if (logs.length >= MAX_LOG_ENTRIES) return
+
+  const message = args
+    .map((arg) => {
+      if (typeof arg === 'string') return arg
+      try {
+        return JSON.stringify(arg)
+      } catch {
+        return String(arg)
+      }
+    })
+    .join(' ')
+
+  logs.push(
+    message.length > MAX_LOG_ENTRY_LENGTH
+      ? message.slice(0, MAX_LOG_ENTRY_LENGTH) + '...'
+      : message
+  )
+}

package/src/modules/ai_assistant/lib/session-memory.ts

@@ -0,0 +1,174 @@
+/**
+ * Session Memory
+ *
+ * Process-level in-memory cache keyed by session token (`sess_xxx`).
+ * Deduplicates schema/spec search queries within a single conversation,
+ * reducing redundant tool calls by the AI agent.
+ *
+ * - Search cache: exact code string match → return cached result (max 50 entries)
+ * - Memory context summary appended to every response to remind the agent
+ * - Sessions auto-expire after 5 minutes (short-lived cache for active conversations)
+ *
+ * NOTE: Only schema/spec lookups are cached. API responses are NEVER cached
+ * because data can change from external sources between calls.
+ */
+
+import { createHash } from 'node:crypto'
+
+const SESSION_TTL_MS = 5 * 60 * 1000 // 5 minutes
+const CLEANUP_INTERVAL_MS = 2 * 60 * 1000 // 2 minutes
+const MAX_SEARCH_ENTRIES = 50
+const MAX_MEMORY_CONTEXT_LENGTH = 500
+
+interface CacheEntry {
+  result: unknown
+  timestamp: number
+  label: string
+}
+
+const TOOL_CALL_HARD_CAP = 10
+const TOOL_CALL_WINDOW_MS = 60 * 1000 // 60 seconds — resets for new user message
+
+interface SessionMemory {
+  searchCache: Map<string, CacheEntry>
+  createdAt: number
+  lastAccessedAt: number
+  toolCallCount: number
+  toolCallWindowStart: number
+}
+
+const sessions = new Map<string, SessionMemory>()
+
+function getOrCreateSession(token: string): SessionMemory {
+  let session = sessions.get(token)
+  if (!session) {
+    session = {
+      searchCache: new Map(),
+      createdAt: Date.now(),
+      lastAccessedAt: Date.now(),
+      toolCallCount: 0,
+      toolCallWindowStart: Date.now(),
+    }
+    sessions.set(token, session)
+  }
+  session.lastAccessedAt = Date.now()
+  return session
+}
+
+function hashCode(code: string): string {
+  return createHash('sha256').update(code).digest('hex').slice(0, 16)
+}
+
+function evictOldest(map: Map<string, CacheEntry>, maxSize: number): void {
+  if (map.size <= maxSize) return
+
+  let oldestKey: string | null = null
+  let oldestTime = Infinity
+
+  for (const [key, entry] of map) {
+    if (entry.timestamp < oldestTime) {
+      oldestTime = entry.timestamp
+      oldestKey = key
+    }
+  }
+
+  if (oldestKey) {
+    map.delete(oldestKey)
+  }
+}
+
+/**
+ * Look up a cached search result by exact code string match.
+ */
+export function lookupSearchCache(token: string, code: string): CacheEntry | null {
+  const session = sessions.get(token)
+  if (!session) return null
+  session.lastAccessedAt = Date.now()
+
+  const key = hashCode(code)
+  return session.searchCache.get(key) ?? null
+}
+
+/**
+ * Store a search result in the session cache.
+ */
+export function storeSearchResult(token: string, code: string, result: unknown, label: string): void {
+  const session = getOrCreateSession(token)
+  const key = hashCode(code)
+
+  evictOldest(session.searchCache, MAX_SEARCH_ENTRIES)
+  session.searchCache.set(key, { result, timestamp: Date.now(), label })
+}
+
+/**
+ * Increment the tool call counter for a session.
+ * Resets the counter if more than TOOL_CALL_WINDOW_MS has elapsed (new user message).
+ * Returns the current count and whether the hard cap has been exceeded.
+ */
+export function incrementToolCallCount(token: string): { count: number; exceeded: boolean } {
+  const session = getOrCreateSession(token)
+  const now = Date.now()
+
+  // Reset counter if the window has expired (likely a new user message)
+  if (now - session.toolCallWindowStart > TOOL_CALL_WINDOW_MS) {
+    session.toolCallCount = 0
+    session.toolCallWindowStart = now
+  }
+
+  session.toolCallCount++
+
+  return {
+    count: session.toolCallCount,
+    exceeded: session.toolCallCount > TOOL_CALL_HARD_CAP,
+  }
+}
+
+/**
+ * Build a summary string of what this session has already discovered.
+ * Appended to tool responses so the agent knows what's cached.
+ */
+export function buildMemoryContext(token: string): string {
+  const session = sessions.get(token)
+  if (!session) return ''
+
+  const searchCount = session.searchCache.size
+  if (searchCount === 0) return ''
+
+  const labels = Array.from(session.searchCache.values())
+    .slice(-3)
+    .map((e) => e.label)
+    .join(', ')
+
+  const context = `[Memory: ${searchCount} schema searches cached (${labels}). Reuse previous schema results instead of re-calling.]`
+  if (context.length > MAX_MEMORY_CONTEXT_LENGTH) {
+    return context.slice(0, MAX_MEMORY_CONTEXT_LENGTH - 3) + '...]'
+  }
+  return context
+}
+
+/**
+ * Build a short label from search code for the memory context summary.
+ */
+export function buildSearchLabel(code: string): string {
+  // Try to extract the helper call: spec.findEndpoints('companies')
+  const helperMatch = code.match(/spec\.(findEndpoints|describeEndpoint|describeEntity)\s*\(([^)]*)\)/)
+  if (helperMatch) {
+    return `${helperMatch[1]}(${helperMatch[2].slice(0, 30)})`
+  }
+
+  // Fallback: first meaningful portion
+  const cleaned = code.replace(/async\s*\(\)\s*=>\s*/, '').trim()
+  return cleaned.slice(0, 40)
+}
+
+// Periodic cleanup of expired sessions
+const cleanupTimer = setInterval(() => {
+  const now = Date.now()
+  for (const [token, session] of sessions) {
+    if (now - session.lastAccessedAt > SESSION_TTL_MS) {
+      sessions.delete(token)
+    }
+  }
+}, CLEANUP_INTERVAL_MS)
+
+cleanupTimer.unref()