language-operator 0.1.31 → 0.1.35

data/lib/language_operator/agent/safety/safe_executor.rb

@@ -34,10 +34,32 @@ module LanguageOperator
           # Step 2: Execute in sandboxed context
           sandbox = SandboxProxy.new(@context, self)
 
-          # Step 3: Execute using instance_eval
+          # Step 3: Prepend safe constant definitions to the code
+          # This makes Ruby type constants available in the evaluated scope
+          safe_constants_code = <<~RUBY
+            Numeric = ::Numeric
+            Integer = ::Integer
+            Float = ::Float
+            String = ::String
+            Array = ::Array
+            Hash = ::Hash
+            TrueClass = ::TrueClass
+            FalseClass = ::FalseClass
+            Time = ::Time
+            Date = ::Date
+          RUBY
+
+          # Step 4: Execute using instance_eval with safe constants prepended
           # Note: We still use instance_eval but with validated code
           # and wrapped context
-          sandbox.instance_eval(code, file_path)
+          #
+          # The string interpolation below evaluates to:
+          #   sandbox.instance_eval("Numeric = ::Numeric\nInteger = ::Integer\nFloat = ::Float\n
+          #     String = ::String\nArray = ::Array\nHash = ::Hash\nTrueClass = ::TrueClass\n
+          #     FalseClass = ::FalseClass\nTime = ::Time\nDate = ::Date\n<user code>", __FILE__, __LINE__)
+          # rubocop:disable Style/DocumentDynamicEvalDefinition
+          sandbox.instance_eval("#{safe_constants_code}\n#{code}", __FILE__, __LINE__)
+          # rubocop:enable Style/DocumentDynamicEvalDefinition
         rescue ASTValidator::SecurityError => e
           # Re-raise validation errors as executor errors for clarity
           raise SecurityError, "Code validation failed: #{e.message}"
@@ -104,6 +126,9 @@ module LanguageOperator
               return ::LanguageOperator::Dsl::Shell
             end
 
+            # Ruby type constants are now injected at eval time (see SafeExecutor#eval)
+            # but keep this as fallback for dynamic constant access
+
             # Otherwise delegate to the context's module
             @__context__.class.const_get(name)
           rescue ::NameError

data/lib/language_operator/agent/scheduler.rb

@@ -84,6 +84,51 @@ module LanguageOperator
         @rufus_scheduler.join
       end
 
+      # Start the scheduler with a main block (DSL v1)
+      #
+      # @param agent_def [LanguageOperator::Dsl::AgentDefinition] The agent definition with main block
+      # @return [void]
+      def start_with_main(agent_def)
+        logger.info('Agent starting in scheduled mode with main block',
+                    agent_name: agent_def.name,
+                    task_count: agent_def.tasks.size)
+        logger.info("Workspace: #{@agent.workspace_path}")
+        logger.info("Connected to #{@agent.servers_info.length} MCP server(s)")
+
+        # Extract schedule from agent definition or use default
+        cron_schedule = agent_def.schedule&.cron || '0 6 * * *'
+
+        logger.info('Scheduling main block execution', cron: cron_schedule, agent: agent_def.name)
+
+        # Create task executor with constraints config
+        require_relative 'task_executor'
+        config = build_executor_config(agent_def)
+        task_executor = TaskExecutor.new(@agent, agent_def.tasks, config)
+
+        @rufus_scheduler.cron(cron_schedule) do
+          with_span('agent.scheduler.execute', attributes: {
+                      'scheduler.cron_expression' => cron_schedule,
+                      'agent.name' => agent_def.name,
+                      'scheduler.task_type' => 'main_block'
+                    }) do
+            logger.timed('Scheduled main block execution') do
+              logger.info('Executing scheduled main block', agent: agent_def.name)
+
+              # Get inputs from environment or default to empty hash
+              inputs = {}
+
+              # Execute main block
+              result = agent_def.main.call(inputs, task_executor)
+
+              logger.info('Main block completed', result: result)
+            end
+          end
+        end
+
+        logger.info('Scheduler started, waiting for scheduled tasks')
+        @rufus_scheduler.join
+      end
+
       # Stop the scheduler
       #
       # @return [void]
