@elevasis/core 0.7.1 → 0.8.0

package/src/execution/engine/llm/adapters/circuit-breaker.ts

@@ -1,147 +1,147 @@
-/**
- * LLM-specific Circuit Breaker
- *
- * This module provides LLM-specific circuit breaker functionality by wrapping
- * the generic circuit breaker from @repo/core/resilience.
- *
- * Key design decisions:
- * - CircuitBreakerOpenError extends ExecutionError (not ServiceUnavailableError)
- *   to maintain compatibility with the execution engine's error handling
- * - Uses the generic circuit breaker state machine for consistency
- * - Converts generic ServiceUnavailableError to LLM-specific CircuitBreakerOpenError
- */
-
-import { ExecutionError } from '../../base/errors'
-import {
-  createCircuitBreaker,
-  CircuitState,
-  ServiceUnavailableError,
-  type CircuitBreaker,
-  type CircuitBreakerConfig
-} from '../../../../platform/resilience'
-
-// Re-export CircuitState for backward compatibility
-export { CircuitState as CircuitBreakerState }
-
-// Module-level storage (shared across all executions, one breaker per model)
-const llmCircuitBreakers = new Map<string, CircuitBreaker>()
-
-// Injectable state change handler -- set by server layer via configureCircuitBreakerAlerts()
-let stateChangeHandler: CircuitBreakerConfig['onStateChange'] | undefined
-
-/**
- * Configure the alert handler for LLM circuit breaker state changes.
- * Call once at server startup to wire circuit breaker transitions to Better Stack.
- */
-export function configureCircuitBreakerAlerts(
-  handler: NonNullable<CircuitBreakerConfig['onStateChange']>
-): void {
-  stateChangeHandler = handler
-}
-
-/**
- * Get or create circuit breaker for a model
- */
-export function getCircuitBreaker(modelName: string): CircuitBreaker {
-  if (!llmCircuitBreakers.has(modelName)) {
-    llmCircuitBreakers.set(
-      modelName,
-      createCircuitBreaker(`llm:${modelName}`, { onStateChange: stateChangeHandler })
-    )
-  }
-  return llmCircuitBreakers.get(modelName)!
-}
-
-/**
- * Execute a function through the circuit breaker for a specific model.
- * This is the preferred API - it handles all state transitions automatically.
- *
- * @param modelName - The LLM model name (e.g., 'gpt-4', 'claude-3')
- * @param fn - The async function to execute
- * @returns The result of fn()
- * @throws CircuitBreakerOpenError if the circuit is open
- * @throws The original error from fn() if it fails
- *
- * @example
- * ```typescript
- * const response = await executeWithCircuitBreaker('gpt-4', async () => {
- *   return await openai.chat.completions.create({ ... })
- * })
- * ```
- */
-export async function executeWithCircuitBreaker<T>(
-  modelName: string,
-  fn: () => Promise<T>
-): Promise<T> {
-  const breaker = getCircuitBreaker(modelName)
-
-  try {
-    return await breaker.execute(fn)
-  } catch (error) {
-    // Convert generic ServiceUnavailableError to LLM-specific error
-    if (error instanceof ServiceUnavailableError) {
-      throw new CircuitBreakerOpenError(modelName, {
-        state: breaker.getState(),
-        failureCount: breaker.getFailureCount(),
-        reason: error.reason
-      })
-    }
-    throw error
-  }
-}
-
-/**
- * Error indicating circuit breaker is open for an LLM model.
- *
- * MUST extend ExecutionError for execution engine compatibility.
- * This is separate from ServiceUnavailableError by design.
- *
- * Severity: critical (execution cannot proceed while circuit is open)
- * Category: system (infrastructure/system protection mechanism)
- */
-export class CircuitBreakerOpenError extends ExecutionError {
-  readonly type = 'circuit_breaker_open' as const
-  readonly severity = 'critical' as const
-  readonly category = 'system' as const
-
-  constructor(modelName: string, context?: Record<string, unknown>) {
-    super(`Circuit breaker open for model '${modelName}' - too many recent failures`, {
-      ...context,
-      modelName
-    })
-  }
-
-  override isRetryable(): boolean {
-    return true // Circuit breaker handles retry delay internally
-  }
-}
-
-// ============================================================================
-// Legacy API (for backward compatibility)
-// These functions are kept for API compatibility but delegate to the new implementation
-// ============================================================================
-
-/**
- * Check if circuit breaker allows requests for a model
- * @deprecated Use executeWithCircuitBreaker() instead
- */
-export function canProceed(modelName: string): boolean {
-  const breaker = getCircuitBreaker(modelName)
-  return breaker.getState() !== CircuitState.OPEN
-}
-
-/**
- * Record successful LLM call
- * @deprecated Success is now recorded automatically in executeWithCircuitBreaker()
- */
-export function recordSuccess(_modelName: string): void {
-  // No-op: Success is recorded automatically in breaker.execute()
-}
-
-/**
- * Record failed LLM call
- * @deprecated Failure is now recorded automatically in executeWithCircuitBreaker()
- */
-export function recordFailure(_modelName: string): void {
-  // No-op: Failure is recorded automatically in breaker.execute()
-}
+/**
+ * LLM-specific Circuit Breaker
+ *
+ * This module provides LLM-specific circuit breaker functionality by wrapping
+ * the generic circuit breaker from @repo/core/resilience.
+ *
+ * Key design decisions:
+ * - CircuitBreakerOpenError extends ExecutionError (not ServiceUnavailableError)
+ *   to maintain compatibility with the execution engine's error handling
+ * - Uses the generic circuit breaker state machine for consistency
+ * - Converts generic ServiceUnavailableError to LLM-specific CircuitBreakerOpenError
+ */
+
+import { ExecutionError } from '../../base/errors'
+import {
+  createCircuitBreaker,
+  CircuitState,
+  ServiceUnavailableError,
+  type CircuitBreaker,
+  type CircuitBreakerConfig
+} from '../../../../platform/resilience'
+
+// Re-export CircuitState for backward compatibility
+export { CircuitState as CircuitBreakerState }
+
+// Module-level storage (shared across all executions, one breaker per model)
+const llmCircuitBreakers = new Map<string, CircuitBreaker>()
+
+// Injectable state change handler -- set by server layer via configureCircuitBreakerAlerts()
+let stateChangeHandler: CircuitBreakerConfig['onStateChange'] | undefined
+
+/**
+ * Configure the alert handler for LLM circuit breaker state changes.
+ * Call once at server startup to wire circuit breaker transitions to Better Stack.
+ */
+export function configureCircuitBreakerAlerts(
+  handler: NonNullable<CircuitBreakerConfig['onStateChange']>
+): void {
+  stateChangeHandler = handler
+}
+
+/**
+ * Get or create circuit breaker for a model
+ */
+export function getCircuitBreaker(modelName: string): CircuitBreaker {
+  if (!llmCircuitBreakers.has(modelName)) {
+    llmCircuitBreakers.set(
+      modelName,
+      createCircuitBreaker(`llm:${modelName}`, { onStateChange: stateChangeHandler })
+    )
+  }
+  return llmCircuitBreakers.get(modelName)!
+}
+
+/**
+ * Execute a function through the circuit breaker for a specific model.
+ * This is the preferred API - it handles all state transitions automatically.
+ *
+ * @param modelName - The LLM model name (e.g., 'gpt-4', 'claude-3')
+ * @param fn - The async function to execute
+ * @returns The result of fn()
+ * @throws CircuitBreakerOpenError if the circuit is open
+ * @throws The original error from fn() if it fails
+ *
+ * @example
+ * ```typescript
+ * const response = await executeWithCircuitBreaker('gpt-4', async () => {
+ *   return await openai.chat.completions.create({ ... })
+ * })
+ * ```
+ */
+export async function executeWithCircuitBreaker<T>(
+  modelName: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  const breaker = getCircuitBreaker(modelName)
+
+  try {
+    return await breaker.execute(fn)
+  } catch (error) {
+    // Convert generic ServiceUnavailableError to LLM-specific error
+    if (error instanceof ServiceUnavailableError) {
+      throw new CircuitBreakerOpenError(modelName, {
+        state: breaker.getState(),
+        failureCount: breaker.getFailureCount(),
+        reason: error.reason
+      })
+    }
+    throw error
+  }
+}
+
+/**
+ * Error indicating circuit breaker is open for an LLM model.
+ *
+ * MUST extend ExecutionError for execution engine compatibility.
+ * This is separate from ServiceUnavailableError by design.
+ *
+ * Severity: critical (execution cannot proceed while circuit is open)
+ * Category: system (infrastructure/system protection mechanism)
+ */
+export class CircuitBreakerOpenError extends ExecutionError {
+  readonly type = 'circuit_breaker_open' as const
+  readonly severity = 'critical' as const
+  readonly category = 'system' as const
+
+  constructor(modelName: string, context?: Record<string, unknown>) {
+    super(`Circuit breaker open for model '${modelName}' - too many recent failures`, {
+      ...context,
+      modelName
+    })
+  }
+
+  override isRetryable(): boolean {
+    return true // Circuit breaker handles retry delay internally
+  }
+}
+
+// ============================================================================
+// Legacy API (for backward compatibility)
+// These functions are kept for API compatibility but delegate to the new implementation
+// ============================================================================
+
+/**
+ * Check if circuit breaker allows requests for a model
+ * @deprecated Use executeWithCircuitBreaker() instead
+ */
+export function canProceed(modelName: string): boolean {
+  const breaker = getCircuitBreaker(modelName)
+  return breaker.getState() !== CircuitState.OPEN
+}
+
+/**
+ * Record successful LLM call
+ * @deprecated Success is now recorded automatically in executeWithCircuitBreaker()
+ */
+export function recordSuccess(_modelName: string): void {
+  // No-op: Success is recorded automatically in breaker.execute()
+}
+
+/**
+ * Record failed LLM call
+ * @deprecated Failure is now recorded automatically in executeWithCircuitBreaker()
+ */
+export function recordFailure(_modelName: string): void {
+  // No-op: Failure is recorded automatically in breaker.execute()
+}

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

