legate 0.1.0

data/lib/legate/agentic/decision.rb

@@ -0,0 +1,49 @@
+# File: lib/legate/agentic/decision.rb
+# frozen_string_literal: true
+
+module Legate
+  # The agentic (observe -> think -> act) execution strategy.
+  module Agentic
+    # One step of an agentic loop: the model either calls a tool or gives a
+    # final answer. Immutable.
+    #
+    # @!attribute action [Symbol] :tool or :final
+    # @!attribute thought [String, nil] the model's reasoning
+    # @!attribute tool [Symbol, nil] the tool to call (when action == :tool)
+    # @!attribute params [Hash] tool arguments (when action == :tool)
+    # @!attribute answer [String, nil] the final answer (when action == :final)
+    Decision = Data.define(:action, :thought, :tool, :params, :answer) do
+      def self.tool(tool:, params:, thought: nil)
+        new(action: :tool, thought: thought, tool: tool.to_sym, params: params || {}, answer: nil)
+      end
+
+      def self.final(answer:, thought: nil)
+        new(action: :final, thought: thought, tool: nil, params: {}, answer: answer)
+      end
+
+      # An unusable decision (the model returned neither a valid tool call nor a
+      # final answer).
+      def self.invalid(thought: nil)
+        new(action: :invalid, thought: thought, tool: nil, params: {}, answer: nil)
+      end
+
+      def final?
+        action == :final
+      end
+
+      def tool?
+        action == :tool && !tool.nil? && !tool.to_s.empty?
+      end
+
+      def invalid?
+        !final? && !tool?
+      end
+
+      # The plan step hash that PlanExecutor#execute_step expects.
+      # @return [Hash]
+      def to_step
+        { tool: tool, params: params }
+      end
+    end
+  end
+end

data/lib/legate/agentic/loop.rb

