language-operator 0.1.59 → 0.1.62

data/lib/language_operator/agent/task_executor.rb

@@ -25,6 +25,9 @@ module LanguageOperator
     class TaskTimeoutError < TaskExecutionError
     end
 
+    class TaskNetworkError < TaskExecutionError
+    end
+
     # Task Executor for DSL v1 organic functions
     #
     # Executes both neural (LLM-based) and symbolic (code-based) tasks.
@@ -74,6 +77,11 @@ module LanguageOperator
         @agent = agent
         @tasks = tasks
         @config = default_config.merge(config)
+
+        # Pre-cache task lookup and timeout information for performance
+        @task_cache = build_task_cache
+        @task_timeouts = build_timeout_cache
+
         logger.debug('TaskExecutor initialized',
                      task_count: @tasks.size,
                      timeout_symbolic: @config[:timeout_symbolic],
@@ -104,21 +112,26 @@ module LanguageOperator
                     'task.inputs' => inputs.keys.map(&:to_s).join(','),
                     '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
+          # Fast task lookup using pre-built cache
+          task_name_sym = task_name.to_sym
+          task_info = @task_cache[task_name_sym]
+          raise ArgumentError, "Task not found: #{task_name}. Available tasks: #{@tasks.keys.join(', ')}" unless task_info
 
-          task_type = determine_task_type(task)
+          task = task_info[:definition]
+          task_type = task_info[:type]
 
-          # Determine timeout based on task type if not explicitly provided
-          timeout ||= task_timeout_for_type(task)
+          # Use cached timeout if not explicitly provided
+          timeout ||= @task_timeouts[task_name_sym]
 
-          logger.info('Executing task',
-                      task: task_name,
-                      type: task_type,
-                      timeout: timeout,
-                      max_retries: max_retries,
-                      inputs: summarize_values(inputs))
+          # Optimize logging - only log if debug level enabled or log_executions is true
+          if logger.logger.level <= ::Logger::DEBUG || @config[:log_executions]
+            logger.info('Executing task',
+                        task: task_name,
+                        type: task_type,
+                        timeout: timeout,
+                        max_retries: max_retries,
+                        inputs: summarize_values(inputs))
+          end
 
           # Add timeout to span attributes after it's determined
           OpenTelemetry::Trace.current_span&.set_attribute('task.timeout', timeout)
@@ -190,10 +203,46 @@ module LanguageOperator
           logger.info('Parsing neural task response',
                       task: task.name)
 
-          # Parse response within child span
+          # Parse response within child span with retry logic
           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)
+
+            begin
+              parse_neural_response(response_text, task)
+            rescue RuntimeError => e
+              # If parsing fails and this is a JSON parsing error, try one more time with clarified prompt
+              raise e unless e.message.include?('returned invalid JSON') && !defined?(@parsing_retry_attempted)
+
+              @parsing_retry_attempted = true
+
+              logger.warn('JSON parsing failed, retrying with clarified prompt',
+                          task: task.name,
+                          original_error: e.message,
+                          response_preview: response_text[0..300])
+
+              # Build retry prompt with clearer instructions
+              retry_prompt = build_parsing_retry_prompt(task, validated_inputs, response_text, e.message)
+
+              logger.info('Retrying LLM call with clarified prompt',
+                          task: task.name,
+                          retry_prompt_length: retry_prompt.length)
+
+              # Retry LLM call
+              retry_response = @agent.send_message(retry_prompt)
+              retry_response_text = retry_response.is_a?(String) ? retry_response : retry_response.content
+
+              logger.info('Parsing retry response',
+                          task: task.name,
+                          retry_response_length: retry_response_text.length)
+
+              # Try parsing the retry response
+              parse_neural_response(retry_response_text, task)
+
+            # Re-raise original error if not a JSON parsing error or already retried
+            ensure
+              # Reset retry flag for next task
+              @parsing_retry_attempted = nil
+            end
           end
 
           logger.info('Response parsed successfully',
@@ -234,19 +283,28 @@ module LanguageOperator
         # Execute the tool (it's a Proc/lambda wrapped by RubyLLM)
         result = tool.call(**params)
 
+        # Extract text from MCP Content objects
+        text_result = if result.is_a?(RubyLLM::MCP::Content)
+                        result.text
+                      elsif result.respond_to?(:map) && result.first.is_a?(RubyLLM::MCP::Content)
+                        result.map(&:text).join
+                      else
+                        result
+                      end
+
         logger.debug('Tool call completed',
                      tool: tool_name_str,
-                     result_preview: result.is_a?(String) ? result[0..200] : result.class.name)
+                     result_preview: text_result.is_a?(String) ? text_result[0..200] : text_result.class.name)
 
         # Try to parse JSON response if it looks like JSON