@@ -1,17 +1,17 @@
-/**
- * LLM Adapters - Browser-safe exports
- *
- * NOTE: Server-only adapters (OpenAIAdapter, OpenRouterAdapter, createLLMAdapter)
- * are exported from @repo/core/server to prevent browser build failures.
- *
- * This file exports only browser-safe utilities and types.
- */
-
-// Browser-safe utilities
-export { CircuitBreakerOpenError } from './circuit-breaker'
-export { UniversalLLMAdapter } from './universal-adapter'
-export { MockAdapter, isMockModel } from './mock-adapter'
-
-// Type-only exports from server (safe for browser - types are erased at runtime)
-export type { OpenAIAdapterConfig } from './server/openai'
-export type { OpenRouterAdapterConfig } from './server/openrouter'
+/**
+ * LLM Adapters - Browser-safe exports
+ *
+ * NOTE: Server-only adapters (OpenAIAdapter, OpenRouterAdapter, createLLMAdapter)
+ * are exported from @repo/core/server to prevent browser build failures.
+ *
+ * This file exports only browser-safe utilities and types.
+ */
+
+// Browser-safe utilities
+export { CircuitBreakerOpenError } from './circuit-breaker'
+export { UniversalLLMAdapter } from './universal-adapter'
+export { MockAdapter, isMockModel } from './mock-adapter'
+
+// Type-only exports from server (safe for browser - types are erased at runtime)
+export type { OpenAIAdapterConfig } from './server/openai'
+export type { OpenRouterAdapterConfig } from './server/openrouter'

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

