ralph.rb 1.2.4355354345 → 2.1.0

data/lib/ralph/iteration.rb

@@ -1,219 +1,99 @@
 # frozen_string_literal: true
 
 module Ralph
+  # Represents a single execution cycle within the loop. Runs the agent with
+  # the prompt, monitors events, detects signals, and can be cancelled at
+  # any time. Tracks the outcome of the iteration (task-done, all-done,
+  # context guard, error, etc.).
   class Iteration
-    # Statuses:
-    #   :completed  — completion promise detected, iteration succeeded
-    #   :continuing — no completion detected, keep looping
-    #   :failed     — non-zero exit code from the agent process
-    #   :fatal      — fatal error detected in agent output (unrecoverable)
-    #   :error      — iteration raised an exception
-    class Result
-      STATUSES = %i[completed continuing failed fatal error].freeze
-
-      attr_reader :status, :agent_result, :duration_ms, :files_modified, :completion_detected, :errors
-
-      def initialize(status:, agent_result:, duration_ms:, files_modified:, completion_detected:, errors:)
-        @status = status
-        @agent_result = agent_result
-        @duration_ms = duration_ms
-        @files_modified = files_modified
-        @completion_detected = completion_detected
-        @errors = errors
-      end
-
-      def exit_code       = agent_result&.exit_code
-      def stdout_text     = agent_result&.stdout_text || ""
-      def stderr_text     = agent_result&.stderr_text || ""
-      def tool_counts     = agent_result&.tool_counts || {}
-      def combined_output = agent_result&.combined_output || ""
-
-      def completed?  = status == :completed
-      def continuing? = status == :continuing
-      def failed?     = status == :failed
-      def fatal?      = status == :fatal
-      def error?      = status == :error
-    end
-
-    include ::Ralph::Helpers
-
-    attr_reader :struggle_indicators, :iteration_start
-
-    def initialize(loop_context)
-      @loop = loop_context
-      @config = @loop.config
-      @agent = @loop.agent
-      @state = @loop.state
-      @struggle_indicators = @loop.struggle_indicators
-
-      # Streaming configuration
-      @compact_tools = !@config.verbose_tools
-      @tool_summary_interval_ms = 3000
-      @heartbeat_interval_ms = 10_000
-
-      @stream_tool_counts = Hash.new(0)
-      @mutex = Mutex.new
-      @timing = { last_printed_at: now_ms, last_activity_at: now_ms }
-      @last_tool_summary_at = 0
-
-      @iteration_start = now_ms
+    OUTCOMES = %i[task_done all_done context_limit duration_limit error].freeze
+
+    attr_reader :number, :outcome
+
+    def initialize(number:, prompt_text:, model:, task_done_string:, all_done_string:, metrics:, display:)
+      @number = number
+      @prompt_text = prompt_text
+      @model = model
+      @task_done_string = task_done_string
+      @all_done_string = all_done_string
+      @metrics = metrics
+      @display = display
+      @outcome = nil
+      @agent = nil
     end
 
-    def context_at_start = @_context_at_start ||= @loop.context
-
-    def run
-      snapshot_before = Git::FileSnapshot.capture
-
-      if @config.stream_output
-        heartbeat = Threads::Heartbeat.new(iteration_start, @heartbeat_interval_ms, @timing, @mutex)
-      end
+    # Run the iteration. Yields control back to the loop via the check block
+    # which determines if the iteration should be cancelled due to external
+    # limits (context, duration). Returns the outcome symbol.
+    def run(max_context: nil, duration_exceeded: nil)
+      @agent = Opencode.new(model: @model)
 
-      @agent.execute(
-        @loop.prompt.build_iteration(@state, @agent),
-        on_line:               method(:handle_line),
-        model:                 @config.model,
-        stream_output:         @config.stream_output,
-        disable_plugins:       @config.disable_plugins,
-        allow_all_permissions: @config.allow_all_permissions,
-      ).then do |agent_result|
-        heartbeat&.stop
+      @agent.run(@prompt_text) do |event|
+        @metrics.process(event)
+        @display.show_event(event)
 
