durable_workflow 0.1.0

data/examples/support_agent/workflow.yml

@@ -0,0 +1,286 @@
+id: support_agent
+name: Customer Support Agent
+version: "1.0"
+description: AI-powered customer support with specialized agents
+
+inputs:
+  message:
+    type: string
+    required: true
+    description: Customer's support request
+  customer_id:
+    type: string
+    required: false
+    description: Optional customer identifier
+  context:
+    type: object
+    required: false
+    description: Additional context (order_id, etc.)
+
+# AI Extension Configuration
+agents:
+  - id: triage
+    name: Triage Agent
+    model: gpt-4o-mini
+    instructions: |
+      You are a support triage agent. Analyze the customer's request and determine:
+      1. The category (billing, technical, general)
+      2. The urgency (low, medium, high)
+      3. Key entities mentioned (order IDs, product names, etc.)
+
+      Always be polite and acknowledge the customer's concern.
+      Use the classify_request tool to record your analysis.
+    tools:
+      - classify_request
+
+  - id: billing
+    name: Billing Agent
+    model: gpt-4o
+    instructions: |
+      You are a billing specialist. Help customers with:
+      - Order lookups and status
+      - Refunds and cancellations
+      - Payment issues
+      - Invoice requests
+
+      Always verify the customer's identity before processing sensitive requests.
+      Use available tools to look up information and take actions.
+    tools:
+      - lookup_order
+      - refund_order
+      - create_ticket
+      - escalate
+    handoffs:
+      - agent_id: technical
+        description: Transfer to technical support for product issues
+
+  - id: technical
+    name: Technical Support Agent
+    model: gpt-4o
+    instructions: |
+      You are a technical support specialist. Help customers with:
+      - Product setup and configuration
+      - Troubleshooting issues
+      - Password resets
+      - Account access problems
+
+      Be patient and provide step-by-step guidance.
+    tools:
+      - reset_password
+      - check_status
+      - create_ticket
+      - escalate
+    handoffs:
+      - agent_id: billing
+        description: Transfer to billing for payment issues
+
+tools:
+  - id: classify_request
+    description: Classify the customer's support request
+    parameters:
+      - name: category
+        type: string
+        required: true
+        description: "Category: billing, technical, or general"
+      - name: urgency
+        type: string
+        required: true
+        description: "Urgency: low, medium, or high"
+      - name: summary
+        type: string
+        required: true
+        description: Brief summary of the request
+    service: SupportServices
+    method: classify_request
+
+  - id: lookup_order
+    description: Look up an order by ID or customer email
+    parameters:
+      - name: order_id
+        type: string
+        description: Order ID to look up
+      - name: email
+        type: string
+        description: Customer email to find orders
+    service: SupportServices
+    method: lookup_order
+
+  - id: refund_order
+    description: Process a refund for an order
+    parameters:
+      - name: order_id
+        type: string
+        required: true
+        description: Order ID to refund
+      - name: reason
+        type: string
+        required: true
+        description: Reason for refund
+      - name: amount
+        type: number
+        description: Partial refund amount (omit for full refund)
+    service: SupportServices
+    method: refund_order
+
+  - id: create_ticket
+    description: Create a support ticket for follow-up
+    parameters:
+      - name: subject
+        type: string
+        required: true
+        description: Ticket subject
+      - name: description
+        type: string
+        required: true
+        description: Detailed description
+      - name: priority
+        type: string
+        description: "Priority: low, medium, high"
+    service: SupportServices
+    method: create_ticket
+
+  - id: check_status
+    description: Check the status of a support ticket
+    parameters:
+      - name: ticket_id
+        type: string
+        required: true
+        description: Ticket ID to check
+    service: SupportServices
+    method: check_status
+
+  - id: reset_password
+    description: Send password reset email to customer
+    parameters:
+      - name: email
+        type: string
+        required: true
+        description: Customer's email address
+    service: SupportServices
+    method: reset_password
+
+  - id: escalate
+    description: Escalate to a human support agent
+    parameters:
+      - name: reason
+        type: string
+        required: true
+        description: Reason for escalation
+      - name: urgency
+        type: string
+        required: true
+        description: "Urgency level: medium or high"
+    service: SupportServices
+    method: escalate
+
+# Workflow Steps
+steps:
+  - id: start
+    type: start
+    next: moderate_input
+
+  - id: moderate_input
+    type: guardrail
+    content: "$input.message"
+    checks:
+      - type: moderation
+      - type: prompt_injection
+    on_fail: rejected
+    next: triage
+
+  - id: triage
+    type: agent
+    agent_id: triage
+    prompt: |
+      Customer message: $input.message
+      Customer ID: $input.customer_id
+      Context: $input.context
+
+      Please analyze this request and classify it.
+    output: triage_result
+    next: route_request
+
+  - id: route_request
+    type: router
+    routes:
+      - when:
+          field: triage_result.category
+          op: eq
+          value: "billing"
+        then: billing_agent
+      - when:
+          field: triage_result.category
+          op: eq
+          value: "technical"
+        then: technical_agent
+    default: general_response
+
+  - id: billing_agent
+    type: agent
+    agent_id: billing
+    prompt: |
+      Customer request (classified as billing, urgency: $triage_result.urgency):
+      $input.message
+
+      Customer ID: $input.customer_id
+      Context: $input.context
+
+      Please help resolve this billing issue.
+    output: agent_response
+    next: check_handoff
+
+  - id: technical_agent
+    type: agent
+    agent_id: technical
+    prompt: |
+      Customer request (classified as technical, urgency: $triage_result.urgency):
+      $input.message
+
+      Customer ID: $input.customer_id
+
+      Please help resolve this technical issue.
+    output: agent_response
+    next: check_handoff
+
+  - id: general_response
+    type: agent
+    agent_id: triage
+    prompt: |
+      The customer's request doesn't fit billing or technical categories.
+      Please provide a helpful general response or ask clarifying questions.
+
+      Customer message: $input.message
+    output: agent_response
+    next: end
+
+  - id: check_handoff
+    type: router
+    routes:
+      - when:
+          field: _handoff_to
+          op: exists
+        then: handle_handoff
+    default: end
+
+  - id: handle_handoff
+    type: handoff
+    target_agent: "$_handoff_to"
+    context:
+      original_message: "$input.message"
+      previous_response: "$agent_response"
+      triage: "$triage_result"
+    output: agent_response
+    next: end
+
+  - id: rejected
+    type: assign
+    set:
+      agent_response: "I apologize, but I cannot process this request. Please contact support directly."
+      triage_result: null
+    next: end
+
+  - id: end
+    type: end
+    result:
+      response: "$agent_response"
+      triage: "$triage_result"

