@elevasis/core 0.7.0 → 0.8.0

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

@@ -1,113 +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) + '...'
-}
+/**
+ * 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

@@ -1,86 +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>>
-}
+/**
+ * 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

@@ -1,6 +1,6 @@
-/**
- * Test utilities for Execution Engine
- * Centralized exports for test helpers and mocks
- */
-
-export { createMockExecutionContext, createMockTool } from './mocks'
+/**
+ * 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

@@ -1,56 +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
-  }
-}
+/**
+ * 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/integration/base-integration-adapter.ts

@@ -1,50 +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
-}
+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
+}