@elevasis/core 0.1.0

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

@@ -0,0 +1,63 @@
+/**
+ * Workflow error classes
+ * Errors specific to workflow execution
+ */
+
+import { ExecutionError } from '../base/errors'
+
+/**
+ * Thrown when a workflow step fails during execution
+ *
+ * Severity: error (step failure — errors always take precedence over warnings)
+ * Category: workflow
+ *
+ * @example
+ * ```typescript
+ * throw new WorkflowStepError(
+ *   'Step "send_email" failed: SMTP server unavailable',
+ *   {
+ *     workflowId: 'wf-123',
+ *     stepIndex: 2,
+ *     stepName: 'send_email',
+ *     attemptCount: 1
+ *   }
+ * )
+ * ```
+ */
+export class WorkflowStepError extends ExecutionError {
+  readonly type = 'workflow_step_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'workflow' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when workflow validation fails
+ *
+ * Severity: info (validation failure indicating user/developer configuration error)
+ * Category: validation
+ *
+ * @example
+ * ```typescript
+ * throw new WorkflowValidationError(
+ *   'Invalid workflow: Step "approval" has no approver configured',
+ *   {
+ *     workflowId: 'wf-123',
+ *     stepIndex: 3,
+ *     field: 'approver'
+ *   }
+ * )
+ * ```
+ */
+export class WorkflowValidationError extends ExecutionError {
+  readonly type = 'workflow_validation_error' as const
+  readonly severity = 'info' as const
+  readonly category = 'validation' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}

package/src/execution/engine/workflow/helpers/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Workflow Step Helpers - Browser-safe exports
+ *
+ * NOTE: Server-only helper (llmCall) is exported from @repo/core/server
+ * to prevent browser build failures (depends on server-only LLM adapters).
+ *
+ * This file exports only browser-safe types.
+ */
+
+// Type-only exports (safe for browser - types are erased at runtime)
+export type { LLMCallOptions } from './server/llm-call'

package/src/execution/engine/workflow/helpers/server/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-only Workflow Helpers
+ *
+ * These helpers use server-only adapters (createLLMAdapter)
+ * and should only be imported from @repo/core/server
+ */
+
+export { llmCall, type LLMCallOptions } from './llm-call'

package/src/execution/engine/workflow/helpers/server/llm-call.ts

@@ -0,0 +1,93 @@
+/**
+ * LLM Call Helper
+ * Helper function for making LLM calls within workflow step handlers
+ */
+
+import { createLLMAdapter } from '../../../llm/adapters/server/adapter-factory'
+import type { ModelConfig } from '../../../llm/model-info'
+import type { ExecutionContext } from '../../../base/types'
+import type { LLMMessage } from '../../../llm/types'
+
+export interface LLMCallOptions {
+  /** Model configuration (provider, model, API key) */
+  modelConfig: ModelConfig
+  /** Chat messages (system/user/assistant) */
+  messages: LLMMessage[]
+  /** JSON Schema for structured output */
+  responseSchema: Record<string, unknown>
+  /** Optional temperature override */
+  temperature?: number
+  /** Optional max output tokens override */
+  maxOutputTokens?: number
+  /** Optional step ID for observability context */
+  stepId?: string
+  /** Optional step name for observability context */
+  stepName?: string
+}
+
+/**
+ * Make an LLM call within a workflow step handler
+ *
+ * Automatically integrates with observability tracking via ExecutionContext.
+ * Tracks calls with `callType: 'workflow-step'` in AI usage metrics.
+ *
+ * @example
+ * ```typescript
+ * const summarizeStep: WorkflowStep = {
+ *   id: 'summarize',
+ *   name: 'Summarize Data',
+ *   handler: async (input, context) => {
+ *     const result = await llmCall(context, {
+ *       modelConfig: {
+ *         provider: 'openrouter',
+ *         model: 'openrouter/anthropic/claude-sonnet-4.5',
+ *         apiKey: process.env.OPENROUTER_API_KEY!
+ *       },
+ *       messages: [
+ *         { role: 'system', content: 'You are a summarization expert.' },
+ *         { role: 'user', content: `Summarize: ${input.data}` }
+ *       ],
+ *       responseSchema: {
+ *         type: 'object',
+ *         properties: { summary: { type: 'string' } },
+ *         required: ['summary']
+ *       },
+ *       stepId: 'summarize',
+ *       stepName: 'Summarize Data'
+ *     })
+ *
+ *     return { summary: result.summary }
+ *   },
+ *   inputSchema: z.object({ data: z.string() }),
+ *   outputSchema: z.object({ summary: z.string() }),
+ *   next: { type: StepType.LINEAR, target: 'next-step' }
+ * }
+ * ```
+ */
+export async function llmCall<T = unknown>(context: ExecutionContext, options: LLMCallOptions): Promise<T> {
+  const { modelConfig, messages, responseSchema, temperature, maxOutputTokens, stepId, stepName } = options
+
+  const adapter = createLLMAdapter(
+    {
+      ...modelConfig,
+      ...(temperature !== undefined && { temperature }),
+      ...(maxOutputTokens !== undefined && { maxOutputTokens })
+    },
+    context.aiUsageCollector,
+    'workflow-step',
+    {
+      type: 'workflow-step',
+      stepId: stepId ?? 'unknown',
+      stepName
+    }
+  )
+
+  const response = await adapter.generate<T>({
+    messages,
+    responseSchema,
+    temperature,
+    maxOutputTokens
+  })
+
+  return response.output
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Workflow module exports
+ */
+
+// Export workflow implementation
+export { Workflow } from './workflow'
+
+// Export workflow types
+export * from './types'
+
+// Export workflow logger types
+export * from './logging'
+
+// Export workflow errors
+export * from './errors'
+
+// Export workflow step helper types (browser-safe - types only)
+// NOTE: llmCall implementation is server-only - import from @repo/core/server
+export { type LLMCallOptions } from './helpers'

package/src/execution/engine/workflow/log-truncate.ts

@@ -0,0 +1,26 @@
+/** Max characters for string values in logged step input/output contexts */
+const LOG_STRING_TRUNCATE_LIMIT = 200
+
+/**
+ * Deep-clone an object, truncating string values that exceed the limit.
+ * Keeps the structure intact so the UI timeline can display field names and short previews.
+ */
+export function truncateForLogging(value: unknown): unknown {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'string') {
+    return value.length > LOG_STRING_TRUNCATE_LIMIT
+      ? value.slice(0, LOG_STRING_TRUNCATE_LIMIT) + `… [${value.length} chars]`
+      : value
+  }
+  if (Array.isArray(value)) {
+    return value.map(truncateForLogging)
+  }
+  if (typeof value === 'object') {
+    const result: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = truncateForLogging(v)
+    }
+    return result
+  }
+  return value
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Workflow-specific logging types and utilities
+ */
+
+import type { ExecutionLogLevel, ExecutionLogMessage } from '../base/logging'
+
+// Workflow start/end log context
+export interface WorkflowExecutionContext {
+  type: 'workflow'
+  contextType: 'workflow-execution'
+  executionId: string
+  workflowId: string
+  workflowName?: string
+  organizationId: string
+  executionPath?: string[]
+}
+
+// Workflow failure log context
+export interface WorkflowFailureContext {
+  type: 'workflow'
+  contextType: 'workflow-failure'
+  executionId: string
+  workflowId: string
+  error: string
+}
+
+// Step started log context
+export interface StepStartedContext {
+  type: 'workflow'
+  contextType: 'step-started'
+  stepId: string
+  stepStatus: 'started'
+  input: unknown
+  startTime: number // Explicit start timestamp for timeline
+}
+
+// Step completed log context
+export interface StepCompletedContext {
+  type: 'workflow'
+  contextType: 'step-completed'
+  stepId: string
+  stepStatus: 'completed'
+  output: unknown
+  duration: number
+  isTerminal: boolean
+  startTime: number // Explicit start timestamp for timeline
+  endTime: number // Explicit end timestamp for timeline
+}
+
+// Step failed log context
+export interface StepFailedContext {
+  type: 'workflow'
+  contextType: 'step-failed'
+  stepId: string
+  stepStatus: 'failed'
+  error: string
+  duration: number
+  startTime: number // Explicit start timestamp for timeline
+  endTime: number // Explicit end timestamp for timeline
+}
+
+// Conditional routing log context
+export interface ConditionalRouteContext {
+  type: 'workflow'
+  contextType: 'conditional-route'
+  stepId: string
+  target: string
+  error?: string
+}
+
+// Execution path log context
+export interface ExecutionPathContext {
+  type: 'workflow'
+  contextType: 'execution-path'
+  executionPath: string[]
+}
+
+// Union of step contexts with stepStatus field
+export type StepStatusContext = StepStartedContext | StepCompletedContext | StepFailedContext
+
+// Union of all workflow log contexts
+export type WorkflowLogContext =
+  | WorkflowExecutionContext
+  | WorkflowFailureContext
+  | StepStartedContext
+  | StepCompletedContext
+  | StepFailedContext
+  | ConditionalRouteContext
+  | ExecutionPathContext
+
+// Workflow execution log message (UI-specific interface)
+export interface WorkflowLogMessage {
+  level: ExecutionLogLevel
+  message: string
+  timestamp: number
+  context?: WorkflowLogContext
+}
+
+/**
+ * Type guard helper functions for context discrimination
+ */
+
+export function isWorkflowExecutionContext(ctx: WorkflowLogContext): ctx is WorkflowExecutionContext {
+  return ctx.contextType === 'workflow-execution'
+}
+
+export function isWorkflowFailureContext(ctx: WorkflowLogContext): ctx is WorkflowFailureContext {
+  return ctx.contextType === 'workflow-failure'
+}
+
+export function isStepStartedContext(ctx: WorkflowLogContext): ctx is StepStartedContext {
+  // Check new contextType field or fall back to old stepStatus pattern for backwards compatibility
+  return (
+    ctx.contextType === 'step-started' ||
+    ('stepStatus' in ctx && (ctx as StepStatusContext).stepStatus === 'started')
+  )
+}
+
+export function isStepCompletedContext(ctx: WorkflowLogContext): ctx is StepCompletedContext {
+  // Check new contextType field or fall back to old stepStatus pattern for backwards compatibility
+  return (
+    ctx.contextType === 'step-completed' ||
+    ('stepStatus' in ctx && (ctx as StepStatusContext).stepStatus === 'completed')
+  )
+}
+
+export function isStepFailedContext(ctx: WorkflowLogContext): ctx is StepFailedContext {
+  // Check new contextType field or fall back to old stepStatus pattern for backwards compatibility
+  return (
+    ctx.contextType === 'step-failed' ||
+    ('stepStatus' in ctx && (ctx as StepStatusContext).stepStatus === 'failed')
+  )
+}
+
+export function isConditionalRouteContext(ctx: WorkflowLogContext): ctx is ConditionalRouteContext {
+  // Check new contextType field or fall back to checking for target field for backwards compatibility
+  return ctx.contextType === 'conditional-route' || ('target' in ctx && 'stepId' in ctx && !('stepStatus' in ctx))
+}
+
+export function isExecutionPathContext(ctx: WorkflowLogContext): ctx is ExecutionPathContext {
+  return ctx.contextType === 'execution-path'
+}
+
+/**
+ * Helper to check if context has step-related information
+ */
+export function isStepContext(
+  ctx: WorkflowLogContext
+): ctx is StepStartedContext | StepCompletedContext | StepFailedContext | ConditionalRouteContext {
+  return (
+    ctx.contextType === 'step-started' ||
+    ctx.contextType === 'step-completed' ||
+    ctx.contextType === 'step-failed' ||
+    ctx.contextType === 'conditional-route'
+  )
+}
+
+/**
+ * Convert ExecutionLogMessage to WorkflowLogMessage for workflow context
+ * Returns null for non-workflow logs
+ */
+export function toWorkflowLogMessage(log: ExecutionLogMessage): WorkflowLogMessage | null {
+  // Convert logs with workflow context
+  if (log.context?.type === 'workflow') {
+    return {
+      level: log.level,
+      message: log.message,
+      timestamp: log.timestamp,
+      context: log.context as WorkflowLogContext
+    }
+  }
+
+  // Convert user-level logs (no context or non-workflow context from step handlers)
+  // Cast is safe: LogEntry renders any context object as expandable JSON
+  return {
+    level: log.level,
+    message: log.message,
+    timestamp: log.timestamp,
+    context: log.context as WorkflowLogContext | undefined
+  }
+}
+
+/**
+ * Convert array of ExecutionLogMessages to WorkflowLogMessages
+ * Filters out non-workflow logs
+ */
+export function toWorkflowLogMessages(logs: ExecutionLogMessage[]): WorkflowLogMessage[] {
+  return logs
+    .map(toWorkflowLogMessage)
+    .filter((log): log is WorkflowLogMessage => log !== null)
+}

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

@@ -0,0 +1,183 @@
+// Import z for schema types
+import type { z } from 'zod'
+
+/**
+ * Workflow-specific type definitions
+ */
+
+import type { ExecutionContext } from '../base/types'
+import type { ResourceDefinition } from '../../../platform/registry/types'
+import type { ResourceMetricsConfig } from '../../../operations/observability/types'
+import type { ExecutionInterface } from '../interface/types'
+
+// Workflow configuration
+export interface WorkflowConfig extends ResourceDefinition {
+  type: 'workflow'
+}
+
+// Workflow step definition
+export interface WorkflowStepDefinition {
+  id: string
+  name: string
+  description: string
+}
+
+// Step handler function type
+export type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>
+
+// Step type for flow control
+export const StepType = {
+  LINEAR: 'linear',
+  CONDITIONAL: 'conditional',
+} as const
+// eslint-disable-next-line no-redeclare -- intentional const+type pattern (enum-like)
+export type StepType = typeof StepType[keyof typeof StepType]
+
+// Next step configuration types
+export interface LinearNext {
+  type: 'linear'
+  target: string
+}
+
+export interface ConditionalNext {
+  type: 'conditional'
+  routes: Array<{
+    condition: (data: unknown) => boolean
+    target: string
+  }>
+  default: string // Required to avoid ambiguity
+}
+
+export type NextConfig =
+  | LinearNext // Go to specific step
+  | ConditionalNext // Conditional routing
+  | null // Explicitly end workflow
+
+// Workflow step with graph-based flow
+export interface WorkflowStep extends WorkflowStepDefinition {
+  handler: StepHandler
+
+  // I/O validation (BOTH REQUIRED for complete type safety)
+  inputSchema: z.ZodSchema // Validates input from previous step or workflow
+  outputSchema: z.ZodSchema // Validates output before next step
+
+  next: NextConfig // Required - explicit flow decision for every step
+}
+
+// Workflow definition - pure configuration without instance state
+// Used by registry to define workflows that can be instantiated
+export interface WorkflowDefinition {
+  config: WorkflowConfig
+  contract: import('../base/types').Contract
+  steps: Record<string, WorkflowStep>
+  entryPoint: string
+
+  /**
+   * Metrics configuration for ROI calculations
+   * Optional: Only needed if tracking automation savings
+   */
+  metricsConfig?: ResourceMetricsConfig
+
+  /**
+   * Execution interface configuration (optional)
+   * If provided, workflow appears in Execution Runner UI
+   */
+  interface?: ExecutionInterface
+}
+
+/**
+ * Workflow timeline and observability types
+ * Used for UI timeline visualization and backend processing
+ */
+
+import type { WorkflowLogMessage } from './logging'
+
+/**
+ * Workflow step state
+ * Aggregates step context events with timing and logs
+ */
+export interface StepState {
+  stepId: string
+  stepName: string
+  status: 'pending' | 'running' | 'completed' | 'failed'
+
+  // Timeline visualization timing
+  startTime?: number // From step-started context
+  endTime?: number // From step-completed/failed context
+  duration?: number // From step-completed/failed context
+
+  // Step data
+  input?: unknown
+  output?: unknown
+  error?: unknown
+  logs: WorkflowLogMessage[]
+}
+
+/**
+ * Complete workflow execution data for node visualization
+ * Parsed from execution logs
+ */
+export interface WorkflowNodeVisualizerData {
+  steps: StepState[]
+  totalDuration: number
+  isRunning: boolean
+}
+
+/**
+ * Step data extracted from execution logs
+ * Used to provide detailed step information in unified graph nodes
+ */
+export interface StepExecutionData {
+  /** Final execution status for this step */
+  status: 'pending' | 'running' | 'completed' | 'failed'
+
+  /** Step execution duration in milliseconds */
+  duration?: number
+
+  /** Step input data */
+  input?: unknown
+
+  /** Step output data */
+  output?: unknown
+
+  /** Error data if step failed */
+  error?: unknown
+
+  /** Log messages from this step (reserved for future use) */
+  logs?: unknown[]
+}
+
+/**
+ * Execution path tracking state
+ *
+ * Tracks which steps have been executed and which edges were taken during workflow
+ * execution. This state is built from SSE execution log events and used to compute
+ * the visual dimming/highlighting of nodes and edges.
+ *
+ * Algorithm:
+ * - `executedSteps` provides O(1) lookup for "has this step been reached?"
+ * - `executedStepsOrdered` preserves execution order for edge inference
+ * - `takenEdges` comes from `conditional-route` SSE events + linear step inference
+ * - `currentStepId` tracks the actively running step for animation
+ * - `stepStatusMap` provides final status for each executed step
+ * - `stepDataMap` provides detailed execution data (duration, input, output, error)
+ */
+export interface ExecutionPathState {
+  /** Set of step IDs that have been executed (O(1) lookup) */
+  executedSteps: Set<string>
+
+  /** Step IDs in execution order (for inferring linear edges) */
+  executedStepsOrdered: string[]
+
+  /** Set of edge IDs that were traversed (format: "edge-{source}-{target}") */
+  takenEdges: Set<string>
+
+  /** Currently running step ID (undefined if no step is running) */
+  currentStepId?: string
+
+  /** Map of step IDs to their final execution status */
+  stepStatusMap?: Map<string, 'pending' | 'running' | 'completed' | 'failed'>
+
+  /** Map of step IDs to their execution data (duration, input, output, error) */
+  stepDataMap?: Map<string, StepExecutionData>
+}