@elevasis/core 0.1.0

package/src/execution/engine/base/__tests__/utils.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest'
+import { z } from 'zod'
+import { convertContractToJson } from '../utils'
+import type { ContractStructure as _ContractStructure } from '../types'
+
+describe('convertContractToJson', () => {
+
+  it('handles complex nested schemas', () => {
+    const inputSchema = z.object({
+      user: z.object({
+        name: z.string(),
+        age: z.number(),
+        tags: z.array(z.string())
+      }),
+      metadata: z.record(z.string(), z.unknown())
+    })
+
+    const outputSchema = z.object({
+      success: z.boolean(),
+      data: z.object({
+        userId: z.string(),
+        createdAt: z.string()
+      }).optional()
+    })
+
+    const result = convertContractToJson(inputSchema, outputSchema, 'complex-workflow')
+
+    // Verify structure is created with correct definition names
+    const inputJsonSchema = result.inputSchema as Record<string, unknown>
+    const outputJsonSchema = result.outputSchema as Record<string, unknown>
+
+    expect((inputJsonSchema as { $ref: string }).$ref).toBe('#/definitions/complex-workflow-input')
+    expect((outputJsonSchema as { $ref: string }).$ref).toBe('#/definitions/complex-workflow-output')
+
+    // Verify nested properties exist in JSON Schema definitions
+    const inputDef = (inputJsonSchema.definitions as Record<string, unknown>)['complex-workflow-input'] as Record<string, unknown>
+    expect(inputDef.properties).toHaveProperty('user')
+    expect(inputDef.properties).toHaveProperty('metadata')
+
+    const outputDef = (outputJsonSchema.definitions as Record<string, unknown>)['complex-workflow-output'] as Record<string, unknown>
+    expect(outputDef.properties).toHaveProperty('success')
+    expect(outputDef.properties).toHaveProperty('data')
+  })
+
+})

package/src/execution/engine/base/errors.ts

@@ -0,0 +1,118 @@
+/**
+ * Error categories for observability grouping and classification.
+ * Used to categorize errors in the execution_errors table metadata.
+ */
+export type ExecutionErrorCategory = 'llm' | 'tool' | 'workflow' | 'agent' | 'validation' | 'system'
+
+/**
+ * Abstract base class for all execution engine errors.
+ * Enforces contract for execution_errors table insertion with explicit type,
+ * severity, category, and context properties.
+ *
+ * All execution engine errors MUST extend this class to ensure proper error
+ * tracking and observability in the execution_errors table.
+ *
+ * @example
+ * ```typescript
+ * export class MyExecutionError extends ExecutionError {
+ *   readonly type = 'my_execution_error' as const
+ *   readonly severity = 'warning' as const
+ *   readonly category = 'workflow' as const
+ *
+ *   constructor(message: string, context?: Record<string, unknown>) {
+ *     super(message, context)
+ *   }
+ * }
+ * ```
+ */
+export abstract class ExecutionError extends Error {
+  /**
+   * Error type identifier for execution_errors table.
+   * Should be a unique, snake_case string that identifies this specific error class.
+   * Used for filtering, aggregation, and error-specific handling in observability systems.
+   */
+  abstract readonly type: string
+
+  /**
+   * Error severity level for execution_errors table.
+   * - critical: System failures, auth issues, resource exhaustion - execution cannot continue
+   * - warning: Transient failures, configuration errors - execution may retry or requires user correction
+   * - info: Validation failures, expected user errors - user/developer action needed
+   */
+  abstract readonly severity: 'critical' | 'warning' | 'info'
+
+  /**
+   * Error category for observability grouping.
+   * Used to categorize errors in dashboards and analytics.
+   */
+  abstract readonly category: ExecutionErrorCategory
+
+  /**
+   * Additional context/metadata for the error.
+   * Stored in execution_errors.metadata JSONB column.
+   */
+  public readonly context?: Record<string, unknown>
+
+  /**
+   * @param message - Human-readable error message
+   * @param context - Additional context/metadata for observability
+   */
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message)
+    this.name = this.constructor.name
+    this.context = context
+
+    // Maintain proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  /**
+   * Indicates whether this error type is retryable.
+   * Default: false (safe default - only retry when explicitly safe to do so)
+   *
+   * Subclasses should override to return true for retryable scenarios:
+   * - Network/infrastructure errors (exponential backoff)
+   * - Rate limiting (linear backoff)
+   * - Service availability (exponential backoff)
+   * - Circuit breaker (circuit breaker's own delay)
+   *
+   * DO NOT retry:
+   * - Authentication/authorization errors
+   * - Validation errors
+   * - Configuration errors
+   * - Resource exhaustion errors
+   */
+  isRetryable(): boolean {
+    return false
+  }
+}
+
+/**
+ * Unknown execution error - fallback for untyped errors
+ *
+ * Used when catching errors that are not ExecutionError instances.
+ * Preserves original error context for debugging while ensuring
+ * consistent error tracking in the execution_errors table.
+ *
+ * Severity: critical (unknown errors should be treated seriously until investigated)
+ */
+export class UnknownExecutionError extends ExecutionError {
+  readonly type = 'unknown_execution_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'system' as const
+
+  constructor(
+    message: string,
+    public readonly originalError?: unknown
+  ) {
+    super(message, {
+      originalError: originalError instanceof Error ? {
+        name: originalError.name,
+        message: originalError.message,
+        stack: originalError.stack
+      } : originalError
+    })
+  }
+}

