robot_lab-to 0.2.6

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Tools
+      # Tool the robot MUST call as its final action to declare the iteration result.
+      #
+      # Create a fresh instance per iteration. After robot.run() returns, read
+      # captured_result (nil if the robot never called the tool).
+      class SubmitResult < RobotLab::Tool
+        description <<~DESC
+          Submit the result of this iteration. You MUST call this tool as your
+          FINAL action before finishing. Do not call it until your work is complete.
+        DESC
+
+        param :success, type: "boolean",
+                        desc: "true if you made meaningful progress toward the objective; " \
+                              "false if you made no meaningful changes AND have no new learnings"
+
+        param :summary, type: "string",
+                        desc: "Brief one-sentence description of what you accomplished or why you stopped"
+
+        param :key_changes, type: "array",
+                            desc: "List of files or changes made this iteration (empty if none)",
+                            required: false
+
+        param :key_learnings, type: "array",
+                              desc: "Insights worth remembering for future iterations (empty if none)",
+                              required: false
+
+        param :should_fully_stop, type: "boolean",
+                                  desc: "Set to true only when instructed by a stop condition",
+                                  required: false
+
+        attr_reader :captured_result
+
+        def execute(success:, summary:, key_changes: [], key_learnings: [], should_fully_stop: nil, **)
+          @captured_result = IterationResult.new(
+            success: success,
+            summary: summary,
+            key_changes: Array(key_changes),
+            key_learnings: Array(key_learnings),
+            should_fully_stop: should_fully_stop
+          )
+          "Iteration complete. Stop all work now."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RobotLab
+  module To
+    module Tools
+      # Create a NEW file with the given contents. Parent directories are
+      # created as needed. The WriteGuard refuses this on files that already
+      # exist (use Edit instead) — small models otherwise rewrite whole files
+      # and destroy content.
+      class Write < FileTool
+        description <<~DESC
+          Create a new file with the given content. Use this only for files that
+          do not exist yet; to change an existing file, use Edit.
+        DESC
+
+        param :path, type: "string", desc: "Path of the file to create"
+        param :content, type: "string", desc: "Full text content to write"
+
+        def execute(path:, content:, **)
+          resolved = File.expand_path(path, Dir.pwd)
+          FileUtils.mkdir_p(File.dirname(resolved))
+          File.write(resolved, content.to_s)
+          "Wrote #{content.to_s.lines.size} lines to #{path}"
+        rescue SystemCallError => e
+          "Error writing #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/verifier.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module RobotLab
+  module To
+    # Runs an independent verification command (e.g. the test suite) to confirm
+    # a robot's self-reported success before the orchestrator commits.
+    #
+    # This is the single-robot translation of separation-of-duties: the deciding
+    # authority is a real command run by the orchestrator, not the robot, so the
+    # robot cannot self-certify a passing verdict. A non-zero exit -- or a
+    # timeout -- fails the gate.
+    class Verifier
+      MAX_OUTPUT = 4_000
+
+      Result = Data.define(:passed, :output) do
+        def passed? = passed
+      end
+
+      def initialize(command, work_dir: Dir.pwd, timeout: 600)
+        @command  = command
+        @work_dir = work_dir
+        @timeout  = timeout
+      end
+
+      def run
+        output, ok = capture
+        Result.new(passed: ok, output: clamp(output))
+      end
+
+      private
+
+      def capture
+        # pgroup: true so a timeout can kill the whole process tree (test
+        # runners spawn children), not just the shell.
+        Open3.popen2e(@command, chdir: @work_dir, pgroup: true) do |stdin, out, wait|
+          stdin.close
+          collected = +""
+          begin
+            Timeout.timeout(@timeout) { collected << out.read }
+          rescue Timeout::Error
+            terminate(wait.pid)
+            return ["#{collected}\n[verification timed out after #{@timeout}s]", false]
+          end
+          [collected, wait.value.success?]
+        end
+      end
+
+      def terminate(pid)
+        Process.kill("-TERM", Process.getpgid(pid))
+      rescue StandardError
+        nil
+      end
+
+      def clamp(text)
+        t = text.to_s.strip
+        t.length > MAX_OUTPUT ? "#{t[0, MAX_OUTPUT]}\n[output truncated]" : t
+      end
+    end
+  end
+end

data/lib/robot_lab/to/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    VERSION = "0.2.6"
+  end
+end