data/lib/durable_workflow/core/condition.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    # Stateless condition evaluator
+    class ConditionEvaluator
+      OPS = {
+        'eq' => ->(v, e) { v == e },
+        'neq' => ->(v, e) { v != e },
+        'gt' => ->(v, e) { v.to_f > e.to_f },
+        'lt' => ->(v, e) { v.to_f < e.to_f },
+        'gte' => ->(v, e) { v.to_f >= e.to_f },
+        'lte' => ->(v, e) { v.to_f <= e.to_f },
+        'in' => ->(v, e) { Array(e).include?(v) },
+        'not_in' => ->(v, e) { !Array(e).include?(v) },
+        'contains' => ->(v, e) { v.to_s.include?(e.to_s) },
+        'starts_with' => ->(v, e) { v.to_s.start_with?(e.to_s) },
+        'ends_with' => ->(v, e) { v.to_s.end_with?(e.to_s) },
+        'matches' => ->(v, e) { v.to_s.match?(Regexp.new(e.to_s)) },
+        'exists' => ->(v, _) { !v.nil? },
+        'empty' => ->(v, _) { v.nil? || (v.respond_to?(:empty?) && v.empty?) },
+        'truthy' => ->(v, _) { !v.nil? },
+        'falsy' => ->(v, _) { !v }
+      }.freeze
+
+      class << self
+        # Evaluate Route or Condition
+        def match?(state, cond)
+          val = Resolver.resolve(state, "$#{cond.field}")
+          exp = Resolver.resolve(state, cond.value)
+          op = OPS.fetch(cond.op) { ->(_, _) { false } }
+          op.call(val, exp)
+        rescue StandardError => e
+          DurableWorkflow.log(:warn, "Condition failed: #{e.message}", field: cond.field, op: cond.op)
+          false
+        end
+
+        # Find first matching route
+        def find_route(state, routes)
+          routes.find { match?(state, _1) }
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/engine.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module DurableWorkflow
+  module Core
+    class Engine
+      FINISHED = '__FINISHED__'
+
+      attr_reader :workflow, :store
+
+      def initialize(workflow, store: nil)
+        @workflow = workflow
+        @store = store || DurableWorkflow.config&.store
+        raise ConfigError, 'No store configured. Use Redis, ActiveRecord, or Sequel.' unless @store
+      end
+
+      def run(input: {}, execution_id: nil)
+        exec_id = execution_id || SecureRandom.uuid
+
+        state = State.new(
+          execution_id: exec_id,
+          workflow_id: workflow.id,
+          input: DurableWorkflow::Utils.deep_symbolize(input)
+        )
+
+        # Save initial Execution with :running status
+        save_execution(state, ExecutionResult.new(status: :running, execution_id: exec_id))
+
+        if workflow.timeout
+          Timeout.timeout(workflow.timeout) do
+            execute_from(state, workflow.first_step.id)
+          end
+        else
+          execute_from(state, workflow.first_step.id)
+        end
+      rescue Timeout::Error
+        result = ExecutionResult.new(status: :failed, execution_id: state.execution_id, error: "Workflow timeout after #{workflow.timeout}s")
+        save_execution(state, result)
+        result
+      end
+
+      def resume(execution_id, response: nil, approved: nil)
+        execution = @store.load(execution_id)
+        raise ExecutionError, "Execution not found: #{execution_id}" unless execution
+
+        state = execution.to_state
+        state = state.with_ctx(response:) if response
+        state = state.with_ctx(approved:) unless approved.nil?
+
+        # Use recover_to from Execution, or fall back to current_step
+        resume_step = execution.recover_to || execution.current_step
+
+        execute_from(state, resume_step)
+      end
+
+      private
+
+      def execute_from(state, step_id)
+        while step_id && step_id != FINISHED
+          state = state.with_current_step(step_id)
+
+          # Save intermediate state as :running
+          save_execution(state, ExecutionResult.new(status: :running, execution_id: state.execution_id))
+
+          step = workflow.find_step(step_id)
+          raise ExecutionError, "Step not found: #{step_id}" unless step
+
+          outcome = execute_step(state, step)
+          state = outcome.state
+
+          case outcome.result
+          when HaltResult
+            return handle_halt(state, outcome.result)
+          when ContinueResult
+            step_id = outcome.result.next_step
+          else
+            raise ExecutionError, "Unknown result: #{outcome.result.class}"
+          end
+        end
+
+        # Completed
+        result = ExecutionResult.new(status: :completed, execution_id: state.execution_id, output: state.ctx[:result])
+        save_execution(state, result)
+        result
+      end
+
+      def execute_step(state, step)
+        executor_class = Executors::Registry[step.type]
+        raise ExecutionError, "No executor for: #{step.type}" unless executor_class
+
+        start = Time.now
+        outcome = executor_class.new(step).call(state)
+        duration = ((Time.now - start) * 1000).to_i
+
+        @store.record(Entry.new(
+                        id: SecureRandom.uuid,
+                        execution_id: state.execution_id,
+                        step_id: step.id,
+                        step_type: step.type,
+                        action: outcome.result.is_a?(HaltResult) ? :halted : :completed,
+                        duration_ms: duration,
+                        output: outcome.result.output,
+                        timestamp: Time.now
+                      ))
+
+        outcome
+      rescue StandardError => e
+        @store.record(Entry.new(
+                        id: SecureRandom.uuid,
+                        execution_id: state.execution_id,
+                        step_id: step.id,
+                        step_type: step.type,
+                        action: :failed,
+                        error: "#{e.class}: #{e.message}",
+                        timestamp: Time.now
+                      ))
+
+        if step.on_error
+          # Store error info in ctx for access by error handler step
+          error_state = state.with_ctx(_last_error: { step: step.id, message: e.message, class: e.class.name })
+          return StepOutcome.new(state: error_state, result: ContinueResult.new(next_step: step.on_error))
+        end
+
+        raise
+      end
+
+      def handle_halt(state, halt_result)
+        result = ExecutionResult.new(
+          status: :halted,
+          execution_id: state.execution_id,
+          output: state.ctx[:result],
+          halt: halt_result
+        )
+        save_execution(state, result)
+        result
+      end
+
+      def save_execution(state, result)
+        execution = Execution.from_state(state, result)
+        @store.save(execution)
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/approval.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Approval < Base
+        Registry.register('approval', self)
+
+        def call(state)
+          # Check if timed out (when resuming)
+          requested_at_str = state.ctx.dig(:_halt, :requested_at)
+          if requested_at_str && config.timeout
+            requested_at = Time.parse(requested_at_str)
+            if Time.now - requested_at > config.timeout
+              return continue(state, next_step: config.on_timeout) if config.on_timeout
+
+              raise ExecutionError, 'Approval timeout'
+
+            end
+          end
+
+          # Resuming from approval
+          if state.ctx.key?(:approved)
+            approved = state.ctx[:approved]
+            state = state.with(ctx: state.ctx.except(:approved))
+            if approved
+              return continue(state)
+            elsif config.on_reject
+              return continue(state, next_step: config.on_reject)
+            else
+              raise ExecutionError, 'Rejected'
+            end
+          end
+
+          # Request approval
+          halt(state,
+               data: {
+                 type: :approval,
+                 prompt: resolve(state, config.prompt),
+                 context: resolve(state, config.context),
+                 approvers: config.approvers,
+                 timeout: config.timeout,
+                 requested_at: Time.now.iso8601
+               },
+               resume_step: step.id,
+               prompt: resolve(state, config.prompt))
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/assign.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Assign < Base
+        Registry.register('assign', self)
+
+        def call(state)
+          state = config.set.reduce(state) do |s, (k, v)|
+            store(s, k, resolve(s, v))
+          end
+          continue(state)
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Base
+        attr_reader :step, :config
+
+        def initialize(step)
+          @step = step
+          @config = step.config
+        end
+
+        # Executors receive state and return StepOutcome
+        def call(state)
+          raise NotImplementedError
+        end
+
+        private
+
+        def next_step
+          step.next_step
+        end
+
+        # Pure resolve - takes state explicitly
+        def resolve(state, v)
+          Resolver.resolve(state, v)
+        end
+
+        # Return StepOutcome with continue result
+        def continue(state, next_step: nil, output: nil)
+          StepOutcome.new(
+            state:,
+            result: ContinueResult.new(next_step: next_step || self.next_step, output:)
+          )
+        end
+
+        # Return StepOutcome with halt result
+        def halt(state, data: {}, resume_step: nil, prompt: nil)
+          StepOutcome.new(
+            state:,
+            result: HaltResult.new(data:, resume_step: resume_step || next_step, prompt:)
+          )
+        end
+
+        # Immutable store - returns new state
+        def store(state, key, val)
+          return state unless key
+
+          state.with_ctx(key.to_sym => DurableWorkflow::Utils.deep_symbolize(val))
+        end
+
+        def with_timeout(seconds = nil, &)
+          timeout = seconds || config_timeout
+          return yield unless timeout
+
+          Timeout.timeout(timeout, &)
+        rescue Timeout::Error
+          raise ExecutionError, "Step '#{step.id}' timed out after #{timeout}s"
+        end
+
+        def with_retry(max_retries: 0, delay: 1.0, backoff: 2.0)
+          attempts = 0
+          begin
+            attempts += 1
+            yield
+          rescue StandardError => e
+            if attempts <= max_retries
+              sleep_time = delay * (backoff**(attempts - 1))
+              log(:warn, "Retry #{attempts}/#{max_retries} after #{sleep_time}s", error: e.message)
+              sleep(sleep_time)
+              retry
+            end
+            raise
+          end
+        end
+
+        def config_timeout
+          config.respond_to?(:timeout) ? config.timeout : nil
+        end
+
+        def log(level, msg, **data)
+          DurableWorkflow.log(level, msg, step_id: step.id, step_type: step.type, **data)
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/call.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Call < Base
+        Registry.register('call', self)
+
+        def call(state)
+          svc = resolve_service(config.service)
+          method = config.method_name
+          input = resolve(state, config.input)
+
+          result = with_retry(
+            max_retries: config.retries,
+            delay: config.retry_delay,
+            backoff: config.retry_backoff
+          ) do
+            with_timeout { invoke(svc, method, input) }
+          end
+
+          # Runtime schema validation (if schema defined)
+          validate_output!(result) if output_schema
+
+          state = store(state, output_key, result)
+          continue(state, output: result)
+        end
+
+        private
+
+        def resolve_service(name)
+          DurableWorkflow.config&.service_resolver&.call(name) || Object.const_get(name)
+        end
+
+        def invoke(svc, method, input)
+          target = svc.respond_to?(method) ? svc : svc.new
+          m = target.method(method)
+
+          # Check if method takes keyword args
+          has_kwargs = m.parameters.any? { |type, _| %i[key keyreq keyrest].include?(type) }
+
+          if has_kwargs && input.is_a?(Hash)
+            m.call(**input.transform_keys(&:to_sym))
+          elsif m.arity.zero?
+            m.call
+          else
+            m.call(input)
+          end
+        end
+
+        def output_key
+          case config.output
+          when Symbol, String then config.output
+          when OutputConfig then config.output.key
+          when Hash then config.output[:key]
+          end
+        end
+
+        def output_schema
+          case config.output
+          when OutputConfig then config.output.schema
+          when Hash then config.output[:schema]
+          end
+        end
+
+        def validate_output!(result)
+          SchemaValidator.validate!(
+            result,
+            output_schema,
+            context: "Step '#{step.id}' output"
+          )
+        end
+      end
+    end
+  end
+end