package/src/execution/engine/base/index.ts

@@ -0,0 +1,2 @@
+export { ExecutionError as ExecutionError, UnknownExecutionError, type ExecutionErrorCategory } from './errors'
+export * from './types'

package/src/execution/engine/base/logging.ts

@@ -0,0 +1,31 @@
+/**
+ * Base execution logger for Execution Engine
+ */
+export type ExecutionLogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+// Import resource-specific contexts for the union type
+import type { WorkflowLogContext } from '../workflow/logging'
+import type { AgentLogContext } from '../agent/observability/logging'
+
+// Union type for all contexts
+export type LogContext = WorkflowLogContext | AgentLogContext
+
+// Updated interface with consolidated context
+export interface ExecutionLogMessage {
+  level: ExecutionLogLevel
+  message: string
+  timestamp: number
+  context?: LogContext
+}
+
+export interface ExecutionLoggerConfig {
+  context?: string
+}
+
+// Logger interface - any logger implementation must satisfy this
+export interface IExecutionLogger {
+  debug(message: string, context?: LogContext): void
+  info(message: string, context?: LogContext): void
+  warn(message: string, context?: LogContext): void
+  error(message: string, context?: LogContext): void
+}

package/src/execution/engine/base/serialization.ts

@@ -0,0 +1,324 @@
+/**
+ * Generic serialization system for resource definitions
+ * Automatically handles Zod schemas, Maps, Sets, functions, and special types (Tools, KnowledgeMap)
+ *
+ * Replaces manual field extraction with automatic type detection and conversion.
+ * Used for API responses, CLI exports, and testing fixtures.
+ */
+
+import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
+import type { AgentDefinition } from '../agent/core/types'
+import type { WorkflowDefinition, NextConfig } from '../workflow/types'
+import { StepType } from '../workflow/types'
+
+/**
+ * Serialization options for different use cases
+ */
+export interface SerializationOptions {
+  /** Redact secrets (apiKey, tokens, passwords) - Default: true */
+  redactSecrets?: boolean
+  /** Include tool schemas in serialized tools - Default: true */
+  includeToolSchemas?: boolean
+  /** Include knowledge map metadata - Default: true */
+  includeKnowledgeMap?: boolean
+}
+
+/**
+ * Internal serialization context (includes circular reference tracking)
+ */
+interface SerializationContext extends Required<SerializationOptions> {
+  /** Circular reference protection via WeakSet */
+  visited: WeakSet<object>
+}
+
+/**
+ * Main entry point: Serialize any resource definition to JSON-safe format
+ *
+ * Automatically converts:
+ * - Zod schemas → JSON Schema
+ * - Maps → arrays with id field
+ * - Sets → arrays
+ * - Dates → ISO strings
+ * - Functions → removed
+ * - Secrets → redacted
+ *
+ * @param definition - Resource definition (AgentDefinition or WorkflowDefinition)
+ * @param options - Serialization options
+ * @returns JSON-serializable object
+ */
+export function serializeDefinition(
+  definition: AgentDefinition | WorkflowDefinition,
+  options?: SerializationOptions
+): any {
+  const opts: Required<SerializationOptions> = {
+    redactSecrets: true,
+    includeToolSchemas: true,
+    includeKnowledgeMap: true,
+    ...options
+  }
+
+  const context: SerializationContext = {
+    ...opts,
+    visited: new WeakSet()
+  }
+
+  return deepSerialize(definition, context)
+}
+
+/**
+ * Recursive serialization with type detection
+ * Handles all special types and delegates to specialized handlers
+ */
+function deepSerialize(value: any, ctx: SerializationContext): any {
+  // Primitives & null/undefined
+  if (value === null || value === undefined) return value
+  if (typeof value !== 'object') return value
+
+  // Zod schemas are leaf values — always convert (no circular tracking needed)
+  if (isZodSchema(value)) return convertZodToJsonSchema(value)
+
+  // Circular reference check (for non-leaf objects only)
+  if (ctx.visited.has(value)) {
+    return { __circular: true }
+  }
+  ctx.visited.add(value)
+  if (value instanceof Map) return convertMapToArray(value, ctx)
+  if (value instanceof Set) return convertSetToArray(value, ctx)
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === 'function') return undefined // Remove functions
+
+  // Arrays
+  if (Array.isArray(value)) {
+    return value.map((item) => deepSerialize(item, ctx)).filter((item) => item !== undefined)
+  }
+
+  // Objects - special handling for known types
+  if (isToolObject(value)) return serializeTool(value, ctx)
+  if (isKnowledgeMapObject(value)) return serializeKnowledgeMap(value, ctx)
+  if (isNextConfigObject(value)) return serializeNextConfig(value, ctx)
+
+  // Generic object recursion
+  return serializeObject(value, ctx)
+}
+
+/**
+ * Serialize generic object (recursively process all properties)
+ * Handles secret redaction and function removal
+ */
+function serializeObject(obj: any, ctx: SerializationContext): any {
+  const result: any = {}
+
+  for (const [key, val] of Object.entries(obj)) {
+    if (typeof val === 'function') continue
+
+    // Redact secrets
+    if (ctx.redactSecrets && isSecretKey(key)) {
+      result[key] = redactSecret(val)
+      continue
+    }
+
+    // Record-based steps → array format (backward compat with Map-based steps)
+    if (key === 'steps' && isWorkflowStepsRecord(val)) {
+      result[key] = convertRecordToArray(val as Record<string, any>, ctx)
+      continue
+    }
+
+    // Recurse
+    const serialized = deepSerialize(val, ctx)
+    if (serialized !== undefined) {
+      result[key] = serialized
+    }
+  }
+
+  return result
+}
+
+/**
+ * Serialize Tool object
+ * Extracts name, description, and optional schemas
+ */
+function serializeTool(tool: any, ctx: SerializationContext): any {
+  const result: any = {
+    name: tool.name,
+    description: tool.description
+  }
+
+  // Include schemas if requested
+  if (ctx.includeToolSchemas && tool.inputSchema) {
+    result.inputSchema = deepSerialize(tool.inputSchema, ctx)
+  }
+
+  if (ctx.includeToolSchemas && tool.outputSchema) {
+    result.outputSchema = deepSerialize(tool.outputSchema, ctx)
+  }
+
+  // execute function automatically omitted (typeof === 'function')
+
+  return result
+}
+
+/**
+ * Serialize KnowledgeMap object
+ * Extracts node metadata without content or file paths
+ */
+function serializeKnowledgeMap(km: any, ctx: SerializationContext): any {
+  if (!ctx.includeKnowledgeMap) return undefined
+
+  // Handle nodes field (Record<string, KnowledgeNode>)
+  const nodes = km.nodes || {}
+  const nodeEntries = Object.entries(nodes).map(([id, node]: [string, any]) => ({
+    id,
+    description: node.description,
+    loaded: node.loaded || false,
+    hasPrompt: Boolean(node.prompt)
+    // load function automatically omitted
+    // prompt content omitted (too large for structure metadata)
+  }))
+
+  return {
+    nodeCount: nodeEntries.length,
+    nodes: nodeEntries
+  }
+}
+
+/**
+ * Serialize NextConfig object
+ * Strips non-serializable condition functions while preserving route structure
+ */
+function serializeNextConfig(nextConfig: NextConfig, _context: SerializationContext): any {
+  if (!nextConfig) return null
+
+  // Handle linear next (simple target)
+  if (nextConfig.type === StepType.LINEAR) {
+    return {
+      type: nextConfig.type,
+      target: nextConfig.target
+    }
+  }
+
+  // Handle conditional next (strip condition functions)
+  if (nextConfig.type === StepType.CONDITIONAL) {
+    return {
+      type: nextConfig.type,
+      routes:
+        nextConfig.routes?.map((route) => ({
+          // Strip condition function, keep only target
+          target: route.target
+        })) ?? [],
+      default: nextConfig.default
+    }
+  }
+
+  return null
+}
+
+/**
+ * Convert Map to array with id field
+ */
+function convertMapToArray(map: Map<any, any>, ctx: SerializationContext): any[] {
+  return Array.from(map.entries()).map(([key, val]) => ({
+    id: key,
+    ...deepSerialize(val, ctx)
+  }))
+}
+
+/**
+ * Check if value is a Record of WorkflowStep objects (plain object with step-shaped values)
+ * Used to detect Record<string, WorkflowStep> after the Map-to-Record refactor
+ */
+function isWorkflowStepsRecord(value: any): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value instanceof Map || value instanceof Set) {
+    return false
+  }
+  const entries = Object.values(value)
+  if (entries.length === 0) return false
+  // Check that at least the first entry looks like a WorkflowStep (has name + handler)
+  const first = entries[0] as any
+  return first && typeof first === 'object' && 'name' in first && 'handler' in first
+}
+
+/**
+ * Convert Record<string, WorkflowStep> to array with id field
+ * Produces the same format as convertMapToArray for backward compatibility
+ */
+function convertRecordToArray(record: Record<string, any>, ctx: SerializationContext): any[] {
+  return Object.entries(record).map(([key, val]) => ({
+    id: key,
+    ...deepSerialize(val, ctx)
+  }))
+}
+
+/**
+ * Convert Set to array
+ */
+function convertSetToArray(set: Set<any>, ctx: SerializationContext): any[] {
+  return Array.from(set).map((v) => deepSerialize(v, ctx))
+}
+
+/**
+ * Convert Zod schema to JSON Schema
+ * Reuses existing utility function
+ */
+function convertZodToJsonSchema(schema: any): any {
+  return zodToJsonSchema(schema, {
+    $refStrategy: 'none',
+    errorMessages: true
+  })
+}
+
+/**
+ * Type guard: Check if value is a Zod schema
+ */
+function isZodSchema(value: any): boolean {
+  return value && typeof value === 'object' && '_def' in value && 'parse' in value
+}
+
+/**
+ * Type guard: Check if value is a Tool object
+ */
+function isToolObject(value: any): boolean {
+  return value && typeof value === 'object' && 'name' in value && 'description' in value && 'execute' in value
+}
+
+/**
+ * Type guard: Check if value is a KnowledgeMap object
+ */
+function isKnowledgeMapObject(value: any): boolean {
+  return value && typeof value === 'object' && 'nodes' in value && typeof value.nodes === 'object'
+}
+
+/**
+ * Type guard: Check if value is a NextConfig object
+ */
+function isNextConfigObject(value: any): boolean {
+  return (
+    value &&
+    typeof value === 'object' &&
+    'type' in value &&
+    (value.type === StepType.LINEAR || value.type === StepType.CONDITIONAL)
+  )
+}
+
+/**
+ * Check if key name indicates secret data
+ */
+function isSecretKey(key: string): boolean {
+  const lower = key.toLowerCase()
+
+  // Whitelist: keys that contain "token" but are not secrets
+  const whitelist = ['maxtokens', 'memorytokens', 'inputtokens', 'outputtokens']
+  if (whitelist.some((w) => lower.includes(w))) return false
+
+  const patterns = ['apikey', 'secret', 'password', 'token', 'credential']
+  return patterns.some((p) => lower.includes(p))
+}
+
+/**
+ * Redact secret value while preserving prefix
+ * Example: 'sk-proj-abc123...' → 'sk-proj...'
+ */
+function redactSecret(value: any): string {
+  if (typeof value !== 'string') return '[REDACTED]'
+  if (value.length <= 7) return '[REDACTED]'
+  return value.substring(0, 7) + '...'
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Base Execution Engine type definitions
+ * Core types shared across all Execution Engine resources
+ */
+
+import { z } from 'zod'
+import { IExecutionLogger } from './logging'
+import type {
+  SerializedAgentDefinition,
+  SerializedWorkflowDefinition
+} from '../../../platform/registry/serialized-types'
+import type { AIUsageCollector } from '../../../operations/observability/ai-usage-collector'
+import type { MetricsCollector } from '../../../operations/observability/metrics-collector'
+import type { ResourceType, ResourceStatus, ExecutableResourceType } from '../../../platform/registry/types'
+
+/**
+ * Immutable execution metadata
+ * Represents complete execution identity (who, what, when, where)
+ * Shared across ExecutionContext and ExecutionLoggerContext to eliminate field duplication
+ */
+export interface ExecutionMetadata {
+  executionId: string // Unique ID for this execution instance
+  organizationId: string // Required for multi-tenant isolation and security
+  organizationName: string // Required for resource lookup in registry
+  resourceId: string // Required for observability and audit trails
+  userId?: string // Optional: user context for audit trails (API keys, system executions may not have userId)
+  sessionId?: string // Optional: only for session executions
+  sessionTurnNumber?: number // Optional: only for session executions (maps to execution_logs.session_turn_number)
+}
+
+/**
+ * Unified message event type - covers all message types in sessions
+ * Replaces separate SessionTurnMessages and AgentActivityEvent mechanisms
+ */
+/**
+ * Structured action metadata attached to assistant messages.
+ * Frontend reads this instead of parsing text prefixes.
+ */
+export type AssistantAction =
+  | { kind: 'navigate'; path: string; reason: string }
+  | {
+      kind: 'update_filters'
+      timeRange: string | null
+      statusFilter: string | null
+      searchQuery: string | null
+    }
+
+export type MessageEvent =
+  // User/Assistant text messages
+  | { type: 'user_message'; text: string }
+  | { type: 'assistant_message'; text: string; _action?: AssistantAction }
+
+  // Agent lifecycle events
+  | { type: 'agent:started' }
+  | { type: 'agent:completed' }
+  | { type: 'agent:error'; error: string }
+
+  // Agent activity events (with metadata for UI)
+  | { type: 'agent:reasoning'; iteration: number; reasoning: string }
+  | { type: 'agent:tool_call'; toolName: string; args: Record<string, unknown> }
+  | { type: 'agent:tool_result'; toolName: string; success: boolean; result?: unknown; error?: string }
+
+/**
+ * Execution context for all resources
+ * Unified callback replaces SessionTurnMessages (removed)
+ */
+export interface ExecutionContext extends ExecutionMetadata {
+  // Inherited: executionId, organizationId, organizationName, resourceId, userId, sessionId, sessionTurnNumber
+  logger: IExecutionLogger // Required for observability and debugging
+  signal?: AbortSignal // Future: cancellation support for long-running operations
+
+  // Unified message event callback (immediate persistence + streaming)
+  onMessageEvent?: (event: MessageEvent) => Promise<void>
+
+  /** Called per iteration to write heartbeat + check stall status. Non-fatal if it throws. */
+  onHeartbeat?: () => Promise<void>
+
+  // Observability collectors (optional - injected by coordinators)
+  aiUsageCollector?: AIUsageCollector // Tracks AI token usage and costs
+  metricsCollector?: MetricsCollector // Tracks execution timing and ROI metrics
+
+  // Nested execution tracking (Wave 2c - Agent Resource Invocation)
+  parentExecutionId?: string // Parent execution ID for nested invocations
+  executionDepth: number // Nesting depth: 0 = top-level, 1+ = nested
+
+  // Integration credential tracking (for OAuth token refresh persistence)
+  credentialName?: string // Credential name used for current integration call
+
+  // Execution-scoped storage for large data (e.g., PDF buffers) that shouldn't be logged
+  // Automatically garbage collected when execution context ends
+  store: Map<string, unknown>
+}
+
+// Contract definition - validation schemas (Zod)
+export interface Contract {
+  inputSchema: z.ZodSchema // Required - use z.object({}) for no input
+  outputSchema?: z.ZodSchema // Optional - if present, agent generates output
+}
+
+// Contract structure - serializable JSON Schema representation
+export interface ContractStructure {
+  inputSchema: unknown // JSON Schema representation
+  outputSchema?: unknown // JSON Schema representation (optional for side-effect resources)
+}
+
+// Re-export resource types from registry (canonical source)
+export type { ResourceType, ResourceStatus, ExecutableResourceType }
+
+/**
+ * NOTE: AIResource interface has been removed and replaced with ResourceDefinition
+ * from registry/types.ts. All resources (executable and non-executable) now extend
+ * the unified ResourceDefinition base interface.
+ *
+ * AgentConfig and WorkflowConfig now extend ResourceDefinition directly.
+ * See packages/core/src/registry/types.ts for the base interface definition.
+ */
+
+// Generic/Unified Resource Structure type
+// Each resource type (workflow, agent) implements its own specific structure
+export type AIResourceDefinition = SerializedWorkflowDefinition | SerializedAgentDefinition
+
+// UI color constants for resource types and statuses
+export const ResourceStatusColors = {
+  dev: 'var(--color-primary)',
+  prod: 'var(--color-success)'
+} as const

package/src/execution/engine/base/utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Base Execution Engine utility functions
+ * Shared utilities used across all Execution Engine resources
+ */
+
+import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
+import type { z } from 'zod'
+import type { ContractStructure } from './types'
+
+/**
+ * Convert Zod schemas to JSON Schema for serialization
+ * Used by Workflow and Agent getStructure() methods
+ *
+ * @param inputSchema - Zod input schema
+ * @param outputSchema - Zod output schema (optional for side-effect resources)
+ * @param resourceId - Resource identifier for schema naming
+ * @returns JSON Schema representation of the contract
+ */
+export function convertContractToJson(
+  inputSchema: z.ZodSchema,
+  outputSchema: z.ZodSchema | undefined,
+  resourceId: string
+): ContractStructure {
+  const options = {
+    $refStrategy: 'none' as const,
+    errorMessages: true
+  }
+
+  return {
+    inputSchema: zodToJsonSchema(inputSchema, {
+      ...options,
+      name: `${resourceId}-input`
+    }),
+    outputSchema: outputSchema
+      ? zodToJsonSchema(outputSchema, {
+          ...options,
+          name: `${resourceId}-output`
+        })
+      : undefined
+  }
+}