@elevasis/core 0.1.0

package/src/execution/engine/llm/adapters/server/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-only LLM Adapters
+ *
+ * These adapters use server-only dependencies (betterstack-logger)
+ * and should only be imported from @repo/core/server
+ */
+
+export { OpenAIAdapter, isOpenAIModel, type OpenAIAdapterConfig } from './openai'
+export { OpenRouterAdapter, isOpenRouterModel, type OpenRouterAdapterConfig } from './openrouter'
+export { GoogleAdapter, isGoogleModel, type GoogleAdapterConfig } from './google'
+export { AnthropicAdapter, isAnthropicModel, type AnthropicAdapterConfig } from './anthropic'
+export { createLLMAdapter } from './adapter-factory'

package/src/execution/engine/llm/adapters/server/openai.ts

@@ -0,0 +1,206 @@
+/**
+ * Generic OpenAI Adapter
+ * Stateless translation layer between universal protocol and OpenAI API
+ *
+ * Responsibilities:
+ * 1. Translate LLMGenerateRequest to OpenAI format
+ * 2. Call OpenAI API with structured output
+ * 3. Parse OpenAI response
+ * 4. Translate back to LLMGenerateResponse
+ */
+
+import type OpenAI from 'openai'
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../../types'
+import type { LLMModel, ModelSpecificOptions } from '../../model-info'
+import { getModelInfo } from '../../model-info'
+import { TokenLimitExceededError, LLMResponseParseError } from '../../errors'
+import { bslogExternalServiceError, isSystemError } from '../../../../../platform/utils/server/betterstack-logger'
+import { composeSignal } from './compose-signal'
+import { DEFAULT_LLM_TIMEOUT } from '../../../../../platform/constants/timeouts'
+
+/**
+ * Type guard for errors with HTTP status code (e.g., OpenAI API errors)
+ */
+interface ErrorWithStatus {
+  status: number
+}
+
+function hasStatus(error: unknown): error is ErrorWithStatus {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'status' in error &&
+    typeof (error as ErrorWithStatus).status === 'number'
+  )
+}
+
+/**
+ * OpenAI adapter configuration
+ */
+export interface OpenAIAdapterConfig {
+  apiKey: string
+  model: LLMModel
+  modelOptions?: ModelSpecificOptions
+}
+
+/**
+ * Check if the model and provider combination is for OpenAI
+ *
+ * @param model - Model identifier (e.g., 'gpt-5-mini', 'gpt-4')
+ * @param provider - Provider name
+ * @returns True if this is an OpenAI model configuration
+ */
+export function isOpenAIModel(model: LLMModel, provider: string): boolean {
+  return model.startsWith('gpt-') && provider === 'openai'
+}
+
+/**
+ * Generic OpenAI Adapter - Implements universal protocol
+ * Uses structured output for guaranteed schema compliance
+ */
+export class OpenAIAdapter implements LLMAdapter {
+  private clientPromise: Promise<OpenAI>
+  private model: LLMModel
+  private modelOptions?: ModelSpecificOptions
+
+  constructor(config: OpenAIAdapterConfig) {
+    // Lazy load OpenAI SDK
+    this.clientPromise = import('openai').then(
+      ({ default: OpenAIClass }) =>
+        new OpenAIClass({
+          apiKey: config.apiKey
+        })
+    )
+    this.model = config.model || 'gpt-5.4-mini'
+    this.modelOptions = config.modelOptions
+  }
+
+  /**
+   * Generate structured output from messages using OpenAI
+   *
+   * @param request - Generic generation request
+   * @returns Structured output with usage metadata
+   */
+  async generate<T>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
+    const client = await this.clientPromise
+
+    try {
+      const createParams: OpenAI.Chat.ChatCompletionCreateParams = {
+        model: this.model,
+        messages: request.messages.map((msg) => ({
+          role: msg.role,
+          content: msg.content
+        })),
+        max_completion_tokens: request.maxOutputTokens,
+        response_format: {
+          type: 'json_schema',
+          json_schema: {
+            name: 'llm_response',
+            schema: request.responseSchema as Record<string, unknown>
+          }
+        }
+      }
+
+      // Only add temperature if specified and not default (1)
+      if (request.temperature !== undefined && request.temperature !== 1) {
+        createParams.temperature = request.temperature
+      }
+
+      // Only add topP if specified
+      if (request.topP !== undefined) {
+        createParams.top_p = request.topP
+      }
+
+      // Apply model-specific options if present (type narrowing for union)
+      if (this.modelOptions && 'reasoning_effort' in this.modelOptions) {
+        if (this.modelOptions.reasoning_effort) {
+          createParams.reasoning_effort = this.modelOptions.reasoning_effort
+        }
+      }
+
+      if (this.modelOptions && 'verbosity' in this.modelOptions) {
+        if (this.modelOptions.verbosity) {
+          createParams.verbosity = this.modelOptions.verbosity
+        }
+      }
+
+      const response = await client.chat.completions.create(createParams, {
+        signal: composeSignal(DEFAULT_LLM_TIMEOUT, request.signal)
+      })
+
+      const choice = response.choices[0]
+      if (!choice) {
+        throw new Error('No response from OpenAI')
+      }
+
+      // DETECT TOKEN LIMIT ERROR - OpenAI-specific
+      if (choice.finish_reason === 'length') {
+        const usage = response.usage
+        const reasoningTokens = usage?.completion_tokens_details?.reasoning_tokens || 0
+        const completionTokens = usage?.completion_tokens || 0
+        const modelInfo = getModelInfo(this.model)
+
+        throw new TokenLimitExceededError(
+          `LLM token limit exceeded during generation. ` +
+            `Model consumed all available tokens during reasoning phase with no tokens left for output.`,
+          {
+            model: this.model,
+            maxOutputTokens: request.maxOutputTokens,
+            usedTokens: completionTokens,
+            reasoningTokens,
+            outputTokens: completionTokens - reasoningTokens,
+            recommendation: modelInfo
+              ? `Increase maxOutputTokens to at least ${modelInfo.minTokens} for this model.`
+              : 'Increase maxOutputTokens for this model.'
+          }
+        )
+      }
+
+      // Check for empty content (secondary validation)
+      const content = choice.message.content || '{}'
+
+      // Parse JSON with error wrapping for retry support
+      let output: unknown
+      try {
+        output = JSON.parse(content)
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          throw new LLMResponseParseError(`Failed to parse LLM response as JSON: ${error.message}`, {
+            rawContent: content.substring(0, 500),
+            parseError: error.message
+          })
+        }
+        throw error
+      }
+
+      // Extract usage data from OpenAI response (for wrapper to track)
+      const usage = response.usage
+        ? {
+            inputTokens: response.usage.prompt_tokens,
+            outputTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens
+          }
+        : undefined
+
+      // Return response with usage (wrapper will extract and strip it)
+      return {
+        output: output as T,
+        usage
+      }
+    } catch (error) {
+      // Add Better Stack logging for system errors (5xx only)
+      if (isSystemError(error)) {
+        bslogExternalServiceError('openai', 'chat.completions.create', error as Error, {
+          model: this.model,
+          statusCode: hasStatus(error) ? error.status : undefined,
+          reasoningEffort:
+            this.modelOptions && 'reasoning_effort' in this.modelOptions
+              ? this.modelOptions.reasoning_effort
+              : undefined
+        })
+      }
+
+      throw error
+    }
+  }
+}

