ralph.rb 1.2.435535439 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cecf1d0a5488b9714cb3bcdfb2d326d6263776e8e22feed4cb5853e850c2d9e
-  data.tar.gz: e57d98a767842503725cfd59f4398ee4c2aa608c90039d20451ff485b9f0aa96
+  metadata.gz: f3950370724ceca76366a10ef15914ab10abc209595d1a5c8ddc466c071ea032
+  data.tar.gz: 0f85bc6a1f1a00d98ee6940928ce3ba506f6591536e14e4eb0cd30c3e6e914db
 SHA512:
-  metadata.gz: 9d9ed862ebcae5ceea7c14cb89ae68655bfa5435e9b1106333a98f73c555924ec10b26ffa1f287268e4faa928e6af57ad59346649df19d9780c52081166517c8
-  data.tar.gz: 37e114a76113057d248c6daa48c13c303547bac384fcc9f2818ceb33dce04d8274aed3841fbe07522cfc4450f4482d6e27c41f2356de5e17b89483eb8bf697a8
+  metadata.gz: 181d38c7c1e72fd04ac4b22118a09caac7f262d7037d4e1c42f4f3440bac0b6a3c3b08d48934b2083ec3972a241457a18770c3f6c0038d82bd3ae33afd790416
+  data.tar.gz: 1feee430c07868a4877f351c1dcef388f42b99cb1db33b1c7515e22aeda33dba7ac0ce1abd5568c1315ded580f674f48f394909db2267d26bc9a64092e8d62e9

data/.github/workflows/gem-push.yml

@@ -2,9 +2,9 @@ name: Ruby Gem
 
 on:
   push:
-    branches: ["ruby"]
+    branches: ["ruby2"]
   pull_request:
-    branches: ["ruby"]
+    branches: ["ruby2"]
 
 jobs:
   build:

data/Gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gemspec
+gemspec name: "ralph.rb"
 
 group :development do
   #gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    ralph.rb (1.2.435535439)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rubocop (1.84.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  ralph.rb!
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.7.2

data/lib/ralph/cli.rb

@@ -1,222 +1,103 @@
 # frozen_string_literal: true
 
 module Ralph
+  # Command-line interface for ralph. Parses arguments, reads stdin when piped,
+  # combines everything into a prompt, and launches the Loop.
+  #
+  # Usage:
+  #   cat prompt.md | ralph "extra instructions" --model=opus-4.5 --max-iterations=10
   class CLI
-    def initialize(argv = ARGV)
-      @config = Config.new
-
-      @parser = OptionParser.new do |o|
-        o.banner = <<~BANNER
-          Ralph Wiggum Loop - Iterative AI development with AI agents
-
-          Usage:
-            ralph "<prompt>" [options]
-
-          Commands:
-            --status            Show current Ralph loop status and history
-            --add-context TEXT  Add context for the next iteration
-            --clear-context     Clear any pending context
-            --list-tasks        Display the current task list with indices
-            --add-task "desc"   Add a new task to the list
-            --remove-task N     Remove task at index N (including subtasks)
-
-          Options:
-        BANNER
-
-        o.on("--agent AGENT", Agents.valid_agent_names, "AI agent: #{Agents.valid_agent_names.join(', ')} (default: opencode)") do |v|
-          @config.chosen_agent = v
-        end
-
-        o.on("--min-iterations N", Integer, "Minimum iterations before completion (default: 1)") do |v|
-          @config.min_iterations = v
-        end
-
-        o.on("--max-iterations N", Integer, "Maximum iterations before stopping (default: unlimited)") do |v|
-          @config.max_iterations = v
-        end
+    def initialize(argv)
+      @argv = argv.dup
+      @options = {
+        model: nil,
+        max_iterations: nil,
+        duration: nil,
+        max_context: nil,
+        completion: nil
+      }
+    end
 
-        o.on("--completion-promise TEXT", "Phrase that signals completion (default: COMPLETE)") do |v|
-          @config.completion_promise = v
+    def run
+      parse_options
+      build_prompt.then do |prompt|
+        if prompt.nil? || prompt.strip.empty?
+          $stderr.puts "Error: no prompt provided."
+          $stderr.puts "Usage: ralph \"your prompt\" [options]"
+          $stderr.puts "       cat prompt.md | ralph [options]"
+          $stderr.puts
+          $stderr.puts parser.help
+          exit 1
+        else
+          @options[:prompt] = prompt
+          Ralph::Loop.new(@options).run
         end
