durable_workflow 0.1.0

data/lib/durable_workflow/core/validator.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    class Validator
+      FINISHED = '__FINISHED__'
+
+      def self.validate!(workflow)
+        new(workflow).validate!
+      end
+
+      def initialize(workflow)
+        @workflow = workflow
+        @errors = []
+        @step_index = workflow.steps.to_h { [_1.id, _1] }
+        @schemas = {} # step_id -> output schema
+      end
+
+      def validate!
+        check_unique_ids!
+        check_step_types!
+        check_references!
+        check_variable_reachability!
+        check_schema_compatibility!
+        check_reachability!
+
+        raise ValidationError, format_errors if @errors.any?
+
+        true
+      end
+
+      def valid?
+        validate!
+      rescue ValidationError
+        false
+      end
+
+      private
+
+      # ─────────────────────────────────────────────────────────────
+      # 0. Unique IDs
+      # ─────────────────────────────────────────────────────────────
+
+      def check_unique_ids!
+        ids = @workflow.steps.map(&:id)
+        dups = ids.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+        @errors << "Duplicate step IDs: #{dups.join(', ')}" if dups.any?
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # 1. Step Types Registered
+      # ─────────────────────────────────────────────────────────────
+
+      def check_step_types!
+        @workflow.steps.each do |step|
+          @errors << "Unknown step type '#{step.type}' in step '#{step.id}'" unless Executors::Registry.registered?(step.type)
+        end
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # 2. Step References Exist
+      # ─────────────────────────────────────────────────────────────
+
+      def check_references!
+        valid_ids = @step_index.keys.to_set << FINISHED
+
+        @workflow.steps.each do |step|
+          check_ref(step.id, 'next', step.next_step, valid_ids)
+          check_ref(step.id, 'on_error', step.on_error, valid_ids)
+
+          cfg = step.config
+          case step.type
+          when 'router'
+            cfg.routes&.each_with_index { |r, i| check_ref(step.id, "route[#{i}]", r.target, valid_ids) }
+            check_ref(step.id, 'default', cfg.default, valid_ids)
+          when 'loop'
+            check_ref(step.id, 'on_exhausted', cfg.on_exhausted, valid_ids)
+            cfg.do&.each { |s| check_ref(step.id, 'loop.do', s.next_step, valid_ids) }
+          when 'parallel'
+            cfg.branches&.each { |s| check_ref(step.id, 'branch', s.next_step, valid_ids) }
+          when 'halt'
+            check_ref(step.id, 'resume_step', cfg.resume_step, valid_ids)
+          when 'approval'
+            check_ref(step.id, 'on_reject', cfg.on_reject, valid_ids)
+            check_ref(step.id, 'on_timeout', cfg.on_timeout, valid_ids) if cfg.respond_to?(:on_timeout)
+          when 'guardrail'
+            check_ref(step.id, 'on_fail', cfg.on_fail, valid_ids) if cfg.respond_to?(:on_fail)
+          end
+        end
+      end
+
+      def check_ref(step_id, field, target, valid_ids)
+        return unless target
+        return if valid_ids.include?(target)
+
+        @errors << "Step '#{step_id}' #{field}: references unknown step '#{target}'"
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # 3. Variable Reachability
+      # ─────────────────────────────────────────────────────────────
+
+      def check_variable_reachability!
+        # Start with workflow inputs available
+        initial = Set.new(@workflow.inputs.map { _1.name.to_sym })
+        initial << :input  # $input always available
+        initial << :now    # $now always available
+        initial << :history # $history always available
+
+        first = @workflow.first_step
+        walk_steps(first, initial, Set.new) if first
+      end
+
+      def walk_steps(step, available, visited)
+        return if step.nil?
+
+        step_key = step.is_a?(String) ? step : step.id
+        step = @step_index[step_key] if step.is_a?(String)
+        return unless step
+        return if visited.include?(step.id)
+
+        visited = visited.dup << step.id
+
+        # Check references in this step
+        check_variable_references(step, available)
+
+        # Collect output schema if present
+        collect_schema(step)
+
+        # Add output to available set
+        available = available.dup
+        add_step_output(step, available)
+
+        # Recurse to all possible next steps
+        next_steps_for(step).each do |next_id|
+          walk_steps(next_id, available, visited)
+        end
+      end
+
+      def check_variable_references(step, available)
+        refs = extract_refs(step.config)
+
+        refs.each do |ref|
+          root = ref.split('.').first.to_sym
+          next if available.include?(root)
+
+          @errors << "Step '#{step.id}': references '$#{ref}' but '#{root}' not set by preceding step"
+        end
+      end
+
+      def add_step_output(step, available)
+        # Handle assign step's `set` hash
+        step.config.set.each_key { |k| available << k.to_sym } if step.config.respond_to?(:set) && step.config.set.is_a?(Hash)
+
+        # Handle output attribute
+        return unless step.config.respond_to?(:output) && step.config.output
+
+        key = case step.config.output
+              when Symbol, String then step.config.output
+              when OutputConfig then step.config.output.key
+              when Hash then step.config.output[:key]
+              end
+
+        available << key.to_sym if key
+      end
+
+      def next_steps_for(step)
+        steps = []
+        steps << step.next_step if step.next_step
+        steps << step.on_error if step.on_error
+
+        case step.type
+        when 'router'
+          steps.concat(step.config.routes.map(&:target))
+          steps << step.config.default if step.config.default
+        when 'loop'
+          steps << step.config.on_exhausted if step.config.on_exhausted
+        when 'approval'
+          steps << step.config.on_reject if step.config.on_reject
+          steps << step.config.on_timeout if step.config.respond_to?(:on_timeout) && step.config.on_timeout
+        when 'guardrail'
+          steps << step.config.on_fail if step.config.respond_to?(:on_fail) && step.config.on_fail
+        end
+
+        steps.compact.uniq
+      end
+
+      def extract_refs(obj, refs = [])
+        case obj
+        when String
+          obj.scan(/\$([a-zA-Z_][a-zA-Z0-9_.]*)/).flatten.each { refs << _1 }
+        when Hash
+          obj.each_value { extract_refs(_1, refs) }
+        when Array
+          obj.each { extract_refs(_1, refs) }
+        when BaseStruct
+          obj.to_h.each_value { extract_refs(_1, refs) }
+        end
+        refs
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # 4. Schema Compatibility
+      # ─────────────────────────────────────────────────────────────
+
+      def collect_schema(step)
+        return unless step.config.respond_to?(:output)
+
+        output = step.config.output
+        schema = case output
+                 when OutputConfig then output.schema
+                 when Hash then output[:schema]
+                 end
+
+        return unless schema
+
+        key = case output
+              when OutputConfig then output.key
+              when Hash then output[:key]
+              end
+
+        @schemas[key.to_sym] = schema if key
+      end
+
+      def check_schema_compatibility!
+        return if @schemas.empty?
+
+        @workflow.steps.each do |step|
+          refs = extract_refs(step.config)
+
+          refs.each do |ref|
+            parts = ref.split('.')
+            root = parts.first.to_sym
+
+            next unless @schemas.key?(root)
+            next if parts.size == 1 # Just $foo, not $foo.bar
+
+            validate_path_against_schema(step.id, ref, @schemas[root], parts[1..])
+          end
+        end
+      end
+
+      def validate_path_against_schema(step_id, full_ref, schema, path)
+        current = schema
+
+        path.each do |segment|
+          props = Utils.fetch(current, :properties)
+          unless props
+            @errors << "Step '#{step_id}': '$#{full_ref}' — schema has no properties"
+            return
+          end
+
+          prop = Utils.fetch(props, segment)
+          unless prop
+            available = props.keys.join(', ')
+            @errors << "Step '#{step_id}': '$#{full_ref}' — '#{segment}' not in schema (available: #{available})"
+            return
+          end
+
+          current = prop
+        end
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # 5. Reachability
+      # ─────────────────────────────────────────────────────────────
+
+      def check_reachability!
+        return if @workflow.steps.empty?
+
+        reachable = Set.new
+        queue = [@workflow.first_step.id]
+
+        while (id = queue.shift)
+          next if reachable.include?(id) || id == FINISHED
+
+          reachable << id
+          step = @step_index[id]
+          next unless step
+
+          queue << step.next_step if step.next_step
+          queue << step.on_error if step.on_error
+
+          cfg = step.config
+          case step.type
+          when 'router'
+            cfg.routes&.each { |r| queue << r.target }
+            queue << cfg.default if cfg.default
+          when 'loop'
+            cfg.do&.each { |s| queue << s.id }
+            queue << cfg.on_exhausted if cfg.on_exhausted
+          when 'parallel'
+            cfg.branches&.each { |s| queue << s.id }
+          when 'approval'
+            queue << cfg.on_reject if cfg.on_reject
+            queue << cfg.on_timeout if cfg.respond_to?(:on_timeout) && cfg.on_timeout
+          when 'guardrail'
+            queue << cfg.on_fail if cfg.respond_to?(:on_fail) && cfg.on_fail
+          end
+        end
+
+        unreachable = @workflow.step_ids - reachable.to_a
+        @errors << "Unreachable steps: #{unreachable.join(', ')}" if unreachable.any?
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Error Formatting
+      # ─────────────────────────────────────────────────────────────
+
+      def format_errors
+        [
+          "Workflow '#{@workflow.id}' validation failed:",
+          *@errors.map { "  - #{_1}" }
+        ].join("\n")
+      end
+    end
+  end
+end