-        if result.is_a?(String) && (result.strip.start_with?('{') || result.strip.start_with?('['))
-          JSON.parse(result, symbolize_names: true)
+        if text_result.is_a?(String) && (text_result.strip.start_with?('{') || text_result.strip.start_with?('['))
+          JSON.parse(text_result, symbolize_names: true)
         else
-          result
+          text_result
         end
       rescue JSON::ParserError
         # Not JSON, return as-is
-        result
+        text_result
       end
 
       # Helper method for symbolic tasks to call LLM directly
@@ -284,13 +342,19 @@ module LanguageOperator
       def execute_parallel(tasks, in_threads: 4)
         require 'parallel'
 
+        # Capture current OpenTelemetry context before parallel execution
+        current_context = OpenTelemetry::Context.current
+
         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] || {}
+          # Restore OpenTelemetry context in worker thread
+          OpenTelemetry::Context.with_current(current_context) do
+            task_name = task_spec[:name]
+            task_inputs = task_spec[:inputs] || {}
 
-          execute_task(task_name, inputs: task_inputs)
+            execute_task(task_name, inputs: task_inputs)
+          end
         end
 
         logger.info('Parallel execution complete', results_count: results.size)
@@ -310,22 +374,41 @@ module LanguageOperator
       end
 
       # Summarize hash values for logging (truncate long strings)
+      # Optimized for performance with lazy computation
       #
       # @param hash [Hash] Hash to summarize
       # @return [Hash] Summarized hash with truncated values
       def summarize_values(hash)
         return {} unless hash.is_a?(Hash)
 
-        hash.transform_values do |v|
-          case v
-          when String
-            v.length > 100 ? "#{v[0..97]}... (#{v.length} chars)" : v
-          when Array
-            v.length > 5 ? "#{v.first(3).inspect}... (#{v.length} items)" : v.inspect
-          else
-            v.inspect
-          end
+        # OPTIMIZE: only create new hash if values need summarization
+        needs_summarization = false
+        result = {}
+
+        hash.each do |key, v|
+          summarized_value = case v
+                             when String
+                               if v.length > 100
+                                 needs_summarization = true
+                                 "#{v[0, 97]}... (#{v.length} chars)"
+                               else
+                                 v
+                               end
+                             when Array
+                               if v.length > 5
+                                 needs_summarization = true
+                                 "#{v.first(3).inspect}... (#{v.length} items)"
+                               else
+                                 v.inspect
+                               end
+                             else
+                               v.inspect
+                             end
+          result[key] = summarized_value
         end
+
+        # Return original if no summarization was needed (rare optimization)
+        needs_summarization ? result : hash
       end
 
       # Build prompt for neural task execution
@@ -362,6 +445,63 @@ module LanguageOperator
         prompt
       end
 