+      end
+    end
 
-        o.on("-t", "--tasks", "Enable Tasks Mode for structured task tracking") do
-          @config.tasks_mode = true
-        end
+    private
 
-        o.on("--task-promise TEXT", "Phrase that signals task completion (default: READY_FOR_NEXT_TASK)") do |v|
-          @config.task_promise = v
-        end
+    def parse_options
+      parser.parse!(@argv)
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument => error
+      $stderr.puts "Error: #{error.message}"
+      $stderr.puts parser.help
+      exit 1
+    end
 
-        o.on("--model MODEL", "Model to use (agent-specific)") do |v|
-          @config.model = v
-        end
+    def parser
+      @parser ||= OptionParser.new do |option_parser|
+        option_parser.banner = "Usage: ralph [prompt] [options]"
+        option_parser.separator ""
+        option_parser.separator "Options:"
 
-        o.on("--[no-]stream", "Stream agent output in real-time (default: on)") do |v|
-          @config.stream_output = v
+        option_parser.on("--model=MODEL", "Model to use (e.g. opus-4.5)") do |value|
+          @options[:model] = value
         end
 
-        o.on("--verbose-tools", "Print every tool line (disable compact summary)") do
-          @config.verbose_tools = true
+        option_parser.on("--max-iterations=N", Integer, "Maximum number of iterations") do |value|
+          @options[:max_iterations] = value
         end
 
-        o.on("--no-plugins", "Disable non-auth OpenCode plugins (opencode only)") do
-          @config.disable_plugins = true
+        option_parser.on("--duration=SECONDS", Integer, "Maximum total duration in seconds") do |value|
+          @options[:duration] = value
         end
 
-        o.on("--[no-]allow-all", "Auto-approve all tool permissions (default: on)") do |v|
-          @config.allow_all_permissions = v
+        option_parser.on("--max-context=N", Integer, "Maximum context tokens before iteration restart") do |value|
+          @options[:max_context] = value
         end
 
-        # Subcommands -- these set a command to dispatch after parsing
-        o.on("-v", "--version", "Show version") do
-          puts "ralph #{VERSION}"
-          exit 0
+        option_parser.on("--completion=STRING", "Completion string the agent emits when done") do |value|
+          @options[:completion] = value
         end
 
-        o.on("--status", "Show current loop status and history") do
-          Output::Status.call(options: @config.to_h)
+        option_parser.on("-h", "--help", "Show this help message") do
+          puts option_parser
           exit 0
         end
 
-        o.on("--add-context TEXT", "Add context for the next iteration") do |context_text|
-
-          Storage::Context.new.append(
-            "\n## Context added at #{Time.now.utc.iso8601}\n#{context_text}\n"
-          )
-
-          puts "✅ Context added for next iteration"
-          puts "   File: #{Storage::Context.new.path}"
-
-          Storage::State.load.then do |state|
-            if state&.active
-              puts "   Will be picked up in iteration #{state.iteration + 1}"
-            else
-              puts "   Will be used when loop starts"
-            end
-          end
-
+        option_parser.on("-v", "--version", "Show version") do
+          puts "ralph #{Ralph::VERSION}"
           exit 0
         end