data/lib/durable_workflow/extensions/ai/ai.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'mcp'
+
+require_relative 'types'
+require_relative 'configuration'
+require_relative 'tool_registry'
+
+# MCP components
+require_relative 'mcp/client'
+require_relative 'mcp/adapter'
+require_relative 'mcp/server'
+require_relative 'mcp/rack_app'
+
+require_relative 'executors/agent'
+require_relative 'executors/guardrail'
+require_relative 'executors/handoff'
+require_relative 'executors/file_search'
+require_relative 'executors/mcp'
+
+module DurableWorkflow
+  module Extensions
+    module AI
+      class Extension < Base
+        self.extension_name = 'ai'
+
+        def self.register_configs
+          Core.register_config('agent', AgentConfig)
+          Core.register_config('guardrail', GuardrailConfig)
+          Core.register_config('handoff', HandoffConfig)
+          Core.register_config('file_search', FileSearchConfig)
+          Core.register_config('mcp', MCPConfig)
+        end
+
+        def self.register_executors
+          Core::Executors::Registry.register('agent', Executors::Agent)
+          Core::Executors::Registry.register('guardrail', Executors::Guardrail)
+          Core::Executors::Registry.register('handoff', Executors::Handoff)
+          Core::Executors::Registry.register('file_search', Executors::FileSearch)
+          Core::Executors::Registry.register('mcp', Executors::MCP)
+        end
+
+        def self.register_parser_hooks
+          Core::Parser.after_parse do |workflow, raw_yaml|
+            raw = raw_yaml || workflow.to_h
+            ai_data = {
+              agents: parse_agents(raw[:agents]),
+              tools: parse_tools(raw[:tools]),
+              mcp_servers: parse_mcp_servers(raw)
+            }
+
+            # Register tools in ToolRegistry
+            ai_data[:tools].each_value { |td| ToolRegistry.register_from_def(td) }
+
+            # Return workflow with AI data stored
+            store_in(workflow, ai_data)
+          end
+        end
+
+        def self.parse_agents(agents)
+          return {} unless agents
+
+          agents.each_with_object({}) do |a, h|
+            agent = AgentDef.new(
+              id: a[:id],
+              name: a[:name],
+              model: a[:model],
+              instructions: a[:instructions],
+              tools: a[:tools] || [],
+              handoffs: parse_handoffs(a[:handoffs])
+            )
+            h[agent.id] = agent
+          end
+        end
+
+        def self.parse_handoffs(handoffs)
+          return [] unless handoffs
+
+          handoffs.map do |hd|
+            HandoffDef.new(
+              agent_id: hd[:agent_id],
+              description: hd[:description]
+            )
+          end
+        end
+
+        def self.parse_tools(tools)
+          return {} unless tools
+
+          tools.each_with_object({}) do |t, h|
+            tool = ToolDef.new(
+              id: t[:id],
+              description: t[:description],
+              parameters: parse_tool_params(t[:parameters]),
+              service: t[:service],
+              method_name: t[:method]
+            )
+            h[tool.id] = tool
+          end
+        end
+
+        def self.parse_tool_params(params)
+          return [] unless params
+
+          params.map do |p|
+            ToolParam.new(
+              name: p[:name],
+              type: p[:type],
+              required: p.fetch(:required, true),
+              description: p[:description]
+            )
+          end
+        end
+
+        def self.parse_mcp_servers(raw)
+          return {} unless raw[:mcp_servers]
+
+          raw[:mcp_servers].transform_values do |config|
+            MCPServerConfig.new(
+              url: config[:url],
+              headers: config[:headers],
+              transport: config[:transport]&.to_sym,
+              command: config[:command]
+            )
+          end
+        end
+
+        # Helper to get agents from workflow
+        def self.agents(workflow)
+          data_from(workflow)[:agents] || {}
+        end
+
+        # Helper to get tools from workflow
+        def self.tools(workflow)
+          data_from(workflow)[:tools] || {}
+        end
+
+        # Helper to get mcp_servers from workflow
+        def self.mcp_servers(workflow)
+          data_from(workflow)[:mcp_servers] || {}
+        end
+      end
+    end
+  end
+end
+
+# Auto-register
+DurableWorkflow::Extensions.register(:ai, DurableWorkflow::Extensions::AI::Extension)