+      # Build retry prompt when JSON parsing fails
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param inputs [Hash] Validated input parameters
+      # @param failed_response [String] The previous response that failed to parse
+      # @param error_message [String] The parsing error message
+      # @return [String] Prompt for LLM retry
+      def build_parsing_retry_prompt(task, inputs, failed_response, error_message)
+        prompt = "# Task: #{task.name} (RETRY - JSON Parsing Failed)\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 += "## Previous Response (Failed to Parse)\n"
+        prompt += "Your previous response caused a parsing error: #{error_message}\n"
+        prompt += "Previous response preview:\n```\n#{failed_response[0..500]}#{'...' if failed_response.length > 500}\n```\n\n"
+
+        prompt += "## Output Schema (CRITICAL)\n"
+        prompt += "You MUST return valid JSON with exactly these fields:\n"
+        task.outputs_schema.each do |key, type|
+          prompt += "- #{key} (#{type})\n"
+        end
+        prompt += "\n"
+
+        prompt += "## Response Format (CRITICAL)\n"
+        prompt += "IMPORTANT: Your response must be ONLY valid JSON. No other text.\n"
+        prompt += "Do NOT use [THINK] tags or any other text.\n"
+        prompt += "Do NOT include code blocks like ```json.\n"
+        prompt += "Return ONLY the JSON object, nothing else.\n"
+        prompt += "The JSON must match the output schema exactly.\n\n"
+
+        prompt += "Example correct format:\n"
+        prompt += "{\n"
+        task.outputs_schema.each_with_index do |(key, type), index|
+          value_example = case type
+                          when 'string' then '"example"'
+                          when 'integer' then '42'
+                          when 'number' then '3.14'
+                          when 'boolean' then 'true'
+                          when 'array' then '[]'
+                          when 'hash' then '{}'
+                          else '"value"'
+                          end
+          comma = index < task.outputs_schema.length - 1 ? ',' : ''
+          prompt += "  \"#{key}\": #{value_example}#{comma}\n"
+        end
+        prompt += "}\n"
+
+        prompt
+      end
+
       # Parse LLM response to extract output values
       #
       # @param response_text [String] LLM response
@@ -380,8 +520,32 @@ module LanguageOperator
                       thinking_preview: thinking_blocks.first&.[](0..500))
         end
 
-        # Strip thinking tags that some models add (e.g., [THINK]...[/THINK])
-        cleaned_text = response_text.gsub(%r{\[THINK\].*?\[/THINK\]}m, '').strip
+        # Strip thinking tags that some models add (e.g., [THINK]...[/THINK] or unclosed [THINK]...)
+        # First try to strip matched pairs, then strip unclosed [THINK] only if there's JSON after it
+        logger.debug('Parsing neural response', task: task.name, response_length: response_text.length, response_start: response_text[0..100])
+
+        cleaned_text = response_text.gsub(%r{\[THINK\].*?\[/THINK\]}m, '')
+                                    .gsub(/\[THINK\].*?(?=\{)/m, '')
+                                    .strip
+
+        # If cleaned text is empty or still contains unclosed [THINK], try more aggressive cleaning
+        if cleaned_text.empty? || cleaned_text.start_with?('[THINK]')
+          # Strip everything from [THINK] to end if no [/THINK] found
+          cleaned_text = response_text.gsub(/\[THINK\].*$/m, '').strip
+
+          # If still no JSON found, extract everything after the last [THINK] block
+          if cleaned_text.empty? && response_text.include?('{')
+            last_think = response_text.rindex('[THINK]')
+            if last_think
+              after_think = response_text[last_think..]
+              # Find first JSON-like structure after [THINK]
+              json_start = after_think.index('{')
+              cleaned_text = after_think[json_start..] if json_start
+            end
+          end
+        end
+
+        logger.debug('After stripping THINK tags', cleaned_length: cleaned_text.length, cleaned_start: cleaned_text[0..100])
 
         # Try to extract JSON from response
         # Look for JSON code blocks first
@@ -389,11 +553,21 @@ module LanguageOperator
         json_text = if json_match
                       json_match[1]
                     else
-                      # Try to find raw JSON object
+                      # Try to find raw JSON object - be more aggressive about finding JSON
                       json_object_match = cleaned_text.match(/\{.*\}/m)
-                      json_object_match ? json_object_match[0] : cleaned_text
+                      if json_object_match
+                        json_object_match[0]
+                      elsif cleaned_text.include?('{')
+                        # Extract from first { to end of string (handles incomplete responses)
+                        json_start = cleaned_text.index('{')
+                        cleaned_text[json_start..]
+                      else
+                        cleaned_text
+                      end
                     end
 
+        logger.debug('Extracted JSON text', json_length: json_text.length, json_start: json_text[0..100])
+
         # Parse JSON
         parsed = JSON.parse(json_text)
 
@@ -407,13 +581,23 @@ module LanguageOperator
         raise "Neural task '#{task.name}' returned invalid JSON: #{e.message}"
       end
 
-      # Recursively convert all hash keys to symbols
+      # Recursively convert all hash keys to symbols (optimized for performance)
       def deep_symbolize_keys(obj)
         case obj
         when Hash
-          obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize_keys(v) }
+          # OPTIMIZE: pre-allocate hash with correct size and avoid double iteration
+          result = {}
+          obj.each do |key, value|
+            result[key.to_sym] = deep_symbolize_keys(value)
+          end
+          result
         when Array
