ralph.rb 1.2.435535439

data/lib/ralph/iteration.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Ralph
+  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
+    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
+
+      @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
+
+        if @config.stream_output
+          @mutex.synchronize { maybe_print_tool_summary(force: true) }
+        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
+        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
+        )
+
+        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)
+        end
+      end
+    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)
+    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
+    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
+    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
+    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
+
+      if tool && @compact_tools
+        @mutex.synchronize { maybe_print_tool_summary }
+      else
+        if line.empty?
+          puts ''
+        elsif is_error
+          warn line
+        else
+          puts line
+        end
+        @mutex.synchronize { @timing[:last_printed_at] = now_ms }
+      end
+    end
+  end
+end

data/lib/ralph/loop.rb

@@ -0,0 +1,196 @@
+#            _       _                _
+#  _ __ __ _| |_ __ | |__   __      _(_) __ _  __ _ _   _ _ __ ___
+# | '__/ _` | | '_ \| '_ \  \ \ /\ / / |/ _` |/ _` | | | | '_ ` _ \
+# | | | (_| | | |_) | | | |  \ V  V /| | (_| | (_| | |_| | | | | | |
+# |_|  \__,_|_| .__/|_| |_|   \_/\_/ |_|\__, |\__, |\__,_|_| |_| |_|
+#             |_|                       |___/ |___/
+#
+# frozen_string_literal: true
+
+module Ralph
+  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
+    end
+
+    def existing_state = @existing_state
+
+    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
+
+      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
+        end
+      end
+    end
+
+    private
+
+      def process_result(result, iteration)
+        unless result.error?
+          Output::Iteration::Summary.call(self, result)
+        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
+
+        result.status != :completed || @state.iteration < @config.min_iterations
+      end
+
+      def max_iterations_reached?
+        @config.max_iterations > 0 && @state.iteration > @config.max_iterations
+      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
+      end
+  end
+end

data/lib/ralph/output/active_loop_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class ActiveLoopError
+      def self.call(existing_state, path:)
+        $stderr.puts "Error: A Ralph loop is already active (iteration #{existing_state.iteration})"
+        $stderr.puts "Started at: #{existing_state.started_at}"
+        $stderr.puts "To cancel it, press Ctrl+C in its terminal or delete #{path}"
+      end
+    end
+  end
+end

data/lib/ralph/output/banner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class Banner
+      def self.call(loop_context)
+        Output::NoPluginWarning.call(loop_context) if loop_context.config.disable_plugins
+
+        puts <<~BANNER
+
+          ╔#{'=' * 66}╗
+          ║                    Ralph Wiggum Loop                            ║
+          ║         Iterative AI Development with #{loop_context.agent.config_name.ljust(20)}        ║
+          ╚#{'=' * 66}╝
+        BANNER
+
+        if loop_context.config.tasks_mode
+          tasks_storage = Storage::Tasks.new
+          unless File.exist?(tasks_storage.path)
+            tasks_storage.initialize_tasks_file
+            Output::TasksFileCreated.call(path: tasks_storage.path)
+          end
+        end
+
+        Output::ConfigSummary.call(loop_context)
+      end
+    end
+  end
+end

data/lib/ralph/output/completion_deferred.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class CompletionDeferred
+      def self.call(config:, next_iteration:)
+        puts "\n⏳ Completion promise detected, but minimum iterations (#{config.min_iterations}) not yet reached."
+        puts "   Continuing to iteration #{next_iteration}..."
+      end
+    end
+  end
+end

data/lib/ralph/output/completion_detected.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class CompletionDetected
+      extend ::Ralph::Helpers
+
+      def self.call(loop_context)
+        puts "\n╔#{'=' * 66}╗"
+        puts "║  ✅ Completion promise detected: <promise>#{loop_context.config.completion_promise}</promise>"
+        puts "║  Task completed in #{loop_context.state.iteration} iteration(s)"
+        puts "║  Total time: #{format_duration_long(loop_context.history.total_duration_ms)}"
+        puts "╚#{'=' * 66}╝"
+      end
+    end
+  end
+end

