robot_lab-to 0.2.6

data/lib/robot_lab/to/prompt_builder.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    # Builds the per-iteration system prompt injected into each robot.
+    class PromptBuilder
+      def initialize(config)
+        @config = config
+      end
+
+      def build(run, notes_content, workspace: nil, pending_commit_failure: nil, resolved_decisions: [])
+        sections = [role_section(run), notes_section(run, notes_content)]
+        sections << workspace_section(workspace) if workspace && !workspace.empty?
+        sections << decisions_answered_section(resolved_decisions) if resolved_decisions && !resolved_decisions.empty?
+        sections << task_section
+        sections << score_feedback_section(run)
+        sections << verify_section if @config.verify_command
+        sections << decision_guidance_section if @config.decisions_enabled?
+        sections << submit_section
+        sections << repair_section(pending_commit_failure) if pending_commit_failure
+        sections << stop_when_section(@config.stop_when) if @config.stop_when
+        sections.compact.join("\n\n")
+      end
+
+      private
+
+      # Close the loop: tell the robot how its recent iterations scored so each
+      # attempt is a testable hypothesis against the target, not a blind guess.
+      # Returns nil for unscored runs (no measure/target/prose) so legacy runs are
+      # unchanged.
+      def score_feedback_section(run)
+        return unless scored_run?
+
+        body = [best_line(run), progress_line(run)].compact.join("\n")
+        return if body.empty?
+
+        <<~MD.chomp
+          ## Score Feedback
+
+          #{body}
+        MD
+      end
+
+      def scored_run?
+        !@config.eval_measure.nil? || !@config.eval_target.nil? ||
+          @config.eval == "prose" || !@config.eval_spec.nil?
+      end
+
+      def best_line(run)
+        return unless run.last_score_value
+
+        target = @config.eval_target ? " (target: #{@config.eval_target})" : ""
+        "Best score committed so far: #{run.last_score_value}#{target}."
+      end
+
+      def progress_line(run)
+        stalled = run.iterations_since_improvement
+        if stalled.positive?
+          "The last #{stalled} iteration(s) did not improve and were rolled back. " \
+            "A similar change will be rolled back again — try a DIFFERENT approach now."
+        elsif run.iteration > 1
+          "Your last change improved the result and was committed. Build on it."
+        end
+      end
+
+      # Feed back the human's answers to questions the robot raised earlier so it
+      # acts on them this iteration instead of re-raising the same decision.
+      def decisions_answered_section(decisions)
+        items = decisions.map do |d|
+          "- **#{d.question}**\n  → Human decision: #{d.resolution || "(resolved — see #{d.path})"}"
+        end.join("\n")
+
+        <<~MD.chomp
+          ## Answered Decisions
+
+          A human has answered questions you raised in earlier iterations. Act on
+          these decisions now — do NOT raise them again:
+
+          #{items}
+        MD
+      end
+
+      # Calibration guidance: the article's hardest problem is teaching the agent
+      # WHEN to escalate. Name the bar explicitly.
+      def decision_guidance_section
+        <<~MD.chomp
+          ## When to Ask for a Human Decision
+
+          You have a `request_decision` tool. Use it ONLY for a choice that is
+          irreversible or hard to reverse, that sets a public contract, that is
+          genuinely ambiguous about the intent behind the objective, or that
+          falls outside the objective's scope. Always include your recommended
+          option and reasoning (your "lean"). Set blocking=true only when work
+          cannot correctly continue without the answer.
+
+          Do NOT use it for routine engineering choices you are equipped to make
+          yourself — naming, structure, library selection within scope, and the
+          like. Prefer making progress over asking.
+        MD
+      end
+
+      # R3: front-load the project layout so the robot doesn't burn its first
+      # several tool calls re-discovering the workspace (ls/find/read) every run.
+      def workspace_section(files)
+        listing = files.first(200).map { |f| "- #{f}" }.join("\n")
+        <<~MD.chomp
+          ## Project Files
+
+          The project already contains the files below — read them directly instead
+          of re-discovering the layout. (Files you create appear here next iteration.)
+
+          #{listing}
+        MD
+      end
+
+      # R1: name the exact command the orchestrator will grade this iteration by,
+      # so the robot can satisfy it instead of guessing.
+      def verify_section
+        <<~MD.chomp
+          ## Verification — how this iteration is judged
+
+          After your change, the orchestrator runs this EXACT command and only commits
+          if it exits 0 — otherwise everything is rolled back:
+
+              #{@config.verify_command}
+
+          Run it yourself and make it pass BEFORE calling submit_iteration_result.
+        MD
+      end
+
+      def role_section(run)
+        <<~MD.chomp
+          You are an autonomous software engineer working on the following objective:
+
+          **#{run.objective}**
+
+          You are on iteration #{run.iteration}. Work incrementally — make ONE focused improvement per iteration.
+        MD
+      end
+
+      def notes_section(run, content)
+        <<~MD.chomp
+          ## Prior Work (notes.md)
+
+          Read the notes below to understand what has been done in previous iterations.
+          Do NOT modify notes.md — it is maintained automatically by the orchestrator.
+
+          File path: #{run.notes_path}
+
+          ```
+          #{content.strip.empty? ? "(no iterations yet)" : content.strip}
+          ```
+        MD
+      end
+
+      def task_section
+        <<~MD.chomp
+          ## Your Task
+
+          1. Make ONE focused, meaningful change toward the objective.
+          2. Before finishing: stop any background processes (dev servers, watchers, browsers).
+          3. Before finishing: run tests, build, or linters if they exist in the project.
+          4. A complete no-op (no file changes AND no new learnings) is NOT success — set success=false.
+        MD
+      end
+
+      def submit_section
+        <<~MD.chomp
+          ## Required: Submit Your Result
+
+          You MUST call `submit_iteration_result` as your FINAL action. Include:
+          - success: true/false
+          - summary: one sentence describing what you did or why you stopped
+          - key_changes: list of files or changes made
+          - key_learnings: insights worth recording for future iterations
+        MD
+      end
+
+      def repair_section(error)
+        <<~MD.chomp
+          ## ⚠ Previous Commit Failure — Repair Required
+
+          The previous iteration completed successfully but git commit failed with:
+
+          ```
+          #{error.output}
+          ```
+
+          **Fix the uncommitted changes first** before doing anything else. Once the
+          commit issue is resolved, call submit_iteration_result with success=true.
+        MD
+      end
+
+      def stop_when_section(condition)
+        <<~MD.chomp
+          ## Stop Condition
+
+          After completing your work, evaluate whether the following condition is met:
+
+          > #{condition}
+
+          If the condition is met AND this iteration was successful, set should_fully_stop=true
+          in your submit_iteration_result call.
+        MD
+      end
+    end
+  end
+end

data/lib/robot_lab/to/run.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module RobotLab
+  module To
+    # Holds mutable state for a single autonomous run.
+    class Run
+      attr_reader :run_id, :objective, :branch, :base_commit, :notes_path, :log_path,
+                  :run_dir, :decisions_path, :started_at
+      attr_accessor :iteration, :consecutive_failures, :consecutive_errors,
+                    :commits, :input_tokens, :output_tokens,
+                    :last_score_value, :iterations_since_improvement
+
+      def initialize(run_id:, objective:, branch:, base_commit:, notes_path:, log_path:,
+                     run_dir: nil, decisions_path: nil)
+        @run_id              = run_id
+        @objective           = objective
+        @branch              = branch
+        @base_commit         = base_commit
+        @notes_path          = Pathname.new(notes_path)
+        @log_path            = Pathname.new(log_path)
+        @run_dir             = Pathname.new(run_dir || @notes_path.parent)
+        @decisions_path      = Pathname.new(decisions_path || @run_dir.join("decisions"))
+        @started_at          = Time.now
+        @iteration           = 0
+        @consecutive_failures = 0
+        @consecutive_errors  = 0
+        @commits             = 0
+        @input_tokens        = 0
+        @output_tokens       = 0
+        @last_score_value    = nil
+        @iterations_since_improvement = 0
+      end
+
+      def total_tokens     = input_tokens + output_tokens
+      def elapsed_seconds  = Time.now - started_at
+      def state_path       = @run_dir.join("run.json")
+
+      def elapsed_human
+        secs = elapsed_seconds.to_i
+        h = secs / 3600
+        m = (secs % 3600) / 60
+        s = secs % 60
+        if h.positive?
+          "#{h}h #{m}m #{s}s"
+        else
+          m.positive? ? "#{m}m #{s}s" : "#{s}s"
+        end
+      end
+
+      # Serializable snapshot for run.json (enables --resume across processes).
+      def to_h
+        {
+          run_id: run_id, objective: objective, branch: branch, base_commit: base_commit,
+          notes_path: notes_path.to_s, log_path: log_path.to_s, run_dir: run_dir.to_s,
+          decisions_path: decisions_path.to_s, started_at: started_at.iso8601,
+          iteration: iteration, consecutive_failures: consecutive_failures,
+          consecutive_errors: consecutive_errors, commits: commits,
+          input_tokens: input_tokens, output_tokens: output_tokens,
+          last_score_value: last_score_value,
+          iterations_since_improvement: iterations_since_improvement
+        }
+      end
+
+      # Rebuild a Run from a run.json written by #to_h.
+      def self.load(path)
+        data = JSON.parse(File.read(path), symbolize_names: true)
+        run  = new(run_id: data[:run_id], objective: data[:objective], branch: data[:branch],
+                   base_commit: data[:base_commit], notes_path: data[:notes_path],
+                   log_path: data[:log_path], run_dir: data[:run_dir],
+                   decisions_path: data[:decisions_path])
+        run.iteration            = data[:iteration].to_i
+        run.consecutive_failures = data[:consecutive_failures].to_i
+        run.consecutive_errors   = data[:consecutive_errors].to_i
+        run.commits              = data[:commits].to_i
+        run.input_tokens         = data[:input_tokens].to_i
+        run.output_tokens        = data[:output_tokens].to_i
+        run.last_score_value     = data[:last_score_value]
+        run.iterations_since_improvement = data[:iterations_since_improvement].to_i
+        run.instance_variable_set(:@started_at, Time.parse(data[:started_at])) if data[:started_at]
+        run
+      end
+
+      # Derive run_id from current timestamp + random hex suffix.
+      def self.generate_id
+        t = Time.now
+        hex = SecureRandom.hex(3)
+        "#{t.strftime("%Y%m%d-%H%M%S")}-#{hex}"
+      end
+
+      # Slugify objective into a branch-name fragment (max 40 chars).
+      def self.slugify(text)
+        text.downcase
+            .gsub(/[^a-z0-9]+/, "-")
+            .gsub(/^-+|-+$/, "")
+            .slice(0, 40)
+            .then { |s| s.empty? ? "takeover" : s }
+      end
+
+      def self.branch_name(objective)
+        slug = slugify(objective)
+        ts   = Time.now.strftime("%Y%m%d-%H%M%S")
+        "robot-to/#{slug}-#{ts}"
+      end
+    end
+  end
+end

data/lib/robot_lab/to/stop_conditions.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    # Evaluates all stop conditions against the current run state.
+    class StopConditions
+      def initialize(config, run)
+        @config = config
+        @run    = run
+      end
+
+      # Checked before starting a new iteration.
+      def before?
+        check_max_iterations || check_max_tokens
+      end
+
+      # Checked after an iteration completes.
+      def after?
+        check_max_iterations || check_max_tokens || check_consecutive_failures || check_plateau
+      end
+
+      # Checked after a successful iteration with a stop_when condition.
+      def stop_when_met?(result)
+        return false unless @config.stop_when
+        return false unless result.stop?
+
+        raise AbortError, "stop condition met: #{@config.stop_when}"
+      end
+
+      # Called by the orchestrator's token-tracking callback mid-iteration.
+      # Returns the abort reason string if exceeded, nil otherwise.
+      def token_limit_exceeded?
+        return false unless @config.max_tokens
+
+        @run.total_tokens >= @config.max_tokens
+      end
+
+      private
+
+      def check_max_iterations
+        return unless @config.max_iterations
+        return unless @run.iteration >= @config.max_iterations
+
+        raise AbortError, "max iterations reached (#{@config.max_iterations})"
+      end
+
+      def check_max_tokens
+        return unless @config.max_tokens
+        return unless @run.total_tokens >= @config.max_tokens
+
+        raise AbortError, "max tokens reached (#{@config.max_tokens})"
+      end
+
+      def check_consecutive_failures
+        return unless @run.consecutive_failures >= @config.max_consecutive_failures
+
+        raise AbortError, "#{@run.consecutive_failures} consecutive failures"
+      end
+
+      # Diminishing returns: stop after N iterations with no committed improvement.
+      # The primary terminator for pairwise/judged evals, which never set a target.
+      def check_plateau
+        limit = @config.stop_on_plateau
+        return unless limit
+        return unless @run.iterations_since_improvement >= limit
+
+        raise AbortError, "plateau: #{limit} iterations without improvement"
+      end
+    end
+  end
+end

data/lib/robot_lab/to/tools/bash.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module RobotLab
+  module To
+    module Tools
+      # Run a shell command in the working directory and return combined
+      # stdout+stderr plus the exit status. Output is capped and the command is
+      # killed past a timeout so a runaway process can't stall an overnight loop.
+      class Bash < FileTool
+        DEFAULT_TIMEOUT = 120
+        MAX_OUTPUT = 30_000
+
+        description <<~DESC
+          Run a shell command in the project directory and return its combined
+          output and exit status. Use for building, testing, listing, and git.
+        DESC
+
+        param :command, type: "string", desc: "The shell command to run"
+        param :timeout, type: "integer", desc: "Seconds before the command is killed", required: false
+
+        def initialize(robot: nil, timeout: DEFAULT_TIMEOUT)
+          super(robot: robot)
+          @default_timeout = timeout
+        end
+
+        def execute(command:, timeout: nil, **)
+          out, status = run(command, (timeout || @default_timeout).to_i)
+          format_result(out, status)
+        end
+
+        # Run `command`, returning [combined_output, status_string].
+        # status_string is "0".."n" for an exit code, or "timeout"/"error: ...".
+        #
+        # @return [Array(String, String)]
+        def run(command, timeout)
+          out_str = +""
+          status = nil
+          Open3.popen2e(command, chdir: Dir.pwd) do |_stdin, out, wait|
+            reader = Thread.new { out.each_char { |c| out_str << c } }
+            status = finished_within?(wait, timeout) ? wait.value.exitstatus.to_s : kill(wait)
+            reader.join(1)
+          end
+          [out_str, status]
+        rescue SystemCallError, IOError => e
+          ["", "error: #{e.message}"]
+        end
+
+        private
+
+        # @return [Boolean] true if the process finished within `timeout`
+        def finished_within?(wait, timeout)
+          deadline = clock + timeout
+          sleep(0.01) while wait.alive? && clock < deadline
+          !wait.alive?
+        end
+
+        def kill(wait)
+          Process.kill("TERM", wait.pid)
+          "timeout"
+        rescue Errno::ESRCH
+          "timeout"
+        end
+
+        def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def format_result(out, status)
+          body = out.length > MAX_OUTPUT ? "#{out[0, MAX_OUTPUT]}\n[output truncated]" : out
+          "[exit #{status}]\n#{body}"
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/tools/edit.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Tools
+      # Exact-string replacement in an existing file. old_text must match the
+      # file's current contents exactly (whitespace included) and be unique
+      # unless replace_all is set. The ReadBeforeEdit guard requires the file to
+      # have been Read this session first, so old_text reflects real contents.
+      class Edit < FileTool
+        description <<~DESC
+          Replace an exact substring in an existing file. old_text must match the
+          current file contents exactly (including whitespace) and be unique unless
+          replace_all is true. Read the file first to get the exact text.
+        DESC
+
+        param :path, type: "string", desc: "Path of the file to edit"
+        param :old_text, type: "string", desc: "Exact text to replace"
+        param :new_text, type: "string", desc: "Replacement text"
+        param :replace_all, type: "boolean", desc: "Replace every occurrence", required: false
+
+        def execute(path:, old_text:, new_text:, replace_all: false, **)
+          resolved = File.expand_path(path, Dir.pwd)
+          return "Error: file not found: #{path}" unless File.file?(resolved)
+
+          original = File.read(resolved)
+          result = apply(original, old_text.to_s, new_text.to_s, replace_all)
+          return result if result.is_a?(String) && result.start_with?("Error:")
+
+          File.write(resolved, result)
+          "Edited #{path}"
+        rescue SystemCallError => e
+          "Error editing #{path}: #{e.message}"
+        end
+
+        # Pure replacement logic (testable in isolation). Returns the new content
+        # string, or an "Error: ..." string on a precondition failure.
+        #
+        # @return [String]
+        def apply(content, old_text, new_text, replace_all)
+          count = content.scan(old_text).size
+          return "Error: old_text not found in file" if count.zero?
+          if count > 1 && !replace_all
+            return "Error: old_text is not unique (#{count} matches); add context or set replace_all"
+          end
+
+          replace_all ? content.gsub(old_text, new_text) : content.sub(old_text, new_text)
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/tools/file_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Tools
+      # Base for robot_lab-to's built-in workspace tools. RubyLLM derives a
+      # fully-namespaced tool name (e.g. "robot_lab--to--tools--read"); small
+      # models do far better with the short, conventional names the guards and
+      # skill docs reference, so we expose the bare last segment ("read",
+      # "write", "edit", "bash", ...).
+      class FileTool < RobotLab::Tool
+        # @return [String] the short, lowercase tool name
+        def name
+          self.class.short_name
+        end
+
+        # @return [String] last class path segment, snake_cased
+        def self.short_name
+          name_segment ||
+            to_s.split("::").last
+                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+        end
+
+        # Subclasses may override the derived short name.
+        # @return [String, nil]
+        def self.name_segment = nil
+      end
+    end
+  end
+end

data/lib/robot_lab/to/tools/read.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Tools
+      # Read a UTF-8 text file, optionally a line range. Output is capped so a
+      # small local model's context can't be blown by one oversized read
+      # (mirrors little-coder's read-guard intent).
+      class Read < FileTool
+        MAX_LINES = 2000
+
+        description <<~DESC
+          Read a text file and return its contents. Optionally pass offset (1-based
+          start line) and limit (max lines). Always read a file before editing it.
+        DESC
+
+        param :path, type: "string", desc: "Path to the file to read"
+        param :offset, type: "integer", desc: "1-based first line to return", required: false
+        param :limit, type: "integer", desc: "Maximum number of lines to return", required: false
+
+        def execute(path:, offset: nil, limit: nil, **)
+          resolved = File.expand_path(path, Dir.pwd)
+          return "Error: file not found: #{path}" unless File.file?(resolved)
+
+          lines = File.readlines(resolved)
+          slice = select_lines(lines, offset, limit)
+          render(slice, lines.size, offset)
+        rescue SystemCallError => e
+          "Error reading #{path}: #{e.message}"
+        end
+
+        # @return [Array<String>] the chosen lines, capped at MAX_LINES
+        def select_lines(lines, offset, limit)
+          start = offset ? [offset.to_i - 1, 0].max : 0
+          count = limit ? limit.to_i : MAX_LINES
+          lines[start, [count, MAX_LINES].min] || []
+        end
+
+        private
+
+        def render(slice, total, offset)
+          body = slice.join
+          start = offset ? offset.to_i : 1
+          shown = slice.size
+          return "(empty file)" if total.zero?
+
+          if start + shown - 1 < total
+            "#{body}\n[truncated: showed #{shown} of #{total} lines starting at #{start}; " \
+              "use offset/limit to read more]"
+          else
+            body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/tools/request_decision.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Tools
+      # Tool the robot calls to escalate a choice it should NOT make on its own.
+      #
+      # Instead of blocking on a human (impossible in an unattended loop), the
+      # robot records the decision as an artifact — situation, options, and its
+      # recommended lean — and keeps going or stops. The orchestrator persists
+      # each captured request as a decision file; a human resolves it out-of-band.
+      #
+      # Create a fresh instance per iteration. After robot.run() returns, read
+      # captured_requests (empty if the robot raised none).
+      class RequestDecision < RobotLab::Tool
+        description <<~DESC
+          Record a decision that requires HUMAN judgment and must not be made
+          autonomously — an irreversible or hard-to-reverse choice, a public
+          contract, an ambiguity about intent, or something outside the stated
+          objective. Always include your recommended option (your "lean").
+
+          This does NOT block for an answer. If blocking is true, the run pauses
+          after this iteration until a human resolves the decision; if false,
+          keep making progress on other work you can safely do. Do NOT use this
+          for routine engineering choices you are equipped to make yourself.
+        DESC
+
+        param :question, type: "string",
+                         desc: "The decision that needs a human answer, phrased as a question"
+
+        param :situation, type: "string",
+                          desc: "Why this needs a human and what is at stake", required: false
+
+        param :options, type: "array",
+                        desc: "The distinct options you see (strings)", required: false
+
+        param :recommendation, type: "string",
+                               desc: "Your recommended option and the reasoning behind it", required: false
+
+        param :blocking, type: "boolean",
+                         desc: "true if work cannot correctly proceed until this is answered", required: false
+
+        def captured_requests
+          @captured_requests ||= []
+        end
+
+        def execute(question:, situation: "", options: [], recommendation: "", blocking: false, **)
+          (@captured_requests ||= []) << {
+            question: question,
+            situation: situation.to_s,
+            options: Array(options),
+            recommendation: recommendation.to_s,
+            blocking: blocking ? true : false
+          }
+
+          if blocking
+            "Decision recorded (BLOCKING). Stop work now and call submit_iteration_result; " \
+              "the run will pause until a human resolves it."
+          else
+            "Decision recorded. Continue with other work you can safely do, then submit your result."
+          end
+        end
+      end
+    end
+  end
+end