-          obj.map { |item| deep_symbolize_keys(item) }
+          # OPTIMIZE: pre-allocate array with correct size
+          result = Array.new(obj.size)
+          obj.each_with_index do |item, index|
+            result[index] = deep_symbolize_keys(item)
+          end
+          result
         else
           obj
         end
@@ -520,7 +704,11 @@ module LanguageOperator
         raise create_appropriate_error(task_name, last_error)
       end
 
-      # Execute a single attempt of a task with timeout
+      # Execute a single attempt of a task with timeout and error context preservation
+      #
+      # This method implements timeout handling that preserves original error context
+      # while maintaining error precedence hierarchy. Timeout errors always take
+      # precedence over any nested errors (including network errors).
       #
       # @param task [TaskDefinition] The task definition
       # @param task_name [Symbol] Name of the task
@@ -533,29 +721,63 @@ module LanguageOperator
         attempt_start = Time.now
 
         result = if timeout.positive?
-                   Timeout.timeout(timeout) do
-                     execute_task_implementation(task, inputs)
-                   end
+                   execute_with_timeout(task, task_name, inputs, timeout)
                  else
                    execute_task_implementation(task, inputs)
                  end
 
         execution_time = Time.now - attempt_start
-        logger.info('Task completed',
-                    task: task_name,
-                    attempt: attempt + 1,
-                    execution_time: execution_time.round(3),
-                    outputs: summarize_values(result))
+
+        # Optimize logging - only log if debug level enabled or log_executions is true
+        if logger.logger.level <= ::Logger::DEBUG || @config[:log_executions]
+          logger.info('Task completed',
+                      task: task_name,
+                      attempt: attempt + 1,
+                      execution_time: execution_time.round(3),
+                      outputs: summarize_values(result))
+        end
 
         result
+      end
+
+      # Execute task with timeout wrapper that preserves error context
+      #
+      # This method ensures that timeout errors always take precedence over
+      # any nested errors (e.g., network errors), solving the race condition
+      # between timeout detection and error classification.
+      #
+      # @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
+      # @return [Hash] Task outputs
+      # @raise [TaskTimeoutError] If execution times out (always takes precedence)
+      def execute_with_timeout(task, task_name, inputs, timeout)
+        attempt_start = Time.now
+
+        Timeout.timeout(timeout) do
+          execute_task_implementation(task, inputs)
+        end
       rescue Timeout::Error => e
+        # Timeout always wins - this solves the race condition
         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)
+                    execution_time: execution_time.round(3),
+                    timeout_precedence: 'timeout error takes precedence over any nested errors')
+
+        # Always wrap as TaskTimeoutError, preserving original timeout context
+        raise TaskTimeoutError.new(task_name, "timed out after #{timeout}s (execution_time: #{execution_time.round(3)}s)", e)
+      rescue *RETRYABLE_ERRORS => e
+        # Network errors that escape timeout handling (very rare)
+        # These occur outside the timeout window, so they're genuine network errors
+        logger.debug('Network error outside timeout window',
+                     task: task_name,
+                     error: e.class.name,
+                     message: e.message)
+        raise TaskNetworkError.new(task_name, "network error: #{e.message}", e)
       end
 
       # Execute the actual task implementation (neural or symbolic)
@@ -595,27 +817,51 @@ module LanguageOperator
       # @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) }
+        case error
+        when TaskNetworkError
+          # Network errors wrapped in TaskNetworkError are retryable
+          true
+        when TaskTimeoutError, TaskValidationError
+          # Timeout and validation errors are never retryable
+          false
+        when TaskExecutionError
+          # Check the original error for retryability
+          error.original_error ? retryable_error?(error.original_error) : false
+        when RuntimeError
+          # JSON parsing errors from neural tasks are retryable
+          error.message.include?('returned invalid JSON')
+        else
+          # Check against the standard retryable error list
+          RETRYABLE_ERRORS.any? { |error_class| error.is_a?(error_class) }
+        end
       end
 