-        if @config.stream_output
-          @mutex.synchronize { maybe_print_tool_summary(force: true) }
+        if event.is_a?(Events::Text)
+          check_signals(event.text)
         end
 
-        unless @config.stream_output
-          if agent_result
-            warn agent_result.stderr_text unless agent_result.stderr_text.empty?
-            puts agent_result.stdout_text
-          end
+        if @outcome
+          @agent.cancel
+          break
         end
 
-        snapshot_after = Git::FileSnapshot.capture
-
-        combined_output = agent_result.combined_output
-        completion_detected = check_completion(combined_output, @config.completion_promise)
-        fatal_error = @agent.detect_fatal_error(combined_output)
-
-        status = (
-          if fatal_error
-            :fatal
-          elsif agent_result.exit_code != 0
-            :failed
-          elsif completion_detected
-            :completed
-          else
-            :continuing
-          end
-        )
+        if max_context && @metrics.current_context >= max_context
+          @outcome = :context_limit
+          @display.show_iteration_cancelled(
+            "context limit reached (#{@metrics.current_context}/#{max_context})"
+          )
+          @agent.cancel
+          break
+        end
 
-        Result.new(
-          status: status,
-          agent_result: agent_result,
-          duration_ms: now_ms - iteration_start,
-          files_modified: snapshot_before.modified_since(snapshot_after),
-          completion_detected: completion_detected,
-          errors: @agent.extract_errors(combined_output)
-        ).tap do |result|
-          update_struggle_indicators(result)
+        if duration_exceeded&.call
+          @outcome = :duration_limit
+          @display.show_iteration_cancelled("duration limit reached")
+          @agent.cancel
+          break
         end
       end
+    rescue Errno::ENOENT => error
+      @outcome = :error
+      @display.show_iteration_error("agent not found: #{error.message}")
+    rescue IOError, Errno::EPIPE => error
+      @outcome = :error
+      @display.show_iteration_error("agent communication error: #{error.message}")
     rescue StandardError => error
-      if @config.current_pid
-        begin
-          Process.kill('TERM', @config.current_pid)
-        rescue StandardError
-          # process may have exited
-        end
-        @config.current_pid = nil
-      end
-
-      Output::Iteration::Error.call(@loop, error)
-
-      sleep 2
-
-      Result.new(
-        status: :error,
-        agent_result: nil,
-        duration_ms: now_ms - (iteration_start || now_ms), # this is so fucking wrong
-        files_modified: [],
-        completion_detected: false,
-        errors: [error.message]
-      )
-    end
-
-    # ---------- Warnings and error detection ----------
-
-    def handle_iteration_error(error, iteration_start)
+      @outcome = :error
+      @display.show_iteration_error("unexpected error: #{error.message}")
+    ensure
+      @outcome ||= :unknown
     end
 
-    # Returns true when the agent appears to be stuck.
-    # Should only be called after iteration > 2 for meaningful results.
-    def struggling?
-      @struggle_indicators[:no_progress_iterations] >= 3 ||
-        @struggle_indicators[:short_iterations] >= 3
+    # Whether this iteration ended because the agent signaled task-done
+    def task_done?
+      @outcome == :task_done
     end
 
-    private
-
-    # ---------- Struggle tracking ----------
-
-    def update_struggle_indicators(result)
-      if result.files_modified.empty?
-        @struggle_indicators[:no_progress_iterations] += 1
-      else
-        @struggle_indicators[:no_progress_iterations] = 0
-      end
-
-      if result.duration_ms < 30_000
-        @struggle_indicators[:short_iterations] += 1
-      else
-        @struggle_indicators[:short_iterations] = 0
-      end
-
-      if result.errors.empty?
-        @struggle_indicators[:repeated_errors] = {}
-      else
-        result.errors.each do |error|
-          key = error[0, 100]
-          @struggle_indicators[:repeated_errors][key] = (@struggle_indicators[:repeated_errors][key] || 0) + 1
-        end
-      end
+    # Whether this iteration ended because the agent signaled all-done
+    def all_done?
+      @outcome == :all_done
     end
 
