ralph.rb 1.2.435535439 → 2.0.0

data/lib/ralph/loop.rb

@@ -1,196 +1,139 @@
-#            _       _                _
-#  _ __ __ _| |_ __ | |__   __      _(_) __ _  __ _ _   _ _ __ ___
-# | '__/ _` | | '_ \| '_ \  \ \ /\ / / |/ _` |/ _` | | | | '_ ` _ \
-# | | | (_| | | |_) | | | |  \ 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 completion string
+  #   - max iterations are reached
+  #   - total duration 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
+    SYSTEM_PROMPT = <<~PROMPT
+      You are working autonomously in a loop. IMPORTANT RULES:
+      1. Do NOT ask the user any questions. Do NOT wait for user input.
+         If you need information, read the specs, code, or docs yourself.
+      2. Work through the task methodically. Use the todo list to track progress.
+      3. When you have FULLY completed the task, you MUST output the exact
+         completion string on its own line: %<completion>s
+      4. Do not output the completion string until ALL work is truly done.
+    PROMPT
+
+    attr_reader :metrics, :iteration_number, :completed
+
+    def initialize(options)
+      @prompt = options[:prompt]
+      @model = options[:model]
+      @max_iterations = options[:max_iterations]
+      @duration_limit = options[:duration]
+      @max_context = options[:max_context]
+      @completion_string = options[:completion] || "<promise>COMPLETE</promise>"
+      @metrics = Metrics.new
+      @iteration_number = 0
+      @completed = false
+      @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
+      @started_at = now_seconds
+      @display.show_start(@prompt)
+
+      loop do
+        break if should_stop_loop?
+
+        @iteration_number += 1
+        @metrics.new_iteration
+        @display.show_iteration_start
+
+        run_iteration
+
+        @display.show_iteration_end
       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
+      @display.show_summary
+      @completed
+    end
 
-      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
+    # Total elapsed wall-clock seconds since the loop started
+    def elapsed_seconds
+      if @started_at
+        now_seconds - @started_at
+      else
+        0.0
       end
     end
 
     private
 
-      def process_result(result, iteration)
-        unless result.error?
-          Output::Iteration::Summary.call(self, result)
+    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_limit && elapsed_seconds >= @duration_limit
+        @display.show_termination("duration limit reached (#{@duration_limit}s)")
+        true
+      else
+        false
+      end
+    end
+
+    def run_iteration
+      iteration_started_at = now_seconds
+      agent = Opencode.new(model: @model)
+      full_prompt = build_prompt
+
+      agent.run(full_prompt) do |event|
+        @metrics.process(event)
+        @display.show_event(event)
+
+        if event.is_a?(Events::Text)
+          check_completion(event.text)
         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"
-          )
+        if should_cancel_iteration?(iteration_started_at)
+          @display.show_iteration_cancelled(cancel_reason(iteration_started_at))
+          agent.cancel
+          break
         end
+      end
+    end
 
-        result.status != :completed || @state.iteration < @config.min_iterations
+    def should_cancel_iteration?(iteration_started_at)
+      if @max_context && @metrics.current_context >= @max_context
+        true
+      elsif @duration_limit && elapsed_seconds >= @duration_limit
+        true
+      else
+        false
       end
+    end
 
-      def max_iterations_reached?
-        @config.max_iterations > 0 && @state.iteration > @config.max_iterations
+    def cancel_reason(iteration_started_at)
+      if @max_context && @metrics.current_context >= @max_context
+        "context limit reached (#{@metrics.current_context}/#{@max_context})"
+      elsif @duration_limit && elapsed_seconds >= @duration_limit
+        "duration limit reached"
+      else
+        "unknown"
       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 check_completion(text)
+      if text && text.include?(@completion_string)
+        @completed = true
       end
+    end
+
+    def build_prompt
+      system_instructions = format(SYSTEM_PROMPT, completion: @completion_string)
+      "#{system_instructions}\n\n---\n\n#{@prompt}"
+    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