@@ -178,6 +223,21 @@ module LanguageOperator
 
         logger.info('Scheduled: Daily at 6:00 AM')
       end
+
+      # Build executor configuration from agent definition constraints
+      #
+      # @param agent_def [LanguageOperator::Dsl::AgentDefinition] The agent definition
+      # @return [Hash] Executor configuration
+      def build_executor_config(agent_def)
+        config = {}
+
+        if agent_def.constraints
+          config[:timeout] = agent_def.constraints[:timeout] if agent_def.constraints[:timeout]
+          config[:max_retries] = agent_def.constraints[:max_retries] if agent_def.constraints[:max_retries]
+        end
+
+        config
+      end
     end
   end
 end

data/lib/language_operator/agent/task_executor.rb

@@ -0,0 +1,548 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require 'socket'
+require_relative '../loggable'
+require_relative 'instrumentation'
+require_relative '../instrumentation/task_tracer'
+
+module LanguageOperator
+  module Agent
+    # Custom error classes for task execution
+    class TaskExecutionError < StandardError
+      attr_reader :task_name, :original_error
+
+      def initialize(task_name, message, original_error = nil)
+        @task_name = task_name
+        @original_error = original_error
+        super("Task '#{task_name}' execution failed: #{message}")
+      end
+    end
+
+    class TaskValidationError < TaskExecutionError
+    end
+
+    class TaskTimeoutError < TaskExecutionError
+    end
+
+    # Task Executor for DSL v1 organic functions
+    #
+    # Executes both neural (LLM-based) and symbolic (code-based) tasks.
+    # Provides the `execute_task` method that MainDefinition blocks use
+    # to invoke tasks transparently regardless of implementation type.
+    #
+    # @example Executing a task
+    #   executor = TaskExecutor.new(agent, tasks_registry)
+    #   result = executor.execute_task(:fetch_data, inputs: { user_id: 123 })
+    #
+    # @example In a main block
+    #   main do |inputs|
+    #     data = execute_task(:fetch_data, inputs: inputs)
+    #     execute_task(:process_data, inputs: data)
+    #   end
+    class TaskExecutor
+      include LanguageOperator::Loggable
+      include Instrumentation
+      include LanguageOperator::Instrumentation::TaskTracer
+
+      # Error types that should be retried
+      RETRYABLE_ERRORS = [
+        Timeout::Error,
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Errno::ETIMEDOUT,
+        SocketError
+      ].freeze
+
+      # Error categories for logging and operator integration
+      ERROR_CATEGORIES = {
+        validation: 'VALIDATION',
+        execution: 'EXECUTION',
+        timeout: 'TIMEOUT',
+        network: 'NETWORK',
+        system: 'SYSTEM'
+      }.freeze
+
+      attr_reader :agent, :tasks, :config
+
+      # Initialize the task executor
+      #
+      # @param agent [LanguageOperator::Agent::Base] The agent instance (provides LLM client, tools)
+      # @param tasks [Hash<Symbol, TaskDefinition>] Registry of task definitions
+      # @param config [Hash] Execution configuration
+      def initialize(agent, tasks = {}, config = {})
+        @agent = agent
+        @tasks = tasks
+        @config = default_config.merge(config)
+        logger.debug('TaskExecutor initialized',
+                     task_count: @tasks.size,
+                     timeout: @config[:timeout],
+                     max_retries: @config[:max_retries])
+      end
+
+      # Execute a task by name with given inputs
+      #
+      # This is the main entry point called from MainDefinition blocks.
+      # Routes to neural or symbolic execution based on task implementation.
+      # Includes timeout, retry logic, and comprehensive error handling.
+      #
+      # @param task_name [Symbol] Name of the task to execute
+      # @param inputs [Hash] Input parameters for the task
+      # @param timeout [Numeric] Override timeout for this task (seconds)
+      # @param max_retries [Integer] Override max retries for this task
+      # @return [Hash] Validated output from the task
+      # @raise [ArgumentError] If task not found or inputs invalid
+      # @raise [TaskExecutionError] If task execution fails after retries
+      def execute_task(task_name, inputs: {}, timeout: nil, max_retries: nil)
+        execution_start = Time.now
+        timeout ||= @config[:timeout]
+        max_retries ||= @config[:max_retries]
+
+        with_span('task_executor.execute_task', attributes: {
+                    'task.name' => task_name.to_s,
+                    'task.inputs' => inputs.keys.map(&:to_s).join(','),
+                    'task.timeout' => timeout,
+                    'task.max_retries' => max_retries
+                  }) do
+          # Find task definition
+          task = @tasks[task_name.to_sym]
+          raise ArgumentError, "Task not found: #{task_name}. Available tasks: #{@tasks.keys.join(', ')}" unless task
+
+          task_type = determine_task_type(task)
+          logger.info('Executing task',
+                      task: task_name,
+                      type: task_type,
+                      timeout: timeout,
+                      max_retries: max_retries)
+
+          # Execute with retry logic
+          execute_with_retry(task, task_name, inputs, timeout, max_retries, execution_start)
+        end
+      rescue ArgumentError => e
+        # Validation errors should not be retried - re-raise immediately
+        log_task_error(task_name, e, :validation, execution_start)
+        raise TaskValidationError.new(task_name, e.message, e)
+      rescue StandardError => e
+        # Catch any unexpected errors that escaped retry logic
+        log_task_error(task_name, e, :system, execution_start)
+        raise create_appropriate_error(task_name, e)
+      end
+
+      # Execute a neural task (instructions-based, LLM-driven)
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param inputs [Hash] Input parameters
+      # @return [Hash] Validated outputs
+      # @raise [StandardError] If LLM execution fails or output validation fails
+      def execute_neural(task, inputs)
+        # Validate inputs first
+        validated_inputs = task.validate_inputs(inputs)
+
+        logger.debug('Executing neural task',
+                     task: task.name,
+                     instructions: task.instructions_text,
+                     inputs: validated_inputs)
+
+        # Build prompt for LLM
+        prompt = build_neural_prompt(task, validated_inputs)
+
+        # Execute LLM call within traced span
+        outputs = tracer.in_span('gen_ai.chat', attributes: neural_task_attributes(task, prompt, validated_inputs)) do |span|
+          # Call LLM with full tool access
+          response = @agent.send_message(prompt)
+          response_text = response.is_a?(String) ? response : response.content
+
+          logger.debug('Neural task response received',
+                       task: task.name,
+                       response_length: response_text.length)
+
+          # Record token usage and response metadata
+          record_token_usage(response, span)
+
+          # Record tool calls if available
+          record_tool_calls(response, span)
+
+          # Parse response within child span
+          parsed_outputs = tracer.in_span('task_executor.parse_response') do |parse_span|
+            record_parse_metadata(response_text, parse_span)
+            parse_neural_response(response_text, task)
+          end
+
+          # Record output metadata
+          record_output_metadata(parsed_outputs, span)
+
+          parsed_outputs
+        end
+
+        # Validate outputs against schema
+        task.validate_outputs(outputs)
+      end
+
+      # Helper method for symbolic tasks to execute tools
+      #
+      # This is a simplified interface - symbolic tasks should primarily use
+      # execute_llm to leverage tools through the LLM interface, or call tools
+      # directly through the MCP client if needed.
+      #
+      # @param tool_name [String] Name of the tool
+      # @param action [String] Tool action/method
+      # @param params [Hash] Tool parameters
+      # @return [Object] Tool response
+      # @note For DSL v1, tools are accessed via LLM tool calling, not direct invocation
+      def execute_tool(tool_name, action, params = {})
+        # Build prompt to use the tool via LLM
+        prompt = "Use the #{tool_name} tool to perform #{action} with parameters: #{params.inspect}"
+        execute_llm(prompt)
+        # Parse response - for now just return the text
+        # TODO: More sophisticated tool result extraction
+      end
+
+      # Helper method for symbolic tasks to call LLM directly
+      #
+      # @param prompt [String] Prompt to send to LLM
+      # @return [String] LLM response
+      def execute_llm(prompt)
+        response = @agent.send_message(prompt)
+        response.is_a?(String) ? response : response.content
+      end
+
+      # Execute multiple tasks in parallel
+      #
+      # Provides explicit parallelism for task execution. Users specify which tasks
+      # should run in parallel, and this method handles the concurrent execution.
+      #
+      # @param tasks [Array<Hash>] Array of task specifications
+      # @param in_threads [Integer] Number of threads to use (default: 4)
+      # @return [Array] Results from all tasks in the same order as input
+      # @raise [RuntimeError] If any task fails
+      #
+      # @example Execute multiple independent tasks
+      #   results = execute_parallel([
+      #     { name: :fetch_source1 },
+      #     { name: :fetch_source2 }
+      #   ])
+      #   # => [result1, result2]
+      #
+      # @example With inputs
+      #   results = execute_parallel([
+      #     { name: :process, inputs: { data: data1 } },
+      #     { name: :analyze, inputs: { data: data2 } }
+      #   ])
+      #
+      def execute_parallel(tasks, in_threads: 4)
+        require 'parallel'
+
+        logger.info('Executing tasks in parallel', count: tasks.size, threads: in_threads)
+
+        results = Parallel.map(tasks, in_threads: in_threads) do |task_spec|
+          task_name = task_spec[:name]
+          task_inputs = task_spec[:inputs] || {}
+
+          execute_task(task_name, inputs: task_inputs)
+        end
+
+        logger.info('Parallel execution complete', results_count: results.size)
+        results
+      rescue Parallel::DeadWorker => e
+        logger.error('Parallel execution failed - worker died', error: e.message)
+        raise "Parallel task execution failed: #{e.message}"
+      rescue StandardError => e
+        logger.error('Parallel execution failed', error: e.class.name, message: e.message)
+        raise
+      end
+
+      private
+
+      def logger_component
+        'Agent::TaskExecutor'
+      end
+
+      # Build prompt for neural task execution
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param inputs [Hash] Validated input parameters
+      # @return [String] Prompt for LLM
+      def build_neural_prompt(task, inputs)
+        prompt = "# Task: #{task.name}\n\n"
+        prompt += "## Instructions\n#{task.instructions_text}\n\n"
+
+        if inputs.any?
+          prompt += "## Inputs\n"
+          inputs.each do |key, value|
+            prompt += "- #{key}: #{value.inspect}\n"
+          end
+          prompt += "\n"
+        end
+
+        prompt += "## Output Schema\n"
+        prompt += "You must return a JSON object with the following fields:\n"
+        task.outputs_schema.each do |key, type|
+          prompt += "- #{key} (#{type})\n"
+        end
+        prompt += "\n"
+
+        prompt += 'Return ONLY valid JSON matching the output schema. '
+        prompt += "Use available tools as needed to complete the task.\n"
+
+        prompt
+      end
+
+      # Parse LLM response to extract output values
+      #
+      # @param response_text [String] LLM response
+      # @param task [TaskDefinition] Task definition for schema
+      # @return [Hash] Parsed outputs
+      # @raise [RuntimeError] If parsing fails
+      def parse_neural_response(response_text, task)
+        # Try to extract JSON from response
+        # Look for JSON code blocks first
+        json_match = response_text.match(/```json\s*\n(.*?)\n```/m)
+        json_text = if json_match
+                      json_match[1]
+                    else
+                      # Try to find raw JSON object
+                      json_object_match = response_text.match(/\{.*\}/m)
+                      json_object_match ? json_object_match[0] : response_text
+                    end
+
+        # Parse JSON
+        parsed = JSON.parse(json_text)
+
+        # Deep convert all string keys to symbols (including nested hashes and arrays)
+        deep_symbolize_keys(parsed)
+      rescue JSON::ParserError => e
+        logger.error('Failed to parse neural task response as JSON',
+                     task: task.name,
+                     response: response_text[0..200],
+                     error: e.message)
+        raise "Neural task '#{task.name}' returned invalid JSON: #{e.message}"
+      end
+
+      # Recursively convert all hash keys to symbols
+      def deep_symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize_keys(v) }
+        when Array
+          obj.map { |item| deep_symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+
+      # Default configuration for task execution
+      #
+      # @return [Hash] Default configuration
+      def default_config
+        {
+          timeout: 30.0,           # Default timeout in seconds
+          max_retries: 3,          # Default max retry attempts
+          retry_delay_base: 1.0,   # Base delay for exponential backoff
+          retry_delay_max: 10.0    # Maximum delay between retries
+        }
+      end
+
+      # Determine task type for logging and telemetry
+      #
+      # @param task [TaskDefinition] The task definition
+      # @return [String] Task type
+      def determine_task_type(task)
+        if task.neural? && task.symbolic?
+          'hybrid'
+        elsif task.neural?
+          'neural'
+        elsif task.symbolic?
+          'symbolic'
+        else
+          'undefined'
+        end
+      end
+
+      # Execute task with retry logic and timeout
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param task_name [Symbol] Name of the task
+      # @param inputs [Hash] Input parameters
+      # @param timeout [Numeric] Timeout in seconds
+      # @param max_retries [Integer] Maximum retry attempts
+      # @param execution_start [Time] When execution started
+      # @return [Hash] Task outputs
+      def execute_with_retry(task, task_name, inputs, timeout, max_retries, execution_start)
+        attempt = 0
+        last_error = nil
+
+        while attempt <= max_retries
+          begin
+            return execute_single_attempt(task, task_name, inputs, timeout, attempt, execution_start)
+          rescue StandardError => e
+            last_error = e
+            attempt += 1
+
+            # Don't retry validation errors or non-retryable errors
+            unless retryable_error?(e) && attempt <= max_retries
+              # Re-raise ArgumentError so it gets caught by the ArgumentError rescue block
+              raise e if e.is_a?(ArgumentError)
+
+              log_task_error(task_name, e, categorize_error(e), execution_start, attempt - 1)
+              raise create_appropriate_error(task_name, e)
+            end
+
+            # Calculate delay for exponential backoff
+            delay = calculate_retry_delay(attempt - 1)
+            logger.warn('Task execution failed, retrying',
+                        task: task_name,
+                        attempt: attempt,
+                        max_retries: max_retries,
+                        error: e.class.name,
+                        message: e.message,
+                        retry_delay: delay)
+
+            sleep(delay) if delay.positive?
+          end
+        end
+
+        # If we get here, we've exhausted all retries
+        log_task_error(task_name, last_error, categorize_error(last_error), execution_start, max_retries)
+        raise create_appropriate_error(task_name, last_error)
+      end
+
+      # Execute a single attempt of a task with timeout
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param task_name [Symbol] Name of the task
+      # @param inputs [Hash] Input parameters
+      # @param timeout [Numeric] Timeout in seconds
+      # @param attempt [Integer] Current attempt number
+      # @param execution_start [Time] When execution started
+      # @return [Hash] Task outputs
+      def execute_single_attempt(task, task_name, inputs, timeout, attempt, _execution_start)
+        attempt_start = Time.now
+
+        result = if timeout.positive?
+                   Timeout.timeout(timeout) do
+                     execute_task_implementation(task, inputs)
+                   end
+                 else
+                   execute_task_implementation(task, inputs)
+                 end
+
+        execution_time = Time.now - attempt_start
+        logger.debug('Task execution completed',
+                     task: task_name,
+                     attempt: attempt + 1,
+                     execution_time: execution_time.round(3))
+
+        result
+      rescue Timeout::Error => e
+        execution_time = Time.now - attempt_start
+        logger.warn('Task execution timed out',
+                    task: task_name,
+                    attempt: attempt + 1,
+                    timeout: timeout,
+                    execution_time: execution_time.round(3))
+        raise TaskTimeoutError.new(task_name, "timed out after #{timeout}s", e)
+      end
+
+      # Execute the actual task implementation (neural or symbolic)
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param inputs [Hash] Input parameters
+      # @return [Hash] Task outputs
+      def execute_task_implementation(task, inputs)
+        if task.neural?
+          # Neural execution: LLM with tool access
+          execute_neural(task, inputs)
+        else
+          # Symbolic execution: Direct Ruby code within traced span
+          tracer.in_span('task_executor.symbolic', attributes: symbolic_task_attributes(task)) do |span|
+            validated_inputs = task.validate_inputs(inputs)
+            span.set_attribute('task.input.keys', validated_inputs.keys.map(&:to_s).join(','))
+            span.set_attribute('task.input.count', validated_inputs.size)
+
+            # Pass self as context so symbolic tasks can call execute_task, execute_tool, etc.
+            outputs = task.call(validated_inputs, self)
+
+            record_output_metadata(outputs, span) if outputs.is_a?(Hash)
+            outputs
+          end
+        end
+      end
+
+      # Check if an error should be retried
+      #
+      # @param error [Exception] The error that occurred
+      # @return [Boolean] Whether the error should be retried
+      def retryable_error?(error)
+        RETRYABLE_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      # Categorize error for logging and operator integration
+      #
+      # @param error [Exception] The error that occurred
+      # @return [Symbol] Error category
+      def categorize_error(error)
+        case error
+        when ArgumentError, TaskValidationError
+          :validation
+        when Timeout::Error, TaskTimeoutError
+          :timeout
+        when TaskExecutionError
+          # Check the original error for categorization
+          error.original_error ? categorize_error(error.original_error) : :execution
+        when *RETRYABLE_ERRORS
+          :network
+        else
+          :execution
+        end
+      end
+
+      # Calculate retry delay with exponential backoff
+      #
+      # @param attempt [Integer] Current attempt number (0-based)
+      # @return [Float] Delay in seconds
+      def calculate_retry_delay(attempt)
+        delay = @config[:retry_delay_base] * (2**attempt)
+        [delay, @config[:retry_delay_max]].min
+      end
+
+      # Create appropriate error type based on original error
+      #
+      # @param task_name [Symbol] Name of the task
+      # @param original_error [Exception] The original error
+      # @return [TaskExecutionError] Appropriate error type
+      def create_appropriate_error(task_name, original_error)
+        case original_error
+        when TaskTimeoutError
+          original_error
+        when Timeout::Error
+          TaskTimeoutError.new(task_name, 'timed out', original_error)
+        when ArgumentError
+          TaskValidationError.new(task_name, original_error.message, original_error)
+        else
+          TaskExecutionError.new(task_name, original_error.message, original_error)
+        end
+      end
+
+      # Log task error with comprehensive context
+      #
+      # @param task_name [Symbol] Name of the task
+      # @param error [Exception] The error that occurred
+      # @param category [Symbol] Error category
+      # @param execution_start [Time] When execution started
+      # @param retry_count [Integer] Number of retries attempted
+      def log_task_error(task_name, error, category, execution_start, retry_count = 0)
+        execution_time = Time.now - execution_start
+
+        logger.error('Task execution failed',
+                     task: task_name,
+                     error_category: ERROR_CATEGORIES[category],
+                     error_class: error.class.name,
+                     error_message: error.message,
+                     execution_time: execution_time.round(3),
+                     retry_count: retry_count,
+                     retryable: retryable_error?(error),
+                     backtrace: error.backtrace&.first(5))
+      end
+    end
+  end
+end