-    # ---------- Agent execution ----------
-
-    def maybe_print_tool_summary(force: false)
-      if @compact_tools && @stream_tool_counts.any?
-        now = now_ms
-        if force || (now - @last_tool_summary_at >= @tool_summary_interval_ms)
-          format_tool_summary(@stream_tool_counts).then do |summary|
-            unless summary.empty?
-              puts "| Tools    #{summary}"
-              @timing[:last_printed_at] = now_ms
-              @last_tool_summary_at = now_ms
-            end
-          end
-        end
-      end
+    # Whether this iteration ended due to an error
+    def error?
+      @outcome == :error
     end
 
-    def handle_line(line, is_error, tool)
-      @mutex.synchronize { @timing[:last_activity_at] = now_ms }
-
-      @mutex.synchronize { @stream_tool_counts[tool] += 1 } if tool
+    private
 
-      if tool && @compact_tools
-        @mutex.synchronize { maybe_print_tool_summary }
-      else
-        if line.empty?
-          puts ''
-        elsif is_error
-          warn line
-        else
-          puts line
+    def check_signals(text)
+      if text
+        if text.include?(@all_done_string)
+          @outcome = :all_done
+        elsif @task_done_string && text.include?(@task_done_string)
+          @outcome = :task_done
         end
-        @mutex.synchronize { @timing[:last_printed_at] = now_ms }
       end
     end
   end

data/lib/ralph/loop.rb

@@ -1,196 +1,137 @@
-#            _       _                _
-#  _ __ __ _| |_ __ | |__   __      _(_) __ _  __ _ _   _ _ __ ___
-# | '__/ _` | | '_ \| '_ \  \ \ /\ / / |/ _` |/ _` | | | | '_ ` _ \
-# | | | (_| | | |_) | | | |  \ V  V /| | (_| | (_| | |_| | | | | | |
-# |_|  \__,_|_| .__/|_| |_|   \_/\_/ |_|\__, |\__, |\__,_|_| |_| |_|
-#             |_|                       |___/ |___/
-#
 # frozen_string_literal: true
 
 module Ralph
+  # The core iteration engine. Runs opencode in a loop, restarting fresh
+  # iterations whenever context grows too large or time limits are hit.
+  # The loop ends when:
+  #   - the agent emits the all-done completion string
+  #   - max iterations are reached
+  #   - total duration is exceeded
+  #
+  # An iteration ends early (and a fresh one begins) when:
+  #   - the agent emits the task-done string (build mode only)
+  #   - context limit is exceeded
   class Loop
-    include ::Ralph::Helpers
-
-    attr_reader :config, :agent, :state, :history, :context, :tasks, :prompt, :struggle_indicators
-
-    def initialize(config, state, history, context, tasks)
-      @config = config
-      @agent = Agents.resolve(@config.chosen_agent)
-      @state = state
-      @history = history
-      @context = context
-      @tasks = tasks
-
-      @struggle_indicators = {
-        repeated_errors: {},
-        no_progress_iterations: 0,
-        short_iterations: 0
-      }
-
-      @prompt = @config.prompt
-      @existing_state = Storage::State.load
-      @state.save
+    attr_reader :metrics, :iteration_number, :completed, :iteration_outcomes
+
+    def initialize(options)
+      @prompt = options[:prompt]
+      @model = options[:model]
+      @max_iterations = options[:max_iterations]
+      @duration_limit = options[:duration]
+      @max_context = options[:max_context]
+      @all_done_string = resolve_all_done_string(options)
+      @task_done_string = resolve_task_done_string
+      @metrics = Metrics.new
+      @iteration_number = 0
+      @completed = false
+      @iteration_outcomes = []
+      @started_at = nil
+      @display = Display.new(self)
     end
 
-    def existing_state = @existing_state
-
+    # Run the main loop until a termination condition is met.
     def run
-      if existing_state&.active
-        Output::ActiveLoopError.call(existing_state, path: Storage::State.path)
-        exit 1
-      end
-
-      Output::Banner.call(self)
-
-      # |..................................................|
-      # |--------------------------------------------------|
-      # |==================================================|
-      # |**************************************************|
-      # |##################################################|
-      # | Main loop                                        |
-      # |##################################################|
-      # |**************************************************|
-      # |==================================================|
-      # |--------------------------------------------------|
-      # |..................................................|
-      #
-      # © 2026 Nathan K.
-      # Honestly, I've no idea where this graphic
-      # wonder came from. It's MIT lisenced now, thought.
-
-      setup_signal_handler
+      @started_at = now_seconds
+      @display.show_start(prompt_text)
 
       loop do