-
-        o.on("--clear-context", "Clear any pending context") do
-          Storage::Context.new.then do |context|
-            if context.present?
-              context.clear
-              puts "✅ Context cleared"
-            else
-              puts "ℹ️  No pending context to clear"
-            end
-          end
-
-          exit 0
-        end
-
-        o.on("--list-tasks", "Display the current task list") do
-          begin
-            Storage::Tasks.new.load_tasks.then do |tasks|
-              if tasks
-                tasks.display_with_indices
-              else
-                puts "No tasks file found. Use --add-task to create your first task."
-              end
-            end
-          rescue StandardError => e
-            $stderr.puts "Error reading tasks file: #{e}"
-            exit 1
-          end
-
-          exit 0
-        end
-
-        o.on("--add-task DESC", "Add a new task to the list") do |description|
-          begin
-            Storage::Tasks.new.add_task(description)
-            puts "✅ Task added: \"#{description}\""
-          rescue StandardError => e
-            $stderr.puts "Error adding task: #{e}"
-            exit 1
-          end
-
-          exit 0
-        end
-
-        o.on("--remove-task N", Integer, "Remove task at index N") do |task_index|
-          begin
-            Storage::Tasks.new.remove_task(task_index)
-            puts "✅ Removed task #{task_index} and its subtasks"
-          rescue IndexError => e
-            $stderr.puts "Error: #{e.message}"
-            exit 1
-          rescue RuntimeError => e
-            $stderr.puts "Error: #{e.message}"
-            exit 1
-          rescue StandardError => e
-            $stderr.puts "Error removing task: #{e}"
-            exit 1
-          end
-
-          exit 0
-        end
-
-        o.separator ""
-        o.separator "Examples:"
-        o.separator '  ralph "Build a REST API for todos"'
-        o.separator '  ralph "Fix the auth bug" --max-iterations 10'
-        o.separator '  ralph "Add tests" --completion-promise "ALL TESTS PASS" --model openai/gpt-5.1'
-        o.separator '  ralph --status'
-        o.separator '  ralph --add-context "Focus on the auth module first"'
-        o.separator ""
-        o.separator "How it works:"
-        o.separator "  1. Sends your prompt to the selected AI agent"
-        o.separator "  2. AI agent works on the task"
-        o.separator "  3. Checks output for completion promise"
-        o.separator "  4. If not complete, repeats with same prompt"
-        o.separator "  5. AI sees its previous work in files"
-        o.separator "  6. Continues until promise detected or max iterations"
-        o.separator ""
-        o.separator "To stop manually: Ctrl+C"
-        o.separator "Learn more: https://ghuntley.com/ralph/"
       end
-
     end
 
-    def run(argv = ARGV.dup)
-      @user_prompt = @parser.parse(argv).then do |remaining_args|
-        if $stdin.tty?
-          remaining_args.join(" ").strip
-        else
-          [$stdin.read, remaining_args.join(" ")].join("\n").strip
-        end
-      end
+    def build_prompt
+      parts = []
 
-      if @user_prompt.empty?
-        abort "
-          Error: No prompt provided
-          Usage: ralph 'Your task description' [options]
-          Run 'ralph --help' for more information
-        "
+      # Read from stdin if data is being piped in
+      unless $stdin.tty?
+        stdin_content = $stdin.read
+        parts << stdin_content if stdin_content && !stdin_content.strip.empty?
       end
 
-      tasks   = Storage::Tasks.new
-      context = Storage::Context.new
+      # Remaining positional arguments are the inline prompt
+      parts << @argv.join(" ") if @argv.any?
 
-      PromptTemplate.inject(@user_prompt, context: context, tasks: tasks).then do |prompt|
-        @config.prompt = prompt
-
-        if @config.max_iterations > 0 && @config.min_iterations > @config.max_iterations
-          abort "Error: --min-iterations (#{@config.min_iterations}) cannot be greater than --max-iterations (#{@config.max_iterations})"
-        end
-
-        state   = Storage::State.from_config(@config, prompt: prompt)
-        history = Storage::History.new
-
-        Ralph::Loop.new(@config, state, history, context, tasks).run
+      if parts.any?
+        parts.join("\n\n")
       end
-
-    rescue StandardError => e
-      $stderr.puts "Fatal error: #{e}"
-      Storage::State.clear
-      exit 1
     end
   end
 end