package/src/execution/engine/llm/adapters/server/openrouter.ts

@@ -0,0 +1,235 @@
+/**
+ * OpenRouter Adapter
+ * Stateless translation layer between universal protocol and OpenRouter API
+ *
+ * OpenRouter provides access to 400+ LLM models (Claude, Gemini, Llama, etc.)
+ * via an OpenAI-compatible API with a single API key.
+ *
+ * Responsibilities:
+ * 1. Translate LLMGenerateRequest to OpenRouter format
+ * 2. Call OpenRouter API with structured output
+ * 3. Parse OpenRouter response
+ * 4. Translate back to LLMGenerateResponse
+ */
+
+import type OpenAI from 'openai'
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../../types'
+import type { LLMModel, OpenRouterOptions } from '../../model-info'
+import { getModelInfo } from '../../model-info'
+import { TokenLimitExceededError, LLMResponseParseError } from '../../errors'
+import { bslogExternalServiceError, isSystemError } from '../../../../../platform/utils/server/betterstack-logger'
+import { composeSignal } from './compose-signal'
+import { DEFAULT_LLM_TIMEOUT } from '../../../../../platform/constants/timeouts'
+
+/**
+ * Type guard for errors with HTTP status code
+ */
+interface ErrorWithStatus {
+  status: number
+}
+
+function hasStatus(error: unknown): error is ErrorWithStatus {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'status' in error &&
+    typeof (error as ErrorWithStatus).status === 'number'
+  )
+}
+
+/**
+ * OpenRouter-specific extra_body options for usage accounting and routing
+ */
+interface OpenRouterExtraBody {
+  usage?: { include: boolean }
+  transforms?: string[]
+  route?: 'fallback'
+}
+
+/**
+ * Extended params type for OpenRouter with extra_body support
+ */
+type OpenRouterCreateParams = OpenAI.Chat.ChatCompletionCreateParamsNonStreaming & {
+  extra_body?: OpenRouterExtraBody
+}
+
+/**
+ * OpenRouter adapter configuration
+ */
+export interface OpenRouterAdapterConfig {
+  apiKey: string
+  model: LLMModel
+  modelOptions?: OpenRouterOptions
+}
+
+/**
+ * Check if the model is an OpenRouter model
+ *
+ * @param model - Model identifier (e.g., 'openrouter/anthropic/claude-3.5-sonnet')
+ * @returns True if this is an OpenRouter model
+ */
+export function isOpenRouterModel(model: LLMModel): boolean {
+  return typeof model === 'string' && model.startsWith('openrouter/')
+}
+
+/**
+ * OpenRouter Adapter - Implements universal protocol
+ * Uses OpenAI SDK with custom baseURL for OpenRouter API
+ */
+export class OpenRouterAdapter implements LLMAdapter {
+  private clientPromise: Promise<OpenAI>
+  private model: LLMModel
+  private openRouterModel: string
+  private modelOptions?: OpenRouterOptions
+
+  constructor(config: OpenRouterAdapterConfig) {
+    // Strip 'openrouter/' prefix for API calls
+    // e.g., 'openrouter/anthropic/claude-3.5-sonnet' -> 'anthropic/claude-3.5-sonnet'
+    this.openRouterModel = config.model.replace('openrouter/', '')
+    this.model = config.model
+    this.modelOptions = config.modelOptions
+
+    // Lazy load OpenAI SDK with OpenRouter configuration
+    this.clientPromise = import('openai').then(
+      ({ default: OpenAIClass }) =>
+        new OpenAIClass({
+          baseURL: 'https://openrouter.ai/api/v1',
+          apiKey: config.apiKey,
+          defaultHeaders: {
+            'HTTP-Referer': 'https://elevasis.com',
+            'X-Title': 'Elevasis'
+          }
+        })
+    )
+  }
+
+  /**
+   * Generate structured output from messages using OpenRouter
+   *
+   * @param request - Generic generation request
+   * @returns Structured output with usage metadata
+   */
+  async generate<T>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
+    const client = await this.clientPromise
+
+    try {
+      // Build OpenRouter-specific extra_body with usage accounting
+      const extraBody: OpenRouterExtraBody = {
+        usage: { include: true }
+      }
+
+      if (this.modelOptions?.transforms) {
+        extraBody.transforms = this.modelOptions.transforms
+      }
+
+      if (this.modelOptions?.route) {
+        extraBody.route = this.modelOptions.route
+      }
+
+      const createParams: OpenRouterCreateParams = {
+        model: this.openRouterModel,
+        messages: request.messages.map((msg) => ({
+          role: msg.role,
+          content: msg.content
+        })),
+        max_tokens: request.maxOutputTokens,
+        response_format: {
+          type: 'json_schema',
+          json_schema: {
+            name: 'llm_response',
+            strict: true,
+            schema: request.responseSchema as Record<string, unknown>
+          }
+        },
+        extra_body: extraBody
+      }
+
+      // Add temperature if specified
+      if (request.temperature !== undefined) {
+        createParams.temperature = request.temperature
+      }
+
+      // Add topP if specified
+      if (request.topP !== undefined) {
+        createParams.top_p = request.topP
+      }
+
+      const response = await client.chat.completions.create(createParams, {
+        signal: composeSignal(DEFAULT_LLM_TIMEOUT, request.signal)
+      })
+
+      const choice = response.choices[0]
+      if (!choice) {
+        throw new Error('No response from OpenRouter')
+      }
+
+      // Detect token limit error
+      if (choice.finish_reason === 'length') {
+        const usage = response.usage
+        const completionTokens = usage?.completion_tokens || 0
+        const modelInfo = getModelInfo(this.model)
+
+        throw new TokenLimitExceededError(
+          `LLM token limit exceeded during generation. ` +
+            `Model consumed all available tokens with no tokens left for output.`,
+          {
+            model: this.model,
+            maxOutputTokens: request.maxOutputTokens,
+            usedTokens: completionTokens,
+            reasoningTokens: 0, // OpenRouter doesn't expose reasoning tokens
+            outputTokens: completionTokens,
+            recommendation: modelInfo
+              ? `Increase maxOutputTokens to at least ${modelInfo.minTokens} for this model.`
+              : 'Increase maxOutputTokens for this model.'
+          }
+        )
+      }
+
+      // Parse response content with error wrapping for retry support
+      const content = choice.message.content || '{}'
+      let output: unknown
+      try {
+        output = JSON.parse(content)
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          throw new LLMResponseParseError(`Failed to parse LLM response as JSON: ${error.message}`, {
+            rawContent: content.substring(0, 500),
+            parseError: error.message
+          })
+        }
+        throw error
+      }
+
+      // Extract usage data
+      const usage = response.usage
+        ? {
+            inputTokens: response.usage.prompt_tokens,
+            outputTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens
+          }
+        : undefined
+
+      // Extract actual cost from OpenRouter (when usage accounting is enabled)
+      // OpenRouter returns cost in the usage object as an extended field
+      const usageWithCost = response.usage as { cost?: number } | undefined
+      const cost = usageWithCost?.cost
+
+      return {
+        output: output as T,
+        usage,
+        cost
+      }
+    } catch (error) {
+      // Add Better Stack logging for system errors (5xx only)
+      if (isSystemError(error)) {
+        bslogExternalServiceError('openrouter', 'chat.completions.create', error as Error, {
+          model: this.model,
+          openRouterModel: this.openRouterModel,
+          statusCode: hasStatus(error) ? error.status : undefined
+        })
+      }
+
+      throw error
+    }
+  }
+}