-      # Categorize error for logging and operator integration
+      # Categorize error for logging and operator integration with precedence hierarchy
+      #
+      # Error precedence (highest to lowest):
+      # 1. Timeout errors (always win, even if wrapping network errors)
+      # 2. Validation errors (argument/input validation failures)
+      # 3. Network errors (connection, socket, DNS issues)
+      # 4. Execution errors (general task execution failures)
+      # 5. System errors (unexpected/unknown errors)
       #
       # @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
+        # Precedence Level 1: Timeout errors always win
+        return :timeout if error.is_a?(Timeout::Error) || error.is_a?(TaskTimeoutError)
+
+        # Precedence Level 2: Validation errors
+        return :validation if error.is_a?(ArgumentError) || error.is_a?(TaskValidationError)
+
+        # For wrapped errors, check original error but preserve timeout precedence
+        return categorize_error(error.original_error) if error.is_a?(TaskExecutionError) && error.original_error
+
+        # Precedence Level 3: Network errors
+        return :network if error.is_a?(TaskNetworkError) || RETRYABLE_ERRORS.any? { |err_class| error.is_a?(err_class) }
+
+        # Precedence Level 4: General execution errors
+        :execution
       end
 
       # Calculate retry delay with exponential backoff
@@ -627,19 +873,24 @@ module LanguageOperator
         [delay, @config[:retry_delay_max]].min
       end
 
-      # Create appropriate error type based on original error
+      # Create appropriate error type based on original error with precedence hierarchy
       #
       # @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
+        when TaskTimeoutError, TaskValidationError, TaskNetworkError
+          # Already wrapped in appropriate type
           original_error
         when Timeout::Error
-          TaskTimeoutError.new(task_name, 'timed out', original_error)
+          # Always wrap timeout errors, preserving original context
+          TaskTimeoutError.new(task_name, "timed out after timeout (original: #{original_error.message})", original_error)
         when ArgumentError
           TaskValidationError.new(task_name, original_error.message, original_error)
+        when *RETRYABLE_ERRORS
+          # Wrap network errors for clear categorization
+          TaskNetworkError.new(task_name, "network error: #{original_error.message}", original_error)
         else
           TaskExecutionError.new(task_name, original_error.message, original_error)
         end
@@ -665,6 +916,56 @@ module LanguageOperator
                      retryable: retryable_error?(error),
                      backtrace: error.backtrace&.first(5))
       end
+
+      # Build task lookup cache for O(1) task resolution
+      #
+      # Pre-computes task metadata to avoid repeated type determinations
+      # and provide fast hash-based lookup instead of linear search.
+      #
+      # @return [Hash] Cache mapping task names to metadata
+      def build_task_cache
+        cache = {}
+        @tasks.each do |name, task|
+          # Guard against test doubles that don't respond to task methods
+          cache[name] = if task.respond_to?(:neural?) && task.respond_to?(:symbolic?)
+                          {
+                            definition: task,
+                            type: determine_task_type(task),
+                            neural: task.neural?,
+                            symbolic: task.symbolic?
+                          }
+                        else
+                          # Fallback for test doubles or invalid task objects
+                          {
+                            definition: task,
+                            type: 'unknown',
+                            neural: false,
+                            symbolic: false
+                          }
+                        end
+        end
+        cache
+      end
+
+      # Build timeout cache for O(1) timeout resolution
+      #
+      # Pre-computes timeouts for all tasks to avoid repeated calculations
+      # during task execution hot path.
+      #
+      # @return [Hash] Cache mapping task names to timeout values
+      def build_timeout_cache
+        cache = {}
+        @tasks.each do |name, task|
+          # Guard against test doubles that don't respond to task methods
+          cache[name] = if task.respond_to?(:neural?) && task.respond_to?(:symbolic?)
+                          task_timeout_for_type(task)
+                        else
+                          # Fallback timeout for test doubles or invalid task objects
+                          @config[:timeout_symbolic]
+                        end
+        end
+        cache
+      end
     end
   end
 end