@elevasis/core 0.1.0

package/src/execution/engine/llm/response-schema-validator.ts

@@ -0,0 +1,113 @@
+/**
+ * Lightweight JSON Schema validator for LLM responseSchema compliance
+ *
+ * Validates that LLM output matches the responseSchema that was sent to the provider.
+ * Not a full JSON Schema validator -- covers the subset actually used by LLM structured output:
+ * required fields, property types, enum values, nested objects, and arrays.
+ *
+ * Throws LLMResponseParseError (retryable) so the universal adapter retry loop can re-attempt.
+ */
+
+import { LLMResponseParseError } from './errors'
+
+interface JsonSchema {
+  type?: string
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  enum?: unknown[]
+  items?: JsonSchema
+  const?: unknown
+}
+
+/**
+ * Validate LLM output against the provided JSON Schema.
+ * Throws LLMResponseParseError with a descriptive message listing all violations.
+ */
+export function validateResponseSchema(output: unknown, schema: unknown): void {
+  if (!schema || typeof schema !== 'object') return
+
+  const errors = collectErrors(output, schema as JsonSchema, '')
+  if (errors.length === 0) return
+
+  throw new LLMResponseParseError(`LLM output does not match responseSchema: ${errors.join('; ')}`, {
+    errors,
+    output: summarizeOutput(output),
+    schemaRequired: (schema as JsonSchema).required
+  })
+}
+
+function collectErrors(value: unknown, schema: JsonSchema, path: string): string[] {
+  const errors: string[] = []
+  const label = path || 'root'
+
+  // Null/undefined check
+  if (value === null || value === undefined) {
+    errors.push(`${label} is ${value === null ? 'null' : 'undefined'}`)
+    return errors
+  }
+
+  // Type check
+  if (schema.type) {
+    const actualType = getJsonType(value)
+    if (schema.type !== actualType) {
+      errors.push(`${label}: expected type '${schema.type}', got '${actualType}'`)
+      return errors // Can't check deeper if type is wrong
+    }
+  }
+
+  // Enum check
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${label}: value '${String(value)}' not in enum [${schema.enum.map(String).join(', ')}]`)
+  }
+
+  // Const check
+  if (schema.const !== undefined && value !== schema.const) {
+    errors.push(`${label}: expected const '${String(schema.const)}', got '${String(value)}'`)
+  }
+
+  // Object: check required fields and property types
+  if (schema.type === 'object' && schema.properties && typeof value === 'object' && value !== null) {
+    const obj = value as Record<string, unknown>
+
+    // Check required fields exist
+    if (schema.required) {
+      for (const field of schema.required) {
+        if (!(field in obj)) {
+          errors.push(`missing required field '${path ? `${path}.${field}` : field}'`)
+        }
+      }
+    }
+
+    // Validate each property that exists
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (key in obj) {
+        const propPath = path ? `${path}.${key}` : key
+        errors.push(...collectErrors(obj[key], propSchema, propPath))
+      }
+    }
+  }
+
+  // Array: validate items
+  if (schema.type === 'array' && schema.items && Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const itemPath = `${path}[${i}]`
+      errors.push(...collectErrors(value[i], schema.items, itemPath))
+    }
+  }
+
+  return errors
+}
+
+function getJsonType(value: unknown): string {
+  if (Array.isArray(value)) return 'array'
+  if (value === null) return 'null'
+  return typeof value // 'string' | 'number' | 'boolean' | 'object'
+}
+
+/** Truncate output for error context to avoid bloating logs */
+function summarizeOutput(output: unknown): unknown {
+  if (output === null || output === undefined) return output
+  const str = JSON.stringify(output)
+  if (str.length <= 500) return output
+  return str.substring(0, 500) + '...'
+}

package/src/execution/engine/llm/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Generic LLM Types
+ * Universal interfaces for LLM interaction across all resource types
+ */
+
+// ============================================================================
+// Message Format (OpenAI-compatible)
+// ============================================================================
+
+/**
+ * Standard chat message format
+ * Compatible with OpenAI, Anthropic, and other providers
+ */
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+// ============================================================================
+// Generic Request/Response
+// ============================================================================
+
+/**
+ * Generic LLM generation request
+ * Usable by agents, workflows, tools, etc.
+ */
+export interface LLMGenerateRequest {
+  // Prompt (required)
+  messages: LLMMessage[]
+
+  // Output structure (required)
+  responseSchema: unknown // JSON Schema for structured output
+
+  // Constraints (optional)
+  /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
+  maxOutputTokens?: number
+  temperature?: number
+  topP?: number
+
+  // Cancellation (optional)
+  signal?: AbortSignal // Execution-level abort signal, composed with per-call timeout in base adapters
+}
+
+/**
+ * Generic LLM generation response
+ * Usage field is internal-only (stripped by UniversalLLMAdapter wrapper)
+ */
+export interface LLMGenerateResponse<T = unknown> {
+  output: T // Parsed structured output (validated against responseSchema)
+
+  // Internal use only (for observability tracking)
+  // Not exposed in public interface - wrapper extracts this
+  usage?: {
+    inputTokens: number
+    outputTokens: number
+    totalTokens: number
+  }
+
+  // Actual cost from provider in USD (when available)
+  // Currently only OpenRouter provides this via usage accounting
+  cost?: number
+}
+
+// ============================================================================
+// LLM Adapter Interface
+// ============================================================================
+
+/**
+ * LLM Adapter interface
+ * Generic primitive for all resource types (agents, workflows, tools)
+ *
+ * Design principles:
+ * - Single method: generate() - the core LLM primitive
+ * - Generic return type for type safety
+ * - Universal format (not agent-specific)
+ * - Standard message-based input (OpenAI-compatible)
+ */
+export interface LLMAdapter {
+  /**
+   * Generate structured output from prompt using LLM
+   *
+   * @param request - Generation request with messages and response schema
+   * @returns Generated output (typed) with optional usage metadata
+   */
+  generate<T = unknown>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>>
+}

package/src/execution/engine/test-utils/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Test utilities for Execution Engine
+ * Centralized exports for test helpers and mocks
+ */
+
+export { createMockExecutionContext, createMockTool } from './mocks'

package/src/execution/engine/test-utils/mocks.ts

@@ -0,0 +1,56 @@
+/**
+ * Centralized test utilities for Execution Engine tests
+ * Provides mock creators for ExecutionContext and Tools
+ */
+
+import { vi } from 'vitest'
+import type { Tool, ToolExecutionOptions } from '../tools/types'
+import type { ExecutionContext } from '../base/types'
+import { z } from 'zod'
+
+/**
+ * Create mock ExecutionContext for testing
+ * Provides minimal required fields with sensible defaults
+ *
+ * @param overrides - Partial context to override defaults
+ * @returns Complete ExecutionContext with all required fields
+ */
+export function createMockExecutionContext(overrides?: Partial<ExecutionContext>): ExecutionContext {
+  return {
+    executionId: 'test-exec-123',
+    organizationId: 'test-org-123',
+    organizationName: 'test-org',
+    userId: 'test-user-123',
+    resourceId: 'test-resource-123',
+    executionDepth: 0,
+    store: new Map(),
+    logger: {
+      info: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn()
+    },
+    ...overrides
+  }
+}
+
+/**
+ * Create mock tool for testing
+ * Uses new ToolExecutionOptions signature
+ *
+ * @param name - Tool name
+ * @param overrides - Partial tool definition to override
+ * @returns Tool with mocked execute function
+ */
+export function createMockTool(name: string, overrides?: Partial<Tool>): Tool {
+  return {
+    name,
+    description: `Mock tool: ${name}`,
+    inputSchema: z.object({ input: z.string() }),
+    outputSchema: z.object({ output: z.string() }),
+    execute: vi.fn(async (options: ToolExecutionOptions) => ({
+      output: `Result: ${(options.input as { input: string }).input}`
+    })),
+    ...overrides
+  }
+}

package/src/execution/engine/tools/__tests__/tooling-error.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect } from 'vitest'
+import { ToolingError, type ToolingErrorType } from '../types'
+import { ExecutionError } from '../../base/errors'
+
+describe('ToolingError', () => {
+  describe('inheritance', () => {
+    it('extends ExecutionError', () => {
+      const error = new ToolingError('service_unavailable', 'Service is down')
+      expect(error).toBeInstanceOf(ExecutionError)
+      expect(error).toBeInstanceOf(Error)
+    })
+
+    it('has tool category', () => {
+      const error = new ToolingError('api_error', 'API failed')
+      expect(error.category).toBe('tool')
+    })
+  })
+
+  describe('severity mapping - critical errors', () => {
+    const criticalErrorTypes: ToolingErrorType[] = [
+      'credentials_missing',
+      'credentials_invalid',
+      'permission_denied',
+      'auth_error',
+      'adapter_not_found',
+      'method_not_found',
+      'tool_not_found',
+    ]
+
+    criticalErrorTypes.forEach((errorType) => {
+      it(`${errorType} has critical severity`, () => {
+        const error = new ToolingError(errorType, 'test message')
+        expect(error.severity).toBe('critical')
+      })
+
+      it(`${errorType} is not retryable`, () => {
+        const error = new ToolingError(errorType, 'test message')
+        expect(error.isRetryable()).toBe(false)
+      })
+    })
+  })
+
+  describe('severity mapping - info errors', () => {
+    it('validation_error has info severity', () => {
+      const error = new ToolingError('validation_error', 'Invalid input')
+      expect(error.severity).toBe('info')
+    })
+
+    it('validation_error is not retryable', () => {
+      const error = new ToolingError('validation_error', 'Invalid input')
+      expect(error.isRetryable()).toBe(false)
+    })
+  })
+
+  describe('severity mapping - warning errors (retryable)', () => {
+    const warningErrorTypes: ToolingErrorType[] = [
+      'service_unavailable',
+      'server_unavailable',
+      'rate_limit_exceeded',
+      'api_error',
+      'network_error',
+      'timeout_error',
+      'unknown_error',
+    ]
+
+    warningErrorTypes.forEach((errorType) => {
+      it(`${errorType} has warning severity`, () => {
+        const error = new ToolingError(errorType, 'test message')
+        expect(error.severity).toBe('warning')
+      })
+
+      // Check retryability
+      const retryableTypes = [
+        'service_unavailable',
+        'server_unavailable',
+        'rate_limit_exceeded',
+        'api_error',
+        'network_error',
+        'timeout_error',
+      ]
+
+      if (retryableTypes.includes(errorType)) {
+        it(`${errorType} is retryable`, () => {
+          const error = new ToolingError(errorType, 'test message')
+          expect(error.isRetryable()).toBe(true)
+        })
+      } else {
+        it(`${errorType} is not retryable`, () => {
+          const error = new ToolingError(errorType, 'test message')
+          expect(error.isRetryable()).toBe(false)
+        })
+      }
+    })
+  })
+
+  describe('complete severity mapping coverage', () => {
+    it('all 15 error types have defined severity', () => {
+      const allErrorTypes: ToolingErrorType[] = [
+        // Critical (7)
+        'credentials_missing',
+        'credentials_invalid',
+        'permission_denied',
+        'auth_error',
+        'adapter_not_found',
+        'method_not_found',
+        'tool_not_found',
+        // Info (1)
+        'validation_error',
+        // Warning (7)
+        'service_unavailable',
+        'server_unavailable',
+        'rate_limit_exceeded',
+        'api_error',
+        'network_error',
+        'timeout_error',
+        'unknown_error',
+      ]
+
+      expect(allErrorTypes).toHaveLength(15)
+
+      // Verify each type has a valid severity
+      allErrorTypes.forEach((type) => {
+        const error = new ToolingError(type, 'test')
+        expect(['critical', 'warning', 'info']).toContain(error.severity)
+      })
+    })
+  })
+
+  describe('error properties', () => {
+    it('stores type property', () => {
+      const error = new ToolingError('api_error', 'API failed')
+      expect(error.type).toBe('tooling_error')
+    })
+
+    it('stores errorType property', () => {
+      const error = new ToolingError('api_error', 'API failed')
+      expect(error.errorType).toBe('api_error')
+    })
+
+    it('stores message', () => {
+      const error = new ToolingError('network_error', 'Network timeout')
+      expect(error.message).toBe('Network timeout')
+    })
+
+    it('stores details', () => {
+      const details = { statusCode: 500, endpoint: '/api/test' }
+      const error = new ToolingError('api_error', 'API failed', details)
+      expect(error.details).toEqual(details)
+    })
+
+    it('includes type and details in context', () => {
+      const details = { statusCode: 429 }
+      const error = new ToolingError('rate_limit_exceeded', 'Rate limit hit', details)
+      expect(error.context).toEqual({
+        type: 'rate_limit_exceeded',
+        details: { statusCode: 429 },
+      })
+    })
+
+    it('sets name to ToolingError', () => {
+      const error = new ToolingError('api_error', 'test')
+      expect(error.name).toBe('ToolingError')
+    })
+
+    it('returns correct error type', () => {
+      const error = new ToolingError('timeout_error', 'test')
+      expect(error.name).toBe('ToolingError')
+    })
+  })
+
+  describe('toJSON', () => {
+    it('includes all error properties', () => {
+      const details = { foo: 'bar' }
+      const error = new ToolingError('api_error', 'test message', details)
+      const json = error.toJSON()
+
+      expect(json).toEqual({
+        name: 'ToolingError',
+        type: 'api_error',  // toJSON returns errorType for backward compatibility
+        message: 'test message',
+        severity: 'warning',
+        category: 'tool',
+        details: { foo: 'bar' },
+      })
+    })
+
+    it('includes severity from getter', () => {
+      const criticalError = new ToolingError('credentials_missing', 'No creds')
+      expect(criticalError.toJSON().severity).toBe('critical')
+
+      const warningError = new ToolingError('api_error', 'API failed')
+      expect(warningError.toJSON().severity).toBe('warning')
+
+      const infoError = new ToolingError('validation_error', 'Invalid')
+      expect(infoError.toJSON().severity).toBe('info')
+    })
+  })
+
+  describe('retryability', () => {
+    it('retryable errors return true', () => {
+      const retryableTypes: ToolingErrorType[] = [
+        'service_unavailable',
+        'rate_limit_exceeded',
+        'api_error',
+        'network_error',
+        'timeout_error',
+        'server_unavailable',
+      ]
+
+      retryableTypes.forEach((type) => {
+        const error = new ToolingError(type, 'test')
+        expect(error.isRetryable()).toBe(true)
+      })
+    })
+
+    it('non-retryable errors return false', () => {
+      const nonRetryableTypes: ToolingErrorType[] = [
+        'credentials_missing',
+        'credentials_invalid',
+        'permission_denied',
+        'auth_error',
+        'adapter_not_found',
+        'method_not_found',
+        'tool_not_found',
+        'validation_error',
+        'unknown_error',
+      ]
+
+      nonRetryableTypes.forEach((type) => {
+        const error = new ToolingError(type, 'test')
+        expect(error.isRetryable()).toBe(false)
+      })
+    })
+  })
+
+  describe('stack traces', () => {
+    it('captures stack trace', () => {
+      const error = new ToolingError('api_error', 'test')
+      expect(error.stack).toBeDefined()
+      expect(error.stack).toContain('ToolingError')
+    })
+
+    it('preserves stack trace origin', () => {
+      function throwToolingError() {
+        throw new ToolingError('network_error', 'test')
+      }
+
+      try {
+        throwToolingError()
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolingError)
+        expect((error as Error).stack).toContain('throwToolingError')
+      }
+    })
+  })
+
+  describe('instanceof checks', () => {
+    it('maintains inheritance chain', () => {
+      const error = new ToolingError('api_error', 'test')
+      expect(error instanceof ToolingError).toBe(true)
+      expect(error instanceof ExecutionError).toBe(true)
+      expect(error instanceof Error).toBe(true)
+    })
+  })
+})

package/src/execution/engine/tools/__tests__/types.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ToolingError,
+  serviceUnavailable as _serviceUnavailable,
+  permissionDenied as _permissionDenied,
+  rateLimitExceeded as _rateLimitExceeded,
+  apiError as _apiError
+} from '../types'
+
+describe('ToolingError', () => {
+  describe('isRetryable', () => {
+    it('returns true for retryable errors', () => {
+      const retryableTypes = [
+        'service_unavailable',
+        'rate_limit_exceeded',
+        'api_error',
+        'network_error',
+        'timeout_error',
+        'server_unavailable'
+      ]
+
+      retryableTypes.forEach((type) => {
+        const error = new ToolingError(type as unknown as string, 'Test')
+        expect(error.isRetryable()).toBe(true)
+      })
+    })
+
+    it('returns false for non-retryable errors', () => {
+      const nonRetryableTypes = [
+        'permission_denied',
+        'adapter_not_found',
+        'method_not_found',
+        'tool_not_found',
+        'credentials_missing',
+        'credentials_invalid',
+        'auth_error',
+        'validation_error',
+        'unknown_error'
+      ]
+
+      nonRetryableTypes.forEach((type) => {
+        const error = new ToolingError(type as unknown as string, 'Test')
+        expect(error.isRetryable()).toBe(false)
+      })
+    })
+  })
+})

package/src/execution/engine/tools/integration/base-integration-adapter.ts

@@ -0,0 +1,50 @@
+import type { ExecutionContext } from '../../base/types'
+
+/**
+ * Base integration adapter interface
+ * All integration adapters must implement this interface
+ *
+ * Integration adapters provide a standardized way to call external REST APIs
+ * with proper credential validation and error handling.
+ *
+ * @example
+ * ```typescript
+ * class GmailAdapter implements BaseIntegrationAdapter {
+ *   readonly name = 'gmail'
+ *
+ *   async call(method: string, params: unknown, credentials: Record<string, unknown>, context?: ExecutionContext) {
+ *     // Implementation
+ *   }
+ *
+ *   validateCredentials(credentials: Record<string, unknown>): boolean {
+ *     // Validation logic
+ *   }
+ * }
+ * ```
+ */
+export interface BaseIntegrationAdapter {
+  /** Integration name (e.g., 'gmail', 'slack') */
+  readonly name: string
+
+  /**
+   * Call integration method
+   * @param method - Method name (e.g., 'sendEmail', 'postMessage')
+   * @param params - Method parameters
+   * @param credentials - Organization credentials for this integration
+   * @param context - Execution context for logging and tracing
+   * @returns Method result
+   */
+  call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown>
+
+  /**
+   * Validate credentials for this integration
+   * @param credentials - Credentials to validate
+   * @returns true if valid, false otherwise
+   */
+  validateCredentials(credentials: Record<string, unknown>): boolean
+}

package/src/execution/engine/tools/integration/index.ts

@@ -0,0 +1,53 @@
+/**
+ *
+ * Integration System
+ *
+ * Infrastructure for calling external APIs (Gmail, Slack, etc.) from agent tools.
+ * Provides adapters, credentials, rate limiting, and retry logic.
+ *
+ * Usage:
+ * import { createIntegrationTool, IntegrationService } from '@repo/core/execution-engine/tools/integration'
+ */
+
+// Tool creation (primary interface for agents)
+export { createIntegrationTool } from './tool'
+export type {
+  IntegrationToolConfig,
+  IntegrationType,
+  IntegrationMethodMap,
+  GmailMethod,
+  SlackMethod,
+  GithubMethod,
+  LinearMethod,
+  AirtableMethod,
+  SalesforceMethod,
+  HubspotMethod,
+  StripeMethod,
+  TwilioMethod,
+  SendgridMethod,
+  MailgunMethod,
+  ZapierMethod,
+  WebhookMethod,
+  SignatureApiMethod
+} from './tool'
+
+// Core service and orchestration
+export { IntegrationService } from './service'
+
+// Types and errors
+export type { BaseIntegrationAdapter } from './base-integration-adapter'
+export type { RateLimiter, RetryPolicy } from '../../../../platform/resilience'
+
+// Utilities
+export {
+  DEFAULT_RETRY_POLICY,
+  InMemoryRateLimiter,
+  createRateLimiter,
+  withRetry,
+  calculateRetryDelay,
+  sleep
+} from '../../../../platform/resilience'
+
+// NOTE: Tool factory functions (createGmailSendEmailTool, etc.)
+// are server-only and must be imported from @repo/core/server
+// They are NOT exported here to enforce the browser/server boundary