package/src/execution/engine/llm/adapters/universal-adapter.ts

@@ -0,0 +1,230 @@
+/**
+ * Universal LLM Adapter
+ * Adds reliability (retry, circuit breaker) and observability (automatic token tracking) to ALL LLM calls
+ */
+
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../types'
+import type { LLMModel } from '../model-info'
+import type { AIUsageCollector } from '../../../../operations/observability/ai-usage-collector'
+import type { AICallContext, BaseAICall } from '../../../../operations/observability/types'
+import { executeWithCircuitBreaker } from './circuit-breaker'
+import { LLMResponseParseError, LLMInputBlockedError } from '../errors'
+import { sanitizeUserInput } from '../input-sanitizer'
+import { validateResponseSchema } from '../response-schema-validator'
+import { LLM_MAX_ATTEMPTS, LLM_RETRY_DELAYS } from '../../../../platform/constants/resilience'
+
+/**
+ * Type guard to check if an object has HTTP status property
+ */
+interface ErrorWithStatus {
+  status: number
+}
+
+/**
+ * Type guard to check if an object has message property
+ */
+interface ErrorWithMessage {
+  message: string
+}
+
+/**
+ * Type guard for error with status
+ */
+function hasStatus(error: unknown): error is ErrorWithStatus {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'status' in error &&
+    typeof (error as ErrorWithStatus).status === 'number'
+  )
+}
+
+/**
+ * Type guard for error with message
+ */
+function hasMessage(error: unknown): error is ErrorWithMessage {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    typeof (error as ErrorWithMessage).message === 'string'
+  )
+}
+
+/**
+ * Universal wrapper that adds reliability + observability to any LLM adapter
+ *
+ * Features:
+ * - Exponential backoff retry (3 attempts: 1s, 2s, 4s)
+ * - Circuit breaker for cascading failure prevention (shared per model)
+ * - Automatic token usage tracking with typed contexts
+ * - Automatic latency tracking
+ *
+ * Implements decorator pattern - delegates to base adapter
+ *
+ * Note: Base adapters may include optional 'usage' field in responses.
+ * This wrapper extracts usage for observability and strips it before returning to callers.
+ */
+export class UniversalLLMAdapter implements LLMAdapter {
+  constructor(
+    private baseAdapter: LLMAdapter,
+    private modelName: LLMModel,
+    private aiUsageCollector?: AIUsageCollector,
+    private callType?: BaseAICall['callType'],
+    private context?: AICallContext
+  ) {}
+
+  async generate<T>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
+    // Sanitize user-role messages BEFORE retry/circuit breaker
+    // Blocked input is not transient (no retry) and not a service failure (no circuit breaker impact)
+    const sanitizedRequest = this.sanitizeRequest(request)
+    return this.withRetryAndTracking(async () => {
+      const response = await this.baseAdapter.generate<T>(sanitizedRequest)
+
+      // Validate output against responseSchema (throws retryable LLMResponseParseError)
+      if (sanitizedRequest.responseSchema) {
+        validateResponseSchema(response.output, sanitizedRequest.responseSchema)
+      }
+
+      return response
+    })
+  }
+
+  /**
+   * Sanitize user-role messages for prompt injection attacks
+   * System and assistant messages are framework-generated and skipped
+   *
+   * @throws LLMInputBlockedError if 3+ distinct attack patterns detected
+   */
+  private sanitizeRequest(request: LLMGenerateRequest): LLMGenerateRequest {
+    return {
+      ...request,
+      messages: request.messages.map((msg) => {
+        if (msg.role !== 'user') return msg
+        const result = sanitizeUserInput(msg.content)
+        if (result.blocked) {
+          throw new LLMInputBlockedError(result.warnings)
+        }
+        return { ...msg, content: result.sanitized }
+      })
+    }
+  }
+
+  /**
+   * Wraps LLM call with retry logic, circuit breaker, and observability tracking
+   *
+   * The circuit breaker wraps the entire retry loop - this ensures that:
+   * - Failures during retries are counted toward the circuit breaker threshold
+   * - The circuit opens after sustained failures across retry attempts
+   * - Success after retries properly records success to the circuit breaker
+   */
+  private async withRetryAndTracking<T>(fn: () => Promise<LLMGenerateResponse<T>>): Promise<LLMGenerateResponse<T>> {
+    // Circuit breaker wraps the entire retry loop
+    return executeWithCircuitBreaker(this.modelName, async () => {
+      // Retry loop (max 3 attempts with exponential backoff)
+      let lastError: unknown
+
+      for (let attempt = 1; attempt <= LLM_MAX_ATTEMPTS; attempt++) {
+        try {
+          // Measure per-attempt latency (not cumulative across retries)
+          const startTime = Date.now()
+
+          // Execute LLM call
+          const response = await fn()
+
+          // Calculate latency for this attempt only
+          const latencyMs = Date.now() - startTime
+
+          // Extract usage from response (if available)
+          if (response.usage && this.aiUsageCollector) {
+            this.aiUsageCollector.record(
+              {
+                model: this.modelName,
+                inputTokens: response.usage.inputTokens,
+                outputTokens: response.usage.outputTokens,
+                latencyMs,
+                cost: response.cost // Pass actual cost from provider (e.g., OpenRouter)
+              },
+              this.callType,
+              this.context
+            )
+          }
+
+          // Return response (usage hidden from callers by TypeScript interface)
+          return response
+        } catch (error) {
+          lastError = error
+
+          // Determine if error is retryable
+          const isRetryable = this.isRetryableError(error)
+
+          if (!isRetryable) {
+            // Non-retryable error (401, 400, etc.) - fail immediately
+            // Let the circuit breaker record this as a failure
+            throw error
+          }
+
+          // Retryable error (429, 500, 503, network) - retry with exponential backoff
+          if (attempt < LLM_MAX_ATTEMPTS) {
+            const delay = LLM_RETRY_DELAYS[attempt - 1]
+            await this.sleep(delay)
+          }
+          // If this was the last attempt, the loop ends and we throw below
+        }
+      }
+
+      // All retries failed - throw to let circuit breaker record failure
+      throw lastError
+    })
+  }
+
+  /**
+   * Determine if error should be retried
+   */
+  private isRetryableError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false
+
+    // LLMResponseParseError is always retryable (transient JSON parse failures)
+    if (error instanceof LLMResponseParseError) {
+      return true
+    }
+
+    // Check for HTTP status codes using type guard
+    if (hasStatus(error)) {
+      const status = error.status
+
+      // Retryable: Rate limits, server errors, service unavailable
+      if (status === 429 || status === 500 || status === 503) {
+        return true
+      }
+
+      // Non-retryable: Auth errors, bad requests
+      if (status === 401 || status === 400 || status === 403) {
+        return false
+      }
+    }
+
+    // Check for network errors using type guard
+    if (hasMessage(error)) {
+      const message = error.message
+      if (
+        message.includes('ECONNRESET') ||
+        message.includes('ETIMEDOUT') ||
+        message.includes('ENOTFOUND') ||
+        message.includes('network')
+      ) {
+        return true
+      }
+    }
+
+    // Default: don't retry unknown errors
+    return false
+  }
+
+  /**
+   * Sleep utility for retry delays
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}