robot_lab-to 0.2.6

data/lib/robot_lab/to/guards/read_before_edit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "path_resolution"
+require_relative "run_store"
+
+module RobotLab
+  module To
+    module Guards
+      # Read-before-edit invariant, ported from little-coder read-guard-edit.
+      #
+      # Small models fire Edit with an oldText they never actually saw, guessing
+      # the file's contents — which either fails the exact-match (wasted turn) or
+      # matches the wrong span (silent corruption). We block any Edit whose
+      # target wasn't Read this run.
+      #
+      # The read-set spans many tool calls within one run, so it lives in the
+      # per-run RunStore (see that file for why ctx.local can't hold it). A
+      # successful Read, Edit, or Write marks the path as known.
+      class ReadBeforeEdit < RobotLab::Hook
+        self.namespace = :read_before_edit
+
+        KEY = :robot_lab_to_read_files
+        TRACKED_READS = %w[read edit write].freeze
+
+        class << self
+          # Fresh run = clean slate; a prior iteration's reads say nothing here.
+          def before_run(_ctx)
+            RunStore.reset(KEY, [])
+          end
+
+          # Record successful reads/authored files as "known".
+          def after_tool_call(ctx)
+            return if ctx.tool_error
+            return unless TRACKED_READS.include?(ctx.tool_name.to_s.downcase)
+
+            path = PathResolution.resolve(ctx.tool_args)
+            mark_read(path) if path
+          end
+
+          # Block edits to files that were never read.
+          def around_tool_call(ctx)
+            return yield unless ctx.tool_name.to_s.casecmp?("edit")
+
+            path = PathResolution.resolve(ctx.tool_args)
+            if path && !read?(path)
+              ctx.tool_result = edit_before_read_reason(path)
+              return ctx.tool_result
+            end
+
+            yield
+          end
+
+          # @return [Boolean] whether `path` has been read this run
+          def read?(path)
+            read_files.include?(path)
+          end
+
+          def mark_read(path)
+            files = read_files
+            files << path unless files.include?(path)
+          end
+
+          # @return [Array<String>] the per-run read-set (live reference)
+          def read_files
+            RunStore.fetch(KEY, [])
+          end
+
+          # @param resolved [String]
+          # @return [String]
+          def edit_before_read_reason(resolved)
+            <<~MSG
+              File must be read before edit — #{resolved} has not been read in
+              this session. Read #{resolved} first to get the exact current text
+              for oldText (whitespace and indentation must match exactly), then
+              issue the Edit. Include 2-3 surrounding lines so oldText is unique.
+              Do NOT guess the file's contents.
+            MSG
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/guards/run_store.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Guards
+      # Per-run shared state for the guards.
+      #
+      # RobotLab creates a fresh tool-call HookContext per call with its own
+      # ExtensionState, so cross-call guard state (the read-set, checkpoint-set,
+      # loop tracker) cannot live in ctx.local. robot_lab-to runs each iteration
+      # in its own thread (Orchestrator#run_robot_with_interrupt), so a
+      # thread-local is a clean per-run scope — the same idiom robot_lab-audit
+      # uses for run ids. before_run resets it; the thread ends with the
+      # iteration, so nothing leaks across runs.
+      module RunStore
+        module_function
+
+        # Set/replace the value for `key`.
+        def reset(key, value)
+          Thread.current[key] = value
+        end
+
+        # Fetch the value for `key`, initializing to `default` when unset.
+        def fetch(key, default = nil)
+          Thread.current[key] = default if Thread.current[key].nil? && !default.nil?
+          Thread.current[key]
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/guards/write_guard.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "path_resolution"
+
+module RobotLab
+  module To
+    module Guards
+      # Refuses Write on a file that already exists, redirecting the model to
+      # Edit, and normalizes root-bare paths to cwd. Ported from little-coder
+      # write-guard: small models rewrite whole files and destroy content; the
+      # whitepaper notes this refusal fires on ~57% of Polyglot exercises.
+      #
+      # Tool names matched (case-insensitive): "write".
+      class WriteGuard < RobotLab::Hook
+        self.namespace = :write_guard
+
+        WRITE_TOOLS = %w[write].freeze
+
+        class << self
+          # Normalize the path in place before the tool runs (applies even when
+          # we don't block — e.g. the "/foo.md" -> cwd rewrite).
+          def before_tool_call(ctx)
+            return unless write_tool?(ctx.tool_name)
+
+            args = ctx.tool_args
+            resolved = PathResolution.resolve(args)
+            return unless resolved
+
+            key = PathResolution::PATH_KEYS.find { |k| args.key?(k) || args.key?(k.to_sym) }
+            args[key] = resolved if key
+          end
+
+          # Block the write when the target already exists.
+          def around_tool_call(ctx)
+            unless write_tool?(ctx.tool_name)
+              return yield
+            end
+
+            resolved = PathResolution.resolve(ctx.tool_args)
+            if resolved && File.exist?(resolved)
+              ctx.tool_result = edit_recipe(resolved)
+              return ctx.tool_result
+            end
+
+            yield
+          end
+
+          # @param tool_name [String]
+          # @return [Boolean]
+          def write_tool?(tool_name)
+            WRITE_TOOLS.include?(tool_name.to_s.downcase)
+          end
+
+          # The message returned to the model in place of the refused write.
+          #
+          # @param resolved [String]
+          # @return [String]
+          def edit_recipe(resolved)
+            <<~MSG
+              Write refused — #{resolved} already exists. Write is for creating
+              NEW files only. To change an existing file, Read it first to get the
+              exact current text, then use Edit with that text as oldText
+              (whitespace and indentation must match). Do NOT retry Write; it will
+              be refused again.
+            MSG
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/guards.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "guards/run_store"
+require_relative "guards/path_resolution"
+require_relative "guards/write_guard"
+require_relative "guards/read_before_edit"
+require_relative "guards/checkpoint"
+require_relative "guards/quality_monitor"
+require_relative "guards/grader_lock"
+
+module RobotLab
+  module To
+    # Small-model guardrails ported from little-coder (Apache-2.0).
+    #
+    # These RobotLab::Hook subclasses make file/bash tools safe for a small
+    # *local* model driving an autonomous robot_lab-to loop. They are no-ops
+    # for a frontier model, so registration is opt-in.
+    #
+    # Wire them onto a per-iteration robot in Orchestrator#build_robot:
+    #
+    #   robot = RobotLab.build(...)
+    #   RobotLab::To::Guards.install(robot, run: @run) if @config.local_guards
+    #   robot
+    #
+    # Each guard is single-purpose and independently testable: its class methods
+    # take a HookContext and have no hidden global state beyond a per-robot store
+    # that is reset on before_run.
+    module Guards
+      ALL = [
+        Guards::WriteGuard,
+        Guards::ReadBeforeEdit,
+        Guards::Checkpoint,
+        Guards::QualityMonitor
+      ].freeze
+
+      # Register every guard on a robot.
+      #
+      # @param robot [RobotLab::Robot]
+      # @param run [RobotLab::To::Run, nil] supplies run_dir for checkpoints
+      # @return [RobotLab::Robot] the same robot, for chaining
+      # `except:` lists guard classes to skip. Passing [WriteGuard] lets a robot
+      # overwrite existing files (WriteGuard otherwise refuses Write on an existing
+      # file and redirects to Edit -- unhelpful for iterative prose that rewrites a
+      # draft).
+      def self.install(robot, run: nil, except: [])
+        active = ALL - Array(except)
+        robot.on(Guards::Checkpoint, context: { run: run }) if run
+        (active - [Guards::Checkpoint]).each { |guard| robot.on(guard) }
+        robot.on(Guards::Checkpoint) unless run
+        robot
+      end
+    end
+  end
+end