data/lib/ralph/display.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ralph
+  # Handles all terminal output for the loop -- iteration status, metrics,
+  # agent text, and summary information.
+  class Display
+    SEPARATOR = "-" * 60
+
+    def initialize(loop_engine)
+      @loop_engine = loop_engine
+    end
+
+    def show_start(prompt)
+      puts SEPARATOR
+      puts "ralph -- autonomous agentic loop"
+      puts SEPARATOR
+      puts "Prompt: #{prompt[0, 200]}#{"..." if prompt.length > 200}"
+      puts SEPARATOR
+    end
+
+    def show_iteration_start
+      puts
+      puts "#{SEPARATOR}"
+      puts "Iteration #{@loop_engine.iteration_number} | " \
+           "elapsed: #{format_duration(@loop_engine.elapsed_seconds)} | " \
+           "context: #{format_tokens(@loop_engine.metrics.current_context)} | " \
+           "tokens: #{format_tokens(@loop_engine.metrics.tokens_consumed)}"
+      puts SEPARATOR
+    end
+
+    def show_event(event)
+      if event.is_a?(Events::Text) && event.text
+        print event.text
+        $stdout.flush
+      end
+
+      if event.is_a?(Events::ToolUse)
+        puts
+        puts "  [tool] #{event.tool} (#{event.status})"
+      end
+
+      if event.is_a?(Events::StepFinish)
+        puts
+        puts "  [step] context=#{format_tokens(event.context_size)} " \
+             "output=#{format_tokens(event.output_tokens)} " \
+             "cache_r=#{format_tokens(event.cache_read)} " \
+             "cache_w=#{format_tokens(event.cache_write)}"
+      end
+    end
+
+    def show_iteration_end
+      puts
+      puts "  Iteration #{@loop_engine.iteration_number} complete | " \
+           "steps: #{@loop_engine.metrics.step_count} | " \
+           "iteration tokens: #{format_tokens(@loop_engine.metrics.iteration_tokens)}"
+    end
+
+    def show_iteration_cancelled(reason)
+      puts
+      puts "  ** Iteration cancelled: #{reason}"
+    end
+
+    def show_termination(reason)
+      puts
+      puts "  ** Loop terminated: #{reason}"
+    end
+
+    def show_summary
+      metrics = @loop_engine.metrics
+      puts
+      puts SEPARATOR
+      puts "SUMMARY"
+      puts SEPARATOR
+      puts "  Status:      #{@loop_engine.completed ? "COMPLETED" : "TERMINATED"}"
+      puts "  Iterations:  #{@loop_engine.iteration_number}"
+      puts "  Duration:    #{format_duration(@loop_engine.elapsed_seconds)}"
+      puts "  Steps:       #{metrics.step_count}"
+      puts "  Tokens:      #{format_tokens(metrics.tokens_consumed)}"
+      puts "  Context:     #{format_tokens(metrics.current_context)}"
+      puts SEPARATOR
+    end
+
+    private
+
+    def format_duration(seconds)
+      minutes = (seconds / 60).to_i
+      remaining_seconds = (seconds % 60).to_i
+      if minutes > 0
+        "#{minutes}m #{remaining_seconds}s"
+      else
+        "#{remaining_seconds}s"
+      end
+    end
+
+    def format_tokens(count)
+      if count >= 1_000_000
+        format("%.1fM", count / 1_000_000.0)
+      elsif count >= 1_000
+        format("%.1fk", count / 1_000.0)
+      else
+        count.to_s
+      end
+    end
+  end
+end

data/lib/ralph/events.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Events
+    # Base event wrapping the common fields from opencode JSON stream lines
+    class Base
+      attr_reader :type, :timestamp, :session_id, :part
+
+      def initialize(data)
+        @type = data["type"]
+        @timestamp = data["timestamp"]
+        @session_id = data["sessionID"]
+        @part = data["part"] || {}
+      end
+    end
+
+    # Emitted when a new LLM step begins
+    class StepStart < Base
+      def snapshot
+        part["snapshot"]
+      end
+    end
+
+    # Emitted when the model streams text content
+    class Text < Base
+      def text
+        part["text"]
+      end
+    end
+
+    # Emitted when the model invokes a tool
+    class ToolUse < Base
+      def tool
+        part["tool"]
+      end
+
+      def call_id
+        part["callID"]
+      end
+
+      def state
+        part["state"] || {}
+      end
+
+      def status
+        state["status"]
+      end
+
+      def input
+        state["input"]
+      end
+
+      def output
+        state["output"]
+      end
+    end
+
+    # Emitted when a step completes -- carries the token usage data
+    class StepFinish < Base
+      def reason
+        part["reason"]
+      end
+
+      def tokens
+        part["tokens"] || {}
+      end
+
+      def input_tokens
+        tokens["input"] || 0
+      end
+
+      def output_tokens
+        tokens["output"] || 0
+      end
+
+      def reasoning_tokens
+        tokens["reasoning"] || 0
+      end
+
+      def cache
+        tokens["cache"] || {}
+      end
+
+      def cache_read
+        cache["read"] || 0
+      end
+
+      def cache_write
+        cache["write"] || 0
+      end
+
+      # Total context size for this step: input + cache.read + cache.write
+      def context_size
+        input_tokens + cache_read + cache_write
+      end
+    end
+
+    EVENT_TYPES = {
+      "step_start" => StepStart,
+      "text" => Text,
+      "tool_use" => ToolUse,
+      "step_finish" => StepFinish
+    }.freeze
+
+    # Parse a single JSON line into the appropriate event object.
+    # Returns nil for unknown event types or malformed JSON.
+    def self.parse(line)
+      data = JSON.parse(line)
+      event_class = EVENT_TYPES[data["type"]]
+      if event_class
+        event_class.new(data)
+      end
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end