-        if @config.stopping
-          break
-        elsif max_iterations_reached?
-          Output::MaxIterationsReached.call(self)
-          @state.clear
-          break
-        else
-          Output::Iteration::Header.call(self)
-
-          iteration = Iteration.new(self)
-          result = iteration.run
-          should_continue = process_result(result, iteration)
-
-          if should_continue
-            @state.iteration += 1
-            @state.save
-            sleep 1
-          else
-            break
-          end
+        break if should_stop_loop?
+
+        @iteration_number += 1
+        @metrics.new_iteration
+        @display.show_iteration_start
+
+        iteration = run_iteration
+
+        @iteration_outcomes << { number: iteration.number, outcome: iteration.outcome }
+        @display.show_iteration_end
+
+        if iteration.all_done?
+          @completed = true
         end
       end
-    end
 
-    private
+      @display.show_summary
+      @completed
+    end
 
-      def process_result(result, iteration)
-        unless result.error?
-          Output::Iteration::Summary.call(self, result)
-        end
+    # Total elapsed wall-clock seconds since the loop started
+    def elapsed_seconds
+      if @started_at
+        now_seconds - @started_at
+      else
+        0.0
+      end
+    end
 
-        case result.status
-        when :fatal
-          @history.record(
-            state_iteration: @state.iteration,
-            iteration_start: iteration.iteration_start,
-            result: result,
-            struggle_indicators: iteration.struggle_indicators
-          )
-          Output::PluginError.call
-          @state.clear
-          exit 1
-
-        when :failed
-          @history.record(
-            state_iteration: @state.iteration,
-            iteration_start: iteration.iteration_start,
-            result: result,
-            struggle_indicators: iteration.struggle_indicators
-          )
-          Output::NonzeroExitWarning.call(self, result)
-
-          if @config.tasks_mode
-            if check_completion(result.combined_output, @config.task_promise)
-              Output::TaskCompletion.call(self)
-            end
-          end
-
-        when :completed
-          @history.record(
-            state_iteration: @state.iteration,
-            iteration_start: iteration.iteration_start,
-            result: result,
-            struggle_indicators: iteration.struggle_indicators
-          )
-
-          if @state.iteration >= @config.min_iterations
-            Output::CompletionDetected.call(self)
-            @state.clear
-            Storage::History.clear_history
-            @context.clear
-          end
-
-        when :continuing
-          @history.record(
-            state_iteration: @state.iteration,
-            iteration_start: iteration.iteration_start,
-            result: result,
-            struggle_indicators: iteration.struggle_indicators
-          )
-
-          if @state.iteration > 2 && iteration.struggling?
-            Output::StruggleWarning.call(self)
-          end
-
-          if @config.tasks_mode
-            if check_completion(result.combined_output, @config.task_promise)
-              Output::TaskCompletion.call(self)
-            end
-          end
-
-          if iteration.context_at_start.present?
-            Output::ContextConsumed.call
-            iteration.context_at_start.clear
-          end
-
-        when :error
-          @history.record_error(
-            state_iteration: @state.iteration,
-            iteration_start: iteration.iteration_start,
-            error: result.errors.first || "Unknown error"
-          )
-        end
+    private
 
-        result.status != :completed || @state.iteration < @config.min_iterations
+    # Read all-done string from the prompt object if it responds to it,
+    # falling back to the CLI --completion option or the default.
+    def resolve_all_done_string(options)
+      if options[:completion]
+        options[:completion]
+      elsif @prompt.respond_to?(:all_done) && @prompt.all_done
+        @prompt.all_done
+      else
+        Prompt::Build::DEFAULT_ALL_DONE
       end
+    end
 
-      def max_iterations_reached?
-        @config.max_iterations > 0 && @state.iteration > @config.max_iterations
+    # Read task-done string from the prompt object. Plan prompts return nil,
+    # meaning the loop will not watch for task-done signals.
+    def resolve_task_done_string
+      if @prompt.respond_to?(:task_done)
+        @prompt.task_done
+      else
+        nil
       end