data/lib/robot_lab/to/iteration_result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    IterationResult = Data.define(
+      :success,           # Boolean
+      :summary,           # String
+      :key_changes,       # Array<String>
+      :key_learnings,     # Array<String>
+      :should_fully_stop  # Boolean or nil (nil when --stop-when not active)
+    ) do
+      def success? = success
+      def stop?    = !!should_fully_stop
+
+      # Used when --stop-when is not configured
+      def self.no_stop_when(success:, summary:, key_changes: [], key_learnings: [])
+        new(success: success, summary: summary,
+            key_changes: key_changes, key_learnings: key_learnings,
+            should_fully_stop: nil)
+      end
+
+      # Sentinel result when the robot returns without calling submit_iteration_result
+      def self.not_submitted
+        new(success: false, summary: "Robot did not call submit_iteration_result",
+            key_changes: [], key_learnings: [], should_fully_stop: nil)
+      end
+    end
+  end
+end

data/lib/robot_lab/to/jsonl_logger.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RobotLab
+  module To
+    # Writes structured JSONL events to the run log file.
+    #
+    # Events emitted before the log file is ready are buffered in memory
+    # and flushed on first open (capacity: 100 lines).
+    class JsonlLogger
+      MAX_BUFFER = 100
+
+      def initialize
+        @path   = nil
+        @buffer = []
+        @file   = nil
+      end
+
+      def open(path)
+        @path = path
+        @file = File.open(path, "a")
+        @file.sync = true
+        flush_buffer
+      end
+
+      def log(event, **payload)
+        entry = { event: event, ts: Time.now.iso8601(3) }.merge(payload).compact
+        line  = JSON.generate(entry)
+        if @file
+          @file.write("#{line}\n") # single write keeps the line intact on crash
+        else
+          @buffer.shift if @buffer.size >= MAX_BUFFER
+          @buffer << line
+        end
+      end
+
+      def close
+        if @file
+          @file.flush
+          begin
+            @file.fsync
+          rescue SystemCallError
+            nil
+          end
+          @file.close
+        end
+        @file = nil
+      end
+
+      private
+
+      def flush_buffer
+        @buffer.each { |line| @file.write("#{line}\n") }
+        @buffer.clear
+      end
+    end
+  end
+end