data/lib/robot_lab/to.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "to/version"
+require_relative "to/errors"
+require_relative "to/iteration_result"
+require_relative "to/run"
+require_relative "to/atomic_file"
+require_relative "to/jsonl_logger"
+require_relative "to/notes_manager"
+require_relative "to/decision"
+require_relative "to/decision_manager"
+require_relative "to/commit_manager"
+require_relative "to/verifier"
+require_relative "to/evals/score"
+require_relative "to/evals/context"
+require_relative "to/evals/base"
+require_relative "to/evals/null"
+require_relative "to/evals/code"
+require_relative "to/evals/prose"
+require_relative "to/evals/factory"
+require_relative "to/config"
+require_relative "to/tools/submit_result"
+require_relative "to/tools/request_decision"
+require_relative "to/tools/file_tool"
+require_relative "to/tools/read"
+require_relative "to/tools/write"
+require_relative "to/tools/edit"
+require_relative "to/tools/bash"
+require_relative "to/guards"
+require_relative "to/prompt_builder"
+require_relative "to/backoff"
+require_relative "to/stop_conditions"
+require_relative "to/orchestrator"
+require_relative "to/exit_summary"
+require_relative "to/cli"
+
+module RobotLab
+  module To
+    class << self
+      # Launch an autonomous takeover run.
+      #
+      # @param objective [String] what the robot should work toward
+      # @param opts [Hash] configuration overrides (model:, max_iterations:, etc.)
+      # @return [void]
+      def run(objective, **)
+        config = Config.new(**)
+        suppress_llm_logging unless config.debug?
+        Orchestrator.new(objective, config).run
+      end
+
+      # Resume a paused run by id (used for cron/exit-mode operation). The
+      # objective and prior state are loaded from the run's run.json.
+      def resume(run_id, **)
+        config = Config.new(**)
+        suppress_llm_logging unless config.debug?
+        Orchestrator.new(nil, config, resume_run_id: run_id).run
+      end
+
+      # Registry of named Eval strategies (see RobotLab::To::Evals.build). The
+      # block receives the Config and returns an object responding to #score.
+      def evals = (@evals ||= {})
+
+      def register_eval(name, &block)
+        evals[name.to_sym] = block
+      end
+
+      private
+
+      def suppress_llm_logging
+        require "logger"
+        null = Logger.new(File::NULL)
+        RubyLLM.configure { |c| c.logger = null } if defined?(RubyLLM)
+        RobotLab.configure { |c| c.logger = null } if RobotLab.respond_to?(:configure)
+      end
+    end
+  end
+end
+
+if defined?(RobotLab) && RobotLab.respond_to?(:register_extension)
+  RobotLab.register_extension(:to, RobotLab::To)
+end

data/mkdocs.yml