data/lib/durable_workflow/extensions/ai/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Extensions
+    module AI
+      class Configuration
+        attr_accessor :default_model, :api_keys
+
+        def initialize
+          @default_model = 'gpt-4o-mini'
+          @api_keys = {}
+        end
+      end
+
+      class << self
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        def configure
+          yield configuration if block_given?
+          apply_ruby_llm_config
+          configuration
+        end
+
+        def chat(model: nil)
+          RubyLLM.chat(model: model || configuration.default_model)
+        end
+
+        private
+
+        def apply_ruby_llm_config
+          RubyLLM.configure do |c|
+            c.openai_api_key = configuration.api_keys[:openai] if configuration.api_keys[:openai]
+            c.anthropic_api_key = configuration.api_keys[:anthropic] if configuration.api_keys[:anthropic]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/extensions/ai/executors/agent.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Extensions
+    module AI
+      module Executors
+        class Agent < Core::Executors::Base
+          MAX_TOOL_ITERATIONS = 10
+
+          def call(state)
+            @current_state = state
+
+            agent_id = config.agent_id
+            agent = Extension.agents(workflow(state))[agent_id]
+            raise ExecutionError, "Agent not found: #{agent_id}" unless agent
+
+            prompt = resolve(state, config.prompt)
+            tool_classes = build_tool_classes(state, agent)
+
+            response = run_agent_loop(state, agent, prompt, tool_classes)
+
+            state = @current_state
+            content = response.content.respond_to?(:text) ? response.content.text : response.content.to_s
+            state = store(state, config.output, content)
+            continue(state, output: content)
+          end
+
+          private
+
+          def workflow(state)
+            DurableWorkflow.registry[state.workflow_id]
+          end
+
+          def build_chat(agent)
+            AI.chat(model: agent.model)
+          end
+
+          def build_tool_classes(_state, agent)
+            return [] if agent.tools.empty? && agent.handoffs.empty?
+
+            tool_classes = []
+
+            # Get RubyLLM::Tool classes from registry
+            agent.tools.each do |tool_id|
+              tool_class = ToolRegistry[tool_id]
+              tool_classes << tool_class if tool_class
+            end
+
+            # Create handoff tools
+            agent.handoffs.each do |handoff|
+              tool_classes << build_handoff_tool(handoff)
+            end
+
+            tool_classes
+          end
+
+          def build_handoff_tool(handoff)
+            target_agent_id = handoff.agent_id
+            tool_description = handoff.description || "Transfer to #{target_agent_id}"
+            executor_ref = self
+            tool_name = "transfer_to_#{target_agent_id}"
+
+            # Create named handoff tool class
+            class_name = "TransferTo#{target_agent_id.split('_').map(&:capitalize).join}"
+            return GeneratedTools.const_get(class_name) if GeneratedTools.const_defined?(class_name)
+
+            GeneratedTools.const_set(class_name, Class.new(RubyLLM::Tool) do
+              description tool_description
+
+              # Override name to avoid long namespace in tool name
+              define_method(:name) { tool_name }
+
+              define_method(:execute) do
+                executor_ref.instance_variable_get(:@current_state).tap do
+                  new_state = executor_ref.instance_variable_get(:@current_state)
+                                         .with_ctx(_handoff_to: target_agent_id)
+                  executor_ref.instance_variable_set(:@current_state, new_state)
+                end
+                "Transferring to #{target_agent_id}"
+              end
+            end)
+          end
+
+          def run_agent_loop(state, agent, prompt, tool_classes)
+            iterations = 0
+            chat = build_chat(agent)
+
+            # Add tools to chat
+            tool_classes.each { |tc| chat.with_tool(tc) }
+
+            # Build full prompt with system instructions
+            full_prompt = if agent.instructions
+                            "System: #{agent.instructions}\n\nUser: #{prompt}"
+                          else
+                            prompt
+                          end
+
+            # Main agent loop
+            loop do
+              iterations += 1
+              raise ExecutionError, "Agent exceeded max iterations (#{MAX_TOOL_ITERATIONS})" if iterations > MAX_TOOL_ITERATIONS
+
+              response = chat.ask(full_prompt)
+
+              # If no tool calls, we're done
+              return response unless response.tool_call?
+
+              # Execute tool calls and continue
+              response.tool_calls.each do |tool_call|
+                tool_name = begin
+                  tool_call.name
+                rescue StandardError
+                  Utils.fetch(tool_call, :name)
+                end
+                arguments = begin
+                  tool_call.arguments
+                rescue StandardError
+                  (Utils.fetch(tool_call, :arguments) || {})
+                end
+
+                result = execute_tool_call(state, tool_name, arguments)
+                full_prompt = "Tool #{tool_name} returned: #{result}"
+              end
+            end
+          end
+
+          def execute_tool_call(_state, tool_name, arguments)
+            # Check for handoff tools
+            if tool_name.start_with?('transfer_to_') || tool_name.match?(/^TransferTo/)
+              target_agent = tool_name.sub(/^transfer_to_/, '').sub(/^TransferTo/, '')
+                                      .gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
+              @current_state = @current_state.with_ctx(_handoff_to: target_agent)
+              return "Transferring to #{target_agent}"
+            end
+
+            # Execute via ToolRegistry
+            tool_class = ToolRegistry[tool_name]
+            raise ExecutionError, "Tool not found: #{tool_name}" unless tool_class
+
+            tool_instance = tool_class.new
+            args = arguments.is_a?(Hash) ? arguments.transform_keys(&:to_sym) : {}
+            tool_instance.call(**args)
+          rescue StandardError => e
+            "Error: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end