@@ -1,116 +1,116 @@
-/**
- * Mock LLM Adapter
- * Provides a simple mock implementation for testing purposes
- */
-
-import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../types'
-import type { AgentAction } from '../../agent/actions/types'
-
-/**
- * Mock response for agent iteration scenarios
- */
-export interface MockIterationResponse {
-  reasoning?: string
-  memoryOps?: { set?: Record<string, string>, delete?: string[] }
-  nextActions?: AgentAction[]
-}
-
-/**
- * Configuration for MockAdapter
- * Supports multi-iteration scenarios via response queue
- */
-export interface MockAdapterConfig {
-  // Queue of responses for multi-iteration scenarios
-  responses?: MockIterationResponse[]
-
-  // Completion phase output
-  completionOutput?: unknown
-}
-
-/**
- * Check if the model and provider combination is for Mock
- *
- * @param model - Model identifier (e.g., 'mock')
- * @param provider - Provider name
- * @returns True if this is a mock model configuration
- */
-export function isMockModel(model: string, provider: string): boolean {
-  return model === 'mock' || provider === 'mock'
-}
-
-/**
- * Mock adapter that returns appropriate responses based on request schema
- * Used for testing and development without making real API calls
- *
- * Supports:
- * - Response queue for multi-iteration testing
- * - Call count tracking
- * - Realistic token usage simulation
- * - Backward compatible default behavior
- */
-/**
- * Minimal JSON Schema interface for checking schema structure
- */
-interface JsonSchemaWithProperties {
-  properties?: Record<string, unknown>
-}
-
-export class MockAdapter implements LLMAdapter {
-  private responseQueue: MockIterationResponse[] = []
-  private callCount = 0
-
-  constructor(private config: MockAdapterConfig = {}) {
-    this.responseQueue = [...(config.responses || [])]
-  }
-
-  async generate<T = unknown>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
-    // Check if this is an agent iteration request (has reasoning + nextActions)
-    const schema = request.responseSchema as JsonSchemaWithProperties | undefined
-    const isAgentIteration = schema?.properties?.reasoning && schema?.properties?.nextActions
-
-    this.callCount++
-
-    if (isAgentIteration) {
-      // Use next response from queue, or default to immediate completion
-      const response = this.responseQueue.shift() || {
-        reasoning: 'Mock reasoning',
-        nextActions: [{ type: 'complete' }]
-      }
-
-      // Return agent iteration response
-      return {
-        output: {
-          reasoning: response.reasoning || 'Mock reasoning',
-          memoryOps: response.memoryOps || {},
-          nextActions: response.nextActions || [{ type: 'complete' }]
-        } as T,
-        usage: {
-          inputTokens: 100 * this.callCount,
-          outputTokens: 50 * this.callCount,
-          totalTokens: 150 * this.callCount
-        }
-      }
-    }
-
-    // Return generic completion response
-    return {
-      output: (this.config.completionOutput || {
-        response: 'Mock response',
-        processedAt: new Date().toISOString()
-      }) as T,
-      usage: {
-        inputTokens: 50,
-        outputTokens: 25,
-        totalTokens: 75
-      }
-    }
-  }
-
-  /**
-   * Get total number of generate() calls made
-   * Useful for verifying expected iteration counts in tests
-   */
-  getCallCount(): number {
-    return this.callCount
-  }
-}
+/**
+ * Mock LLM Adapter
+ * Provides a simple mock implementation for testing purposes
+ */
+
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../types'
+import type { AgentAction } from '../../agent/actions/types'
+
+/**
+ * Mock response for agent iteration scenarios
+ */
+export interface MockIterationResponse {
+  reasoning?: string
+  memoryOps?: { set?: Record<string, string>, delete?: string[] }
+  nextActions?: AgentAction[]
+}
+
+/**
+ * Configuration for MockAdapter
+ * Supports multi-iteration scenarios via response queue
+ */
+export interface MockAdapterConfig {
+  // Queue of responses for multi-iteration scenarios
+  responses?: MockIterationResponse[]
+
+  // Completion phase output
+  completionOutput?: unknown
+}
+
+/**
+ * Check if the model and provider combination is for Mock
+ *
+ * @param model - Model identifier (e.g., 'mock')
+ * @param provider - Provider name
+ * @returns True if this is a mock model configuration
+ */
+export function isMockModel(model: string, provider: string): boolean {
+  return model === 'mock' || provider === 'mock'
+}
+
+/**
+ * Mock adapter that returns appropriate responses based on request schema
+ * Used for testing and development without making real API calls
+ *
+ * Supports:
+ * - Response queue for multi-iteration testing
+ * - Call count tracking
+ * - Realistic token usage simulation
+ * - Backward compatible default behavior
+ */
+/**
+ * Minimal JSON Schema interface for checking schema structure
+ */
+interface JsonSchemaWithProperties {
+  properties?: Record<string, unknown>
+}
+
+export class MockAdapter implements LLMAdapter {
+  private responseQueue: MockIterationResponse[] = []
+  private callCount = 0
+
+  constructor(private config: MockAdapterConfig = {}) {
+    this.responseQueue = [...(config.responses || [])]
+  }
+
+  async generate<T = unknown>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
+    // Check if this is an agent iteration request (has reasoning + nextActions)
+    const schema = request.responseSchema as JsonSchemaWithProperties | undefined
+    const isAgentIteration = schema?.properties?.reasoning && schema?.properties?.nextActions
+
+    this.callCount++
+
+    if (isAgentIteration) {
+      // Use next response from queue, or default to immediate completion
+      const response = this.responseQueue.shift() || {
+        reasoning: 'Mock reasoning',
+        nextActions: [{ type: 'complete' }]
+      }
+
+      // Return agent iteration response
+      return {
+        output: {
+          reasoning: response.reasoning || 'Mock reasoning',
+          memoryOps: response.memoryOps || {},
+          nextActions: response.nextActions || [{ type: 'complete' }]
+        } as T,
+        usage: {
+          inputTokens: 100 * this.callCount,
+          outputTokens: 50 * this.callCount,
+          totalTokens: 150 * this.callCount
+        }
+      }
+    }
+
+    // Return generic completion response
+    return {
+      output: (this.config.completionOutput || {
+        response: 'Mock response',
+        processedAt: new Date().toISOString()
+      }) as T,
+      usage: {
+        inputTokens: 50,
+        outputTokens: 25,
+        totalTokens: 75
+      }
+    }
+  }
+
+  /**
+   * Get total number of generate() calls made
+   * Useful for verifying expected iteration counts in tests
+   */
+  getCallCount(): number {
+    return this.callCount
+  }
+}