data/lib/ralph/opencode.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ralph
+  # Wraps the opencode CLI to run headless agent sessions with JSON stream output.
+  #
+  # Spawns `opencode run` as a subprocess and yields parsed events line-by-line
+  # from the JSON stream. Supports cancellation via Process.kill.
+  class Opencode
+    attr_reader :model, :agent, :pid
+
+    def initialize(model: nil, agent: nil)
+      @model = model
+      @agent = agent
+      @pid = nil
+      @process_thread = nil
+    end
+
+    # Run opencode with the given prompt. Yields each parsed Event to the block.
+    # Returns the exit status of the opencode process.
+    def run(prompt, &block)
+      command = build_command(prompt)
+      @pid = nil
+
+      Open3.popen3(*command) do |stdin, stdout, stderr, wait_thread|
+        @pid = wait_thread.pid
+        stdin.close
+
+        stdout.each_line do |line|
+          line.strip!
+          if line.length > 0
+            Events.parse(line).then do |event|
+              block.call(event) if event
+            end
+          end
+        end
+
+        wait_thread.value
+      end
+    end
+
+    # Send SIGTERM to the running opencode process.
+    def cancel
+      if @pid
+        Process.kill("TERM", @pid)
+      end
+    rescue Errno::ESRCH
+      # Process already exited -- nothing to do
+    end
+
+    # Check whether opencode is available on the system PATH.
+    def self.available?
+      system("which opencode > /dev/null 2>&1")
+    end
+
+    private
+
+    def build_command(prompt)
+      command = ["opencode", "run"]
+      command.push("--model", @model) if @model
+      command.push("--agent", @agent) if @agent
+      command.push("--format", "json")
+      command.push(prompt)
+      command
+    end
+  end
+end

data/lib/ralph/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ralph
-  VERSION = "1.2.435535439"
+  VERSION = "2.0.0"
 end

data/lib/ralph.rb

@@ -60,8 +60,5 @@ module Ralph
   # ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣶⣤⣤⣄⣀⣀⣈⣉⠉⠉⠉⠉⠙⠛⠛⠛⠛⠛⠉⠉⣀⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
 end
 
-# Helpers must load first since other modules extend it at parse time
-require_relative "ralph/helpers"
-
 # Require everything else by globbing, because I'm too lazy to do anything else
 Dir[File.join(__dir__, "ralph", "**", "*.rb")].sort.each { |f| require f }

data/plans/00-complete-implementation.md

@@ -0,0 +1,120 @@
+# Ralph.rb Complete Implementation Plan
+
+This is the master plan that coordinates all individual component implementations into a cohesive system.
+
+## Phase 1: Foundation Setup
+- [ ] Verify Ruby development environment and dependencies
+- [ ] Set up project structure following Ruby conventions
+- [ ] Create basic gemspec and package configuration
+- [ ] Set up testing framework (RSpec or Minitest)
+- [ ] Configure RuboCop style checking
+- [ ] Create basic CI/CD configuration files
+
+## Phase 2: Core Infrastructure (Parallel Development)
+- [ ] **CLI Implementation** (Plan 01)
+  - [ ] Basic executable and argument parsing
+  - [ ] Option validation and error handling
+  - [ ] Unix pipe support implementation
+- [ ] **Metrics Foundation** (Plan 04)  
+  - [ ] Event parsing infrastructure
+  - [ ] JSON stream processing
+  - [ ] Basic token calculation logic
+- [ ] **Agent Integration Foundation** (Plan 03)
+  - [ ] Opencode wrapper class
+  - [ ] Process management basics
+  - [ ] JSON stream consumption
+
+## Phase 3: Loop Integration Core
+- [ ] **Loop Implementation** (Plan 02)
+  - [ ] Basic loop architecture
+  - [ ] Iteration management system
+  - [ ] Context guard implementation
+- [ ] **Component Integration**
+  - [ ] Metrics → Loop interface for context monitoring
+  - [ ] Loop → Agents interface for iteration control
+  - [ ] CLI → Loop interface for parameter passing
+
+## Phase 4: Advanced Features Integration
+- [ ] **Complete Agent Integration**
+  - [ ] Full opencode command execution
+  - [ ] Event forwarding to Metrics
+  - [ ] Process lifecycle management
+- [ ] **Advanced Metrics**
+  - [ ] Real-time monitoring interface
+  - [ ] Threshold-based alerting
+  - [ ] Historical data tracking
+- [ ] **Loop Termination Logic**
+  - [ ] Completion string detection
+  - [ ] Time and iteration limits
+  - [ ] Context-based cancellation
+
+## Phase 5: Display and User Experience
+- [ ] Real-time progress display implementation
+- [ ] Token usage visualization
+- [ ] Error message formatting and display
+- [ ] Help system and documentation
+- [ ] Debug and verbose output modes
+
+## Phase 6: Testing and Quality Assurance
+- [ ] **Unit Testing**
+  - [ ] CLI argument parsing tests
+  - [ ] Metrics calculation tests
+  - [ ] Loop logic tests
+  - [ ] Agent integration tests
+- [ ] **Integration Testing**
+  - [ ] End-to-end workflow tests
+  - [ ] Error scenario testing
+  - [ ] Performance testing
+- [ ] **Style and Quality**
+  - [ ] RuboCop compliance verification
+  - [ ] Code coverage requirements
+  - [ ] Documentation completeness
+
+## Phase 7: Documentation and Deployment
+- [ ] Complete README with usage examples
+- [ ] API documentation for all components
+- [ ] Installation and setup guides
+- [ ] Troubleshooting and FAQ sections
+- [ ] Release notes and changelog
+
+## Phase 8: Performance Optimization
+- [ ] Profile and optimize hot paths
+- [ ] Memory usage optimization
+- [ ] JSON stream parsing performance
+- [ ] Concurrent processing optimizations
+- [ ] Resource cleanup and garbage collection
+
+## Critical Success Criteria
+- [ ] All four component plans completed successfully
+- [ ] Integration between components works seamlessly
+- [ ] Real-time monitoring meets performance requirements
+- [ ] Unix philosophy and CLI design principles followed
+- [ ] Error handling is comprehensive and user-friendly
+- [ ] Code quality meets Ruby style standards
+- [ ] Test coverage exceeds 90%
+- [ ] Documentation is complete and accurate
+
+## Risk Mitigation
+- [ ] Component integration points identified and tested early
+- [ ] Fallback mechanisms for opencode CLI failures
+- [ ] Graceful degradation for partial system failures
+- [ ] Comprehensive logging for troubleshooting
+- [ ] Modular design allows component replacement/upgrades
+
+## Dependencies and External Requirements
+- [ ] Opencode CLI installed and accessible
+- [ ] Ruby 3.0+ with standard library
+- [ ] Unix-like environment for pipe support
+- [ ] Sufficient memory for JSON stream processing
+- [ ] Network access for opencode API communication
+
+## Final Verification Checklist
+- [ ] CLI accepts all specified options correctly
+- [ ] Loop manages iterations and context properly
+- [ ] Agents communicate with opencode reliably
+- [ ] Metrics provide accurate real-time data
+- [ ] Complete workflow functions end-to-end
+- [ ] All error scenarios handled gracefully
+- [ ] Performance meets real-time requirements
+- [ ] Documentation enables easy adoption
+- [ ] Code quality and tests pass all checks