data/lib/ralph/output/config_summary.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class ConfigSummary
+      def self.call(loop_context)
+        config = loop_context.config
+        agent = loop_context.agent
+        prompt = loop_context.prompt
+
+        prompt_text = prompt.to_s
+        prompt_preview = prompt_text.gsub(/\s+/, ' ')[0, 80] + (prompt_text.length > 80 ? '...' : '')
+        puts "Task: #{prompt_preview}"
+        puts "Completion promise: #{config.completion_promise}"
+        if config.tasks_mode
+          puts 'Tasks mode: ENABLED'
+          puts "Task promise: #{config.task_promise}"
+        end
+        puts "Min iterations: #{config.min_iterations}"
+        puts "Max iterations: #{config.max_iterations > 0 ? config.max_iterations : 'unlimited'}"
+        puts "Agent: #{agent.config_name}"
+        puts "Model: #{config.model}" if config.model && !config.model.empty?
+        puts 'OpenCode plugins: non-auth plugins disabled' if config.disable_plugins && agent.type == :opencode
+        puts 'Permissions: auto-approve all tools' if config.allow_all_permissions
+        puts ''
+        puts 'Starting loop... (Ctrl+C to stop)'
+        puts '═' * 68
+      end
+    end
+  end
+end

data/lib/ralph/output/context_consumed.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class ContextConsumed
+      def self.call
+        puts "📝 Context was consumed this iteration"
+      end
+    end
+  end
+end

data/lib/ralph/output/iteration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    module Iteration
+      class Header
+        def self.call(loop_context)
+          config = loop_context.config
+          iteration = loop_context.state.iteration
+
+          iter_info = config.max_iterations > 0 ? " / #{config.max_iterations}" : ''
+          min_info = config.min_iterations > 1 && iteration < config.min_iterations ? " (min: #{config.min_iterations})" : ''
+          puts "\n🔄 Iteration #{iteration}#{iter_info}#{min_info}"
+          puts '─' * 68
+        end
+      end
+
+      class Summary
+        extend ::Ralph::Helpers
+
+        def self.call(loop_context, result)
+          tool_summary = format_tool_summary(result.tool_counts)
+          puts "\nIteration Summary"
+          puts "─" * 68
+          puts "Iteration: #{loop_context.state.iteration}"
+          puts "Elapsed:   #{format_duration(result.duration_ms)}"
+          if tool_summary && !tool_summary.empty?
+            puts "Tools:     #{tool_summary}"
+          else
+            puts "Tools:     none"
+          end
+          puts "Exit code: #{result.exit_code}"
+          puts "Completion promise: #{result.completion_detected ? "detected" : "not detected"}"
+        end
+      end
+
+      class Error
+        def self.call(loop_context, error)
+          $stderr.puts "\n❌ Error in iteration #{loop_context.state.iteration}: #{error}"
+          puts "Continuing to next iteration..."
+        end
+      end
+    end
+  end
+end

data/lib/ralph/output/max_iterations_reached.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class MaxIterationsReached
+      extend ::Ralph::Helpers
+
+      def self.call(loop_context)
+        puts "\n╔#{'=' * 66}╗"
+        puts "║  Max iterations (#{loop_context.config.max_iterations}) reached. Loop stopped."
+        puts "║  Total time: #{format_duration_long(loop_context.history.total_duration_ms)}"
+        puts "╚#{'=' * 66}╝"
+      end
+    end
+  end
+end

data/lib/ralph/output/no_plugin_warning.rb

@@ -0,0 +1,14 @@
+module Ralph
+  module Output
+    class NoPluginWarning
+      def self.call(loop_context)
+        case loop_context.agent.type
+        when :claude_code
+          warn 'Warning: --no-plugins has no effect with Claude Code agent'
+        when :codex
+          warn 'Warning: --no-plugins has no effect with Codex agent'
+        end
+      end
+    end
+  end
+end

data/lib/ralph/output/nonzero_exit_warning.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class NonzeroExitWarning
+      def self.call(loop_context, result)
+        warn "\n⚠️  #{loop_context.agent.config_name} exited with code #{result.exit_code}. Continuing to next iteration."
+      end
+    end
+  end
+end

data/lib/ralph/output/plugin_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class PluginError
+      def self.call
+        $stderr.puts "\n❌ OpenCode tried to load the legacy 'ralph-wiggum' plugin. This package is CLI-only."
+        $stderr.puts "Remove 'ralph-wiggum' from your opencode.json plugin list, or re-run with --no-plugins."
+      end
+    end
+  end
+end