data/lib/robot_lab/to/notes_manager.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    # Manages the cross-iteration notes file (notes.md).
+    #
+    # Written by the orchestrator only. The robot reads it at the start of every
+    # iteration to understand prior work.
+    class NotesManager
+      attr_reader :path
+
+      def initialize(path)
+        @path = Pathname.new(path)
+      end
+
+      def setup(run)
+        AtomicFile.write(@path, <<~HEADER)
+          # robot-to run: #{run.run_id}
+
+          Objective: #{run.objective}
+
+          ## Iteration Log
+        HEADER
+      end
+
+      def read
+        @path.exist? ? @path.read : ""
+      end
+
+      def append_success(result, iteration)
+        changes_md = bullet_list(result.key_changes)
+        learnings_md = bullet_list(result.key_learnings)
+        append(<<~MD)
+
+          ### Iteration #{iteration}
+
+          **Summary:** #{result.summary}
+
+          **Changes:**
+          #{changes_md}
+          **Learnings:**
+          #{learnings_md}
+        MD
+      end
+
+      def append_failure(result, iteration)
+        learnings_md = bullet_list(result.key_learnings)
+        append(<<~MD)
+
+          ### Iteration #{iteration} [FAIL]
+
+          **Summary:** #{result.summary}
+
+          **Learnings:**
+          #{learnings_md}
+        MD
+      end
+
+      def append_no_improvement(result, detail, iteration)
+        append(<<~MD)
+
+          ### Iteration #{iteration} [NO IMPROVEMENT]
+
+          **Summary:** #{result.summary}
+
+          **Score:** #{detail}
+
+          The change passed the gate but did not beat the parent commit, so it was
+          rolled back. Try a different approach next iteration.
+        MD
+      end
+
+      def append_verify_failure(result, output, iteration)
+        append(<<~MD)
+
+          ### Iteration #{iteration} [VERIFY FAILED]
+
+          **Summary:** #{result.summary}
+
+          **Verification output:**
+          ```
+          #{output}
+          ```
+        MD
+      end
+
+      def append_error(error, iteration)
+        append(<<~MD)
+
+          ### Iteration #{iteration} [ERROR]
+
+          **Error:** #{error.class}: #{error.message}
+        MD
+      end
+
+      def append_decision(decision, iteration)
+        append(<<~MD)
+
+          ### Iteration #{iteration} [DECISION]
+
+          **Raised:** #{decision.question}
+          **Blocking:** #{decision.blocking? ? "yes" : "no"}
+          **Recommendation:** #{decision.recommendation}
+          **File:** #{decision.path}
+        MD
+      end
+
+      private
+
+      def append(text)
+        AtomicFile.append(@path, text)
+      end
+
+      def bullet_list(items)
+        return "- (none)\n" if items.nil? || items.empty?
+
+        items.map { |i| "- #{i}" }.join("\n") + "\n"
+      end
+    end
+  end
+end