+    end
 
-      def setup_signal_handler
-        Signal.trap('INT') do
-          if @config.stopping
-            warn "\nForce stopping..."
-            exit 1
-          end
-          @config.stopping = true
-          warn "\nGracefully stopping Ralph loop..."
-          if @config.current_pid
-            begin
-              Process.kill('TERM', @config.current_pid)
-            rescue StandardError
-              # process may have exited
-            end
-          end
-          @state.clear
-          warn 'Loop cancelled.'
-          exit 0
-        end
+    def prompt_text
+      @prompt.to_s
+    end
+
+    def should_stop_loop?
+      if @completed
+        true
+      elsif @max_iterations && @iteration_number >= @max_iterations
+        @display.show_termination("max iterations reached (#{@max_iterations})")
+        true
+      elsif duration_exceeded?
+        @display.show_termination("duration limit reached (#{@duration_limit}s)")
+        true
+      else
+        false
       end
+    end
+
+    def run_iteration
+      iteration = Iteration.new(
+        number: @iteration_number,
+        prompt_text: prompt_text,
+        model: @model,
+        task_done_string: @task_done_string,
+        all_done_string: @all_done_string,
+        metrics: @metrics,
+        display: @display
+      )
+
+      iteration.run(
+        max_context: @max_context,
+        duration_exceeded: -> { duration_exceeded? }
+      )
+
+      iteration
+    end
+
+    def duration_exceeded?
+      @duration_limit && elapsed_seconds >= @duration_limit
+    end
+
+    def now_seconds
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
   end
 end

data/lib/ralph/metrics.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ralph
+  # Tracks token usage and context size from opencode JSON stream events.
+  #
+  # Context formula per step: input + cache.read + cache.write
+  # Each step's cache.read ~= previous step's (cache.read + cache.write).
+  class Metrics
+    attr_reader :steps, :iteration_steps, :total_input_tokens, :total_output_tokens
+
+    def initialize
+      @steps = []
+      @iteration_steps = []
+      @total_input_tokens = 0
+      @total_output_tokens = 0
+      @iteration_count = 0
+    end
+
+    # Process a parsed event. Only StepFinish events carry token data.
+    def process(event)
+      if event.is_a?(Events::StepFinish)
+        record = {
+          input: event.input_tokens,
+          output: event.output_tokens,
+          reasoning: event.reasoning_tokens,
+          cache_read: event.cache_read,
+          cache_write: event.cache_write,
+          context: event.context_size,
+          timestamp: event.timestamp
+        }
+        @steps << record
+        @iteration_steps << record
+        @total_input_tokens += event.input_tokens
+        @total_output_tokens += event.output_tokens
+      end
+    end
+
+    # Current context size from the most recent step_finish
+    def current_context
+      if @steps.any?
+        @steps.last[:context]
+      else
+        0
+      end
+    end
+
+    # Total tokens consumed across all steps (input + output)
+    def tokens_consumed
+      @steps.sum { |step| step[:input] + step[:output] + step[:cache_read] + step[:cache_write] }
+    end
+
+    # Tokens consumed in the current iteration only
+    def iteration_tokens
+      @iteration_steps.sum { |step| step[:input] + step[:output] + step[:cache_read] + step[:cache_write] }
+    end
+
+    # Number of LLM steps completed
+    def step_count
+      @steps.length
+    end
+
+    # Signal a new iteration -- resets per-iteration tracking
+    def new_iteration
+      @iteration_count += 1
+      @iteration_steps = []
+    end
+
+    # Context growth rate: average tokens added per step
+    def context_growth_rate
+      if @steps.length >= 2
+        first_context = @steps.first[:context]
+        last_context = @steps.last[:context]
+        (last_context - first_context).to_f / (@steps.length - 1)
+      else
+        0.0
+      end
+    end
+
+    # Reset all metrics (used for full restart)
+    def reset
+      @steps = []
+      @iteration_steps = []
+      @total_input_tokens = 0
+      @total_output_tokens = 0
+      @iteration_count = 0
+    end
+  end
+end