@@ -0,0 +1,145 @@
+# MkDocs configuration for robot_lab-to documentation
+site_name: robot_lab-to
+site_description: Autonomous overnight agent loop for RobotLab — run a robot while you sleep.
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/robot_lab-to
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+# Repository information
+repo_name: MadBomber/robot_lab-to
+repo_url: https://github.com/MadBomber/robot_lab-to
+edit_uri: edit/main/docs/
+
+# Theme
+theme:
+  name: material
+
+  # Color scheme — default to dark (slate); toggle to light
+  palette:
+    # Dark mode (default)
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+    # Light mode
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    # Navigation
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.top
+    # Table of contents
+    - toc.follow
+    # Search
+    - search.suggest
+    - search.highlight
+    - search.share
+    # Content
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+# Markdown extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: robot_lab-to
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/robot_lab-to
+      name: robot_lab-to on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/robot_lab-to
+      name: robot_lab-to on RubyGems
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+      - Anatomy of a Run: getting-started/anatomy-of-a-run.md
+  - Core Concepts:
+      - The Iteration Loop: concepts/iteration-loop.md
+      - Cross-Iteration Memory: concepts/notes.md
+      - Stop Conditions: concepts/stop-conditions.md
+      - Verification Gate: concepts/verification.md
+      - "Evals: Scoring Iterations": concepts/evals.md
+      - Run State & Event Log: concepts/run-state.md
+  - Configuration:
+      - Overview: configuration/index.md
+      - Settings Reference: configuration/settings.md
+      - CLI Reference: configuration/cli.md
+  - Local Models:
+      - Overview: local-models/index.md
+      - Ollama Setup: local-models/ollama.md
+      - Built-in Tools: local-models/tools.md
+      - Guardrails: local-models/guardrails.md
+  - Reference:
+      - Architecture: reference/architecture.md
+  - About:
+      - Changelog: about/changelog.md

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: robot_lab-to
+version: !ruby/object:Gem::Version
+  version: 0.2.6
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: robot_lab
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: myway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  robot_lab-to ("takeover") runs a robot_lab Robot in an autonomous loop, committing
+  one focused change per iteration toward a stated objective. Each iteration the robot
+  reads shared notes (notes.md), does work, then calls submit_iteration_result to
+  report success or failure. The orchestrator commits good iterations, rolls back
+  failures, and appends to the notes log for cross-iteration memory. Stop conditions
+  include max iterations, max tokens, consecutive failure threshold, and a natural-
+  language --stop-when condition. Runs overnight; review the branch in the morning.
+email:
+- dvanhoozer@gmail.com
+executables:
+- robot-to
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- COMMITS.md
+- README.md
+- Rakefile
+- bin/robot-to
+- docs/about/changelog.md
+- docs/assets/architecture.svg
+- docs/assets/images/robot_lab-to.jpg
+- docs/assets/iteration-loop.svg
+- docs/concepts/evals.md
+- docs/concepts/iteration-loop.md
+- docs/concepts/notes.md
+- docs/concepts/run-state.md
+- docs/concepts/stop-conditions.md
+- docs/concepts/verification.md
+- docs/configuration/cli.md
+- docs/configuration/index.md
+- docs/configuration/settings.md
+- docs/getting-started/anatomy-of-a-run.md
+- docs/getting-started/installation.md
+- docs/getting-started/quick-start.md
+- docs/index.md
+- docs/local-models/guardrails.md
+- docs/local-models/index.md
+- docs/local-models/ollama.md
+- docs/local-models/tools.md
+- docs/reference/architecture.md
+- examples/01_basic_usage/.gitignore
+- examples/01_basic_usage/README.md
+- examples/01_basic_usage/basic_usage.rb
+- examples/02_advanced_usage/.gitignore
+- examples/02_advanced_usage/README.md
+- examples/02_advanced_usage/advanced_usage.rb
+- examples/02_advanced_usage/quality_gate.rb
+- examples/03_scored/.gitignore
+- examples/03_scored/README.md
+- examples/03_scored/scored_run.rb
+- examples/04_prose/.gitignore
+- examples/04_prose/README.md
+- examples/04_prose/prompts_dir/grade_message.md
+- examples/04_prose/prompts_dir/judge.md
+- examples/04_prose/prompts_dir/outline_criteria.md
+- examples/04_prose/prompts_dir/outline_objective.md
+- examples/04_prose/prompts_dir/section_criteria.md
+- examples/04_prose/prompts_dir/sections_objective.md
+- examples/04_prose/prose_run.rb
+- lib/robot_lab/to.rb
+- lib/robot_lab/to/atomic_file.rb
+- lib/robot_lab/to/backoff.rb
+- lib/robot_lab/to/cli.rb
+- lib/robot_lab/to/commit_manager.rb
+- lib/robot_lab/to/config.rb
+- lib/robot_lab/to/config/defaults.yml
+- lib/robot_lab/to/decision.rb
+- lib/robot_lab/to/decision_manager.rb
+- lib/robot_lab/to/errors.rb
+- lib/robot_lab/to/evals/base.rb
+- lib/robot_lab/to/evals/code.rb
+- lib/robot_lab/to/evals/context.rb
+- lib/robot_lab/to/evals/factory.rb
+- lib/robot_lab/to/evals/null.rb
+- lib/robot_lab/to/evals/prose.rb
+- lib/robot_lab/to/evals/score.rb
+- lib/robot_lab/to/exit_summary.rb
+- lib/robot_lab/to/guards.rb
+- lib/robot_lab/to/guards/checkpoint.rb
+- lib/robot_lab/to/guards/grader_lock.rb
+- lib/robot_lab/to/guards/path_resolution.rb
+- lib/robot_lab/to/guards/quality_monitor.rb
+- lib/robot_lab/to/guards/read_before_edit.rb
+- lib/robot_lab/to/guards/run_store.rb
+- lib/robot_lab/to/guards/write_guard.rb
+- lib/robot_lab/to/iteration_result.rb
+- lib/robot_lab/to/jsonl_logger.rb
+- lib/robot_lab/to/notes_manager.rb
+- lib/robot_lab/to/orchestrator.rb
+- lib/robot_lab/to/prompt_builder.rb
+- lib/robot_lab/to/run.rb
+- lib/robot_lab/to/stop_conditions.rb
+- lib/robot_lab/to/tools/bash.rb
+- lib/robot_lab/to/tools/edit.rb
+- lib/robot_lab/to/tools/file_tool.rb
+- lib/robot_lab/to/tools/read.rb
+- lib/robot_lab/to/tools/request_decision.rb
+- lib/robot_lab/to/tools/submit_result.rb
+- lib/robot_lab/to/tools/write.rb
+- lib/robot_lab/to/verifier.rb
+- lib/robot_lab/to/version.rb
+- mkdocs.yml
+homepage: https://github.com/MadBomber/robot_lab-to
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/robot_lab-to
+  source_code_uri: https://github.com/MadBomber/robot_lab-to
+  changelog_uri: https://github.com/MadBomber/robot_lab-to/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Autonomous overnight agent loop for RobotLab — run robots while you sleep.
+test_files: []