data/plans/01-cli-implementation.md

@@ -0,0 +1,53 @@
+# Ralph.rb CLI Implementation Plan
+
+This plan outlines the phased implementation of the Ralph.rb command-line interface based on the CLI specification in `specs/cli.md`.
+
+## Phase 1: Core CLI Infrastructure
+- [ ] Create `exe/ralph` executable with proper shebang and permissions
+- [ ] Set up basic argument parsing using Ruby's OptionParser or similar
+- [ ] Implement standard Unix-style pipe support for stdin input
+- [ ] Add basic help/version output functionality
+- [ ] Set up project structure with lib/ directory and main.rb entry point
+
+## Phase 2: Command Line Options Implementation
+- [ ] Implement `--model` option for model selection validation
+- [ ] Add `--max-iterations` parameter with integer validation
+- [ ] Implement `--duration` option with time parsing (seconds/minutes)
+- [ ] Add `--max-context` option with integer validation
+- [ ] Implement `--completion` option for completion string detection
+- [ ] Add validation for required vs optional parameters
+
+## Phase 3: Input Processing and Validation
+- [ ] Implement stdin reading with proper encoding handling
+- [ ] Create input validation for prompt files vs inline prompts
+- [ ] Add error handling for malformed input or missing files
+- [ ] Implement argument combination logic (stdin + args)
+- [ ] Add debug mode for troubleshooting input processing
+
+## Phase 4: Integration Preparation
+- [ ] Create interface stubs for Loop, Agent, and Metrics components
+- [ ] Implement parameter passing to core loop system
+- [ ] Add configuration management and defaults
+- [ ] Create error handling and user-friendly error messages
+- [ ] Implement logging/verbosity levels if needed
+
+## Phase 5: Testing and Validation
+- [ ] Write unit tests for CLI argument parsing
+- [ ] Test pipe functionality with various input sources
+- [ ] Validate error handling for invalid inputs
+- [ ] Test integration with other components (mock versions)
+- [ ] Add integration tests for complete CLI workflow
+
+## Verification Criteria
+- [ ] CLI accepts all specified options with proper validation
+- [ ] Unix pipe functionality works correctly (`cat file | ralph`)
+- [ ] Error messages are clear and helpful
+- [ ] All options pass parameters correctly to core system
+- [ ] Help documentation is comprehensive and accurate
+- [ ] No Ruby style violations (run `bin/rubocop`)
+- [ ] All tests pass (run `bin/test`)
+
+## Dependencies
+- Requires Loop, Agents, and Metrics components to be implemented
+- Needs Ruby OptionParser or equivalent for argument handling
+- Integration with opencil CLI for agent execution