@@ -0,0 +1,134 @@
+# File: lib/legate/agentic/loop.rb
+# frozen_string_literal: true
+
+require_relative 'decision'
+
+module Legate
+  module Agentic
+    # Drives the observe -> think -> act loop: ask the planner for the next
+    # single action, run it via the executor, feed the result back as an
+    # observation, and repeat until the model gives a final answer or the
+    # iteration cap is hit.
+    #
+    # Returns the same { details:, last_result: } shape as
+    # PlanExecutor#execute_plan, so Agent#run_task builds the final event
+    # identically for both execution strategies.
+    class Loop
+      DEFAULT_MAX_ITERATIONS = 8
+      # Long string tool results are truncated to this many characters before
+      # being fed back, so one big output doesn't dominate the prompt each turn.
+      MAX_OBSERVATION_CHARS = 2_000
+
+      # @param planner [#reason_next_action] returns a Decision for the next step
+      # @param executor [#execute_step] runs one tool step (e.g. a PlanExecutor)
+      # @param logger [Logger, nil]
+      # @param max_iterations [Integer]
+      def initialize(planner:, executor:, logger: nil, max_iterations: DEFAULT_MAX_ITERATIONS)
+        @planner = planner
+        @executor = executor
+        @logger = logger || Legate.logger
+        @max_iterations = max_iterations
+      end
+
+      # @return [Hash] { details: <observations>, last_result: <result hash> }
+      def run(user_input:, session:, session_service:, invocation_id: nil)
+        observations = []
+
+        @max_iterations.times do |i|
+          decision = @planner.reason_next_action(user_input, observations, invocation_id)
+
+          return success(decision.answer, observations) if decision.final?
+
+          if decision.invalid?
+            @logger.warn("Agentic loop: model returned an unusable decision at step #{i + 1}; stopping.")
+            return error('The agent could not decide on a valid next action.', observations)
+          end
+
+          result = execute(decision, session, session_service, invocation_id)
+          observation = { tool: decision.tool, params: decision.params, result: sanitize(result) }
+          spinning = observation == observations.last
+          observations << observation
+
+          # Loop-breaker: the model just repeated the exact same action and got
+          # the exact same result — re-running won't make progress, so stop and
+          # summarize rather than burn the rest of the iteration budget.
+          next unless spinning
+
+          @logger.warn("Agentic loop: repeated action '#{decision.tool}' with no change; stopping to avoid spinning.")
+          return finish_without_final(user_input, observations, invocation_id,
+                                      fallback: "Stopped after repeating the same action ('#{decision.tool}') without progress.")
+        end
+
+        @logger.warn("Agentic loop: reached the #{@max_iterations}-iteration cap without a final answer.")
+        finish_without_final(user_input, observations, invocation_id,
+                             fallback: "Stopped after #{@max_iterations} steps without a final answer.")
+      end
+
+      private
+
+      # The loop stopped without the model giving a final answer. Try one
+      # best-effort summary of the observations; fall back to an error result if
+      # the planner can't summarize (no adapter, failure, or empty answer).
+      def finish_without_final(user_input, observations, invocation_id, fallback:)
+        summary = summarize(user_input, observations, invocation_id)
+        return success(summary, observations) if summary
+
+        error(fallback, observations)
+      end
+
+      def summarize(user_input, observations, invocation_id)
+        return nil unless @planner.respond_to?(:summarize_final)
+
+        answer = @planner.summarize_final(user_input, observations, invocation_id)
+        answer if answer.is_a?(String) && !answer.empty?
+      rescue StandardError => e
+        @logger.error("Agentic loop: summary failed: #{e.class}: #{e.message}")
+        nil
+      end
+
+      def execute(decision, session, session_service, invocation_id)
+        @executor.execute_step(decision.to_step, session, session_service, invocation_id)
+      rescue StandardError => e
+        # A hard tool failure becomes an observation the model can react to on
+        # the next turn — it does not abort the loop.
+        @logger.error("Agentic loop: tool '#{decision.tool}' raised: #{e.class}: #{e.message}")
+        { status: :error, error_message: "Tool '#{decision.tool}' raised: #{e.message}" }
+      end
+
+      def success(answer, observations)
+        { details: observations, last_result: { status: :success, result: answer } }
+      end
+
+      def error(message, observations)
+        { details: observations, last_result: { status: :error, error_message: message } }
+      end
+
+      # Keep large tool outputs from blowing the context fed back to the model
+      # (mirrors PlanExecutor#execute_plan's per-step sanitization).
+      def sanitize(result)
+        return result unless result.is_a?(Hash)
+
+        out = { status: result[:status] }
+        out[:error_message] = result[:error_message] if result.key?(:error_message)
+        out[:job_id] = result[:job_id] if result.key?(:job_id)
+        out[:message] = result[:message] if result.key?(:message)
+
+        val = result[:result]
+        if val.is_a?(String)
+          out[:result] = truncate(val)
+        elsif val.is_a?(Numeric) || [true, false, nil].include?(val)
+          out[:result] = val
+        elsif result.key?(:result)
+          out[:result] = '[Complex Result Structure]'
+        end
+        out
+      end
+
+      def truncate(str)
+        return str if str.length <= MAX_OBSERVATION_CHARS
+
+        "#{str[0, MAX_OBSERVATION_CHARS]}… [truncated #{str.length - MAX_OBSERVATION_CHARS} chars]"
+      end
+    end
+  end
+end

data/lib/legate/agentic.rb

@@ -0,0 +1,5 @@
+# File: lib/legate/agentic.rb
+# frozen_string_literal: true
+
+require_relative 'agentic/decision'
+require_relative 'agentic/loop'

data/lib/legate/agents/loop_agent.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+# File: lib/legate/agents/loop_agent.rb
+require_relative '../agent'
+
+module Legate
+  module Agents
+    # LoopAgent executes a set of sub-agents repeatedly until a condition is met or
+    # maximum iterations are reached.
+    class LoopAgent < Legate::Agent
+      DEFAULT_MAX_ITERATIONS = 100
+      DEFAULT_TIMEOUT_SECONDS = 3600 # 1 hour
+      MAX_STORED_ITERATIONS = 50
+      # Override run_task to execute sub-agents in a loop
+      # @param session_id [String] The session ID
+      # @param user_input [String] User input to process
+      # @param session_service [Legate::SessionService::Base] Session service for persistence
+      # @return [Legate::Event] The final agent event
+      def run_task(session_id:, user_input:, session_service:)
+        # Verify we have loop sub-agents defined
+        unless @definition.loop_sub_agent_names&.any?
+          err_msg = "LoopAgent '#{name}' has no loop_sub_agent_names defined."
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: {
+                                     status: :error,
+                                     error_message: err_msg,
+                                     error_class: 'ConfigurationError'
+                                   })
+        end
+
+        # Verify we have either loop_max_iterations or a condition
+        unless @definition.loop_max_iterations || (@definition.loop_condition_state_key && !@definition.loop_condition_expected_value.nil?)
+          err_msg = "LoopAgent '#{name}' must define either loop_max_iterations or loop_condition (state key + expected value)."
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: {
+                                     status: :error,
+                                     error_message: err_msg,
+                                     error_class: 'ConfigurationError'
+                                   })
+        end
+
+        # --- Pre-execution Checks --- #
+        unless running?
+          err_msg = "Agent '#{name}' is not running. Call agent.start before run_task, " \
+                    'or use agent.ask (which starts automatically).'
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: { status: :error, error_message: err_msg })
+        end
+
+        session = session_service.get_session(session_id: session_id)
+        unless session
+          err_msg = "Session not found: #{session_id}"
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: { status: :error, error_message: err_msg })
+        end
+        # --------------------------- #
+
+        # Log user input to the LoopAgent itself
+        user_event = Legate::Event.new(role: :user, content: user_input)
+        session_service.append_event(session_id: session_id, event: user_event)
+
+        # Determine loop parameters
+        max_iterations = @definition.loop_max_iterations || DEFAULT_MAX_ITERATIONS
+        timeout_seconds = @definition.respond_to?(:loop_timeout_seconds) && @definition.loop_timeout_seconds || DEFAULT_TIMEOUT_SECONDS
+        condition_key = @definition.loop_condition_state_key
+        expected_value = @definition.loop_condition_expected_value
+
+        Legate.logger.info("LoopAgent '#{name}' starting execution with max #{max_iterations} iterations, #{timeout_seconds}s timeout" +
+                        (condition_key ? " or until #{condition_key} equals #{expected_value.inspect}" : ''))
+
+        # Track loop iterations and results
+        iteration = 0
+        all_iterations = []
+        final_result = nil
+        loop_condition_met = false
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Execute the loop
+        while iteration < max_iterations
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          if elapsed >= timeout_seconds
+            Legate.logger.warn("LoopAgent '#{name}' timed out after #{elapsed.round(1)}s (limit: #{timeout_seconds}s)")
+            final_result = {
+              status: :error,
+              error_message: "Loop timed out after #{elapsed.round(1)} seconds (#{iteration} iterations completed)",
+              error_class: 'TimeoutError',
+              iterations_completed: iteration,
+              max_iterations: max_iterations,
+              loop_condition_met: false,
+              iterations: all_iterations
+            }
+            break
+          end
+          iteration += 1
+          Legate.logger.info("LoopAgent '#{name}' starting iteration #{iteration}/#{max_iterations == Float::INFINITY ? '∞' : max_iterations}")
+
+          # Check condition (if defined) before executing the iteration
+          if condition_key && session_service.respond_to?(:get_state)
+            current_value = session_service.get_state(session_id: session_id, key: condition_key)
+            if current_value == expected_value
+              Legate.logger.info("LoopAgent '#{name}' condition met: #{condition_key} = #{expected_value.inspect}. Exiting loop.")
+              loop_condition_met = true
+              break
+            end
+          end
+
+          # Execute one iteration (all sub-agents in sequence)
+          iteration_results = []
+          iteration_error = nil
+
+          # Execute each sub-agent in order (sequential execution within each iteration)
+          @definition.loop_sub_agent_names.each_with_index do |sub_agent_name, index|
+            sub_agent = find_sub_agent(sub_agent_name)
+            unless sub_agent
+              err_msg = "Sub-agent '#{sub_agent_name}' not found for LoopAgent '#{name}'."
+              Legate.logger.error(err_msg)
+              iteration_error = {
+                status: :error,
+                error_message: err_msg,
+                error_class: 'MissingSubAgentError',
+                step: index + 1,
+                total_steps: @definition.loop_sub_agent_names.size,
+                previous_results: iteration_results.map.with_index { |r, i| { agent: @definition.loop_sub_agent_names.to_a[i], result: r } }
+              }
+              break # Stop this iteration's execution
+            end
+
+            # Start the sub-agent if it's not already running
+            sub_agent.start unless sub_agent.running?
+
+            # Execute the sub-agent with the same session and input
+            begin
+              Legate.logger.info("LoopAgent '#{name}' executing sub-agent '#{sub_agent_name}' (iteration #{iteration}, step #{index + 1}/#{@definition.loop_sub_agent_names.size}).")
+              sub_result = sub_agent.run_task(
+                session_id: session_id,
+                user_input: user_input,
+                session_service: session_service
+              )
+
+              # Record the result
+              iteration_results << { agent: sub_agent_name, result: sub_result.content }
+
+              # Check for error to break sequence
+              if sub_result.content[:status] == :error
+                Legate.logger.warn("Sub-agent '#{sub_agent_name}' returned error, breaking iteration: #{sub_result.content[:error_message]}")
+                iteration_error = {
+                  status: :error,
+                  error_message: "Error in sub-agent '#{sub_agent_name}': #{sub_result.content[:error_message]}",
+                  error_class: sub_result.content[:error_class] || 'SubAgentError',
+                  step: index + 1,
+                  total_steps: @definition.loop_sub_agent_names.size,
+                  sub_agent: sub_agent_name.to_s,
+                  sub_result: sub_result.content
+                }
+                break # Stop this iteration's execution on error
+              end
+            rescue StandardError => e
+              Legate.logger.error("Error executing sub-agent '#{sub_agent_name}': #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}")
+              iteration_error = {
+                status: :error,
+                error_message: "Exception in sub-agent '#{sub_agent_name}': #{e.message}",
+                error_class: e.class.name,
+                step: index + 1,
+                total_steps: @definition.loop_sub_agent_names.size,
+                sub_agent: sub_agent_name.to_s
+              }
+              break # Stop this iteration's execution on error
+            end
+          end
+
+          # Record this iteration's results, capping stored history
+          all_iterations << {
+            iteration: iteration,
+            results: iteration_results,
+            error: iteration_error
+          }
+          all_iterations.shift if all_iterations.size > MAX_STORED_ITERATIONS
+
+          # If there was an error in this iteration, we may need to break the loop
+          if iteration_error
+            # An error occurred during execution - decide whether to break the loop
+            Legate.logger.warn("LoopAgent '#{name}' iteration #{iteration} encountered an error. Exiting loop.")
+            final_result = {
+              status: :error,
+              error_message: "Loop terminated due to error in iteration #{iteration}: #{iteration_error[:error_message]}",
+              error_class: iteration_error[:error_class],
+              iterations_completed: iteration,
+              max_iterations: max_iterations,
+              loop_condition_met: false,
+              iterations: all_iterations
+            }
+            break # Exit the loop on error
+          end
+
+          # Check condition (if defined) after executing the iteration
+          next unless condition_key && session_service.respond_to?(:get_state)
+
+          current_value = session_service.get_state(session_id: session_id, key: condition_key)
+          next unless current_value == expected_value
+
+          Legate.logger.info("LoopAgent '#{name}' condition met: #{condition_key} = #{expected_value.inspect}. Exiting loop.")
+          loop_condition_met = true
+          break
+        end
+
+        # If we didn't set a final_result due to an error, create a success result
+        if final_result.nil?
+          completion_reason = if loop_condition_met
+                                "condition met (#{condition_key} = #{expected_value.inspect})"
+                              elsif iteration >= max_iterations
+                                "maximum iterations (#{max_iterations}) reached"
+                              else
+                                'unknown reason'
+                              end
+
+          final_result = {
+            status: :success,
+            result: "Completed #{iteration} iteration(s) of #{@definition.loop_sub_agent_names.size} sub-agent(s) - #{completion_reason}",
+            iterations_completed: iteration,
+            max_iterations: max_iterations,
+            loop_condition_met: loop_condition_met,
+            iterations: all_iterations
+          }
+        end
+
+        # Create the final event
+        final_agent_event = Legate::Event.new(role: :agent, content: final_result)
+
+        # Log the final event to the session
+        session_service.append_event(session_id: session_id, event: final_agent_event)
+
+        # --- MAS: Store result in session state if output_key is defined --- #
+        if @definition.respond_to?(:output_key) && @definition.output_key && final_agent_event
+          output_value = final_agent_event.content # Store the entire content hash
+          Legate.logger.info("LoopAgent '#{@name}' storing output to session state with key '#{@definition.output_key}' for session '#{session_id}'.")
+          if session_service.respond_to?(:set_state)
+            session_service.set_state(session_id: session_id, key: @definition.output_key, value: output_value)
+          else
+            Legate.logger.warn("LoopAgent '#{@name}': Session service does not support :set_state. Cannot store output for key '#{@definition.output_key}'.")
+          end
+        end
+        # --- End MAS State Management --- #
+
+        final_agent_event
+      end
+    end
+  end
+end

data/lib/legate/agents/parallel_agent.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# File: lib/legate/agents/parallel_agent.rb
+require_relative '../agent'
+require 'concurrent'
+
+module Legate
+  module Agents
+    # ParallelAgent executes a set of sub-agents concurrently.
+    # All sub-agents are started simultaneously and the agent waits for all to complete.
+    class ParallelAgent < Legate::Agent
+      DEFAULT_PARALLEL_TIMEOUT = 120
+
+      # Override run_task to execute sub-agents in parallel
+      # @param session_id [String] The session ID
+      # @param user_input [String] User input to process
+      # @param session_service [Legate::SessionService::Base] Session service for persistence
+      # @return [Legate::Event] The final agent event
+      def run_task(session_id:, user_input:, session_service:)
+        # Verify we have parallel sub-agents defined
+        unless @definition.parallel_sub_agent_names&.any?
+          err_msg = "ParallelAgent '#{name}' has no parallel_sub_agent_names defined."
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: {
+                                     status: :error,
+                                     error_message: err_msg,
+                                     error_class: 'ConfigurationError'
+                                   })
+        end
+
+        # --- Pre-execution Checks --- #
+        unless running?
+          err_msg = "Agent '#{name}' is not running. Call agent.start before run_task, " \
+                    'or use agent.ask (which starts automatically).'
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: { status: :error, error_message: err_msg })
+        end
+
+        session = session_service.get_session(session_id: session_id)
+        unless session
+          err_msg = "Session not found: #{session_id}"
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: { status: :error, error_message: err_msg })
+        end
+        # --------------------------- #
+
+        # Log user input to the ParallelAgent itself
+        user_event = Legate::Event.new(role: :user, content: user_input)
+        session_service.append_event(session_id: session_id, event: user_event)
+
+        # Log the execution start
+        Legate.logger.info("ParallelAgent '#{name}' starting parallel execution of #{@definition.parallel_sub_agent_names.size} sub-agents.")
+
+        # Get the sub-agents to run in parallel
+        sub_agents_to_run = []
+        missing_agents = []
+
+        @definition.parallel_sub_agent_names.each do |sub_agent_name|
+          sub_agent = find_sub_agent(sub_agent_name)
+          if sub_agent
+            # Start the sub-agent if it's not already running
+            sub_agent.start unless sub_agent.running?
+            sub_agents_to_run << { name: sub_agent_name, agent: sub_agent }
+          else
+            missing_agents << sub_agent_name
+          end
+        end
+
+        # Check if any agents are missing
+        unless missing_agents.empty?
+          err_msg = "The following sub-agents were not found for ParallelAgent '#{name}': #{missing_agents.join(', ')}."
+          Legate.logger.error(err_msg)
+          return Legate::Event.new(role: :agent, content: {
+                                     status: :error,
+                                     error_message: err_msg,
+                                     error_class: 'MissingSubAgentError'
+                                   })
+        end
+
+        # Prepare futures for parallel execution
+        futures = {}
+        sub_agents_to_run.each do |agent_info|
+          futures[agent_info[:name]] = Concurrent::Promises.future do
+            Legate.logger.info("ParallelAgent '#{name}' executing sub-agent '#{agent_info[:name]}' in parallel.")
+            agent_info[:agent].run_task(
+              session_id: session_id,
+              user_input: user_input,
+              session_service: session_service
+            )
+          rescue StandardError => e
+            Legate.logger.error("Error executing sub-agent '#{agent_info[:name]}': #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}")
+            # Return an error event
+            Legate::Event.new(role: :agent, content: {
+                                status: :error,
+                                error_message: "Exception in sub-agent '#{agent_info[:name]}': #{e.message}",
+                                error_class: e.class.name
+                              })
+          end
+        end
+
+        # Wait for all futures to complete
+        all_results = {}
+        has_errors = false
+        timeout = @definition.respond_to?(:parallel_timeout_seconds) && @definition.parallel_timeout_seconds || DEFAULT_PARALLEL_TIMEOUT
+
+        futures.each do |agent_name, future|
+          result = future.value(timeout)
+          all_results[agent_name] = result.content
+          has_errors = true if result.content[:status] == :error
+        rescue Concurrent::TimeoutError
+          Legate.logger.error("Timeout waiting for sub-agent '#{agent_name}' to complete.")
+          all_results[agent_name] = {
+            status: :error,
+            error_message: 'Timeout waiting for sub-agent to complete',
+            error_class: 'TimeoutError'
+          }
+          has_errors = true
+        rescue StandardError => e
+          Legate.logger.error("Error processing sub-agent '#{agent_name}' result: #{e.class} - #{e.message}")
+          all_results[agent_name] = {
+            status: :error,
+            error_message: "Error processing result: #{e.message}",
+            error_class: e.class.name
+          }
+          has_errors = true
+        end
+
+        # Create the final result
+        final_result = {
+          status: has_errors ? :partial_success : :success,
+          result: if has_errors
+                    'Completed parallel execution with some errors'
+                  else
+                    "Successfully completed parallel execution of #{@definition.parallel_sub_agent_names.size} sub-agents"
+                  end,
+          sub_results: all_results,
+          agents_completed: all_results.keys.map(&:to_sym),
+          all_successful: !has_errors
+        }
+
+        # Create the final event
+        final_agent_event = Legate::Event.new(role: :agent, content: final_result)
+
+        # Log the final event to the session
+        session_service.append_event(session_id: session_id, event: final_agent_event)
+
+        # --- MAS: Store result in session state if output_key is defined --- #
+        if @definition.respond_to?(:output_key) && @definition.output_key && final_agent_event
+          output_value = final_agent_event.content # Store the entire content hash
+          Legate.logger.info("ParallelAgent '#{@name}' storing output to session state with key '#{@definition.output_key}' for session '#{session_id}'.")
+          if session_service.respond_to?(:set_state)
+            session_service.set_state(session_id: session_id, key: @definition.output_key, value: output_value)
+          else
+            Legate.logger.warn("ParallelAgent '#{@name}': Session service does not support :set_state. Cannot store output for key '#{@definition.output_key}'.")
+          end
+        end
+        # --- End MAS State Management --- #
+
+        final_agent_event
+      end
+    end
+  end
+end