robot_lab-to 0.2.7 → 0.3.0

data/lib/robot_lab/to/orchestrator.rb

@@ -14,6 +14,17 @@ module RobotLab
     # not make alone, it is written to a decision file (see DecisionManager). A
     # blocking decision either pauses the loop (decision_mode: wait) or stops the
     # run for a later `--resume` (decision_mode: exit).
+    #
+    # :reek:TooManyMethods :reek:TooManyInstanceVariables -- this is the
+    # single object that owns the whole iteration lifecycle (setup, agent
+    # turn, eval gate, commit/rollback, decisions, tokens, signals). Splitting
+    # it apart would scatter state (@run, @git, @pending_commit_failure,
+    # @stop_requested, ...) across collaborators that would just pass it back
+    # and forth -- see the "Architecture" section of CLAUDE.md.
+    # :reek:RepeatedConditional -- @stop_requested, @pending_commit_failure,
+    # and decisions_enabled? are real orchestrator-wide state, legitimately
+    # checked at each point that must react to it; that is what a run loop's
+    # flags are for, not a sign the checks belong on another object.
     class Orchestrator
       SIGNAL_STOP = "graceful_stop"
 
@@ -43,10 +54,17 @@ module RobotLab
         @decisions              = nil
         @decision_tool          = nil
         @injected_decisions     = []
+        @backoff                = nil
+        @builder                = nil
+        @notes                  = nil
+        @stop_conditions        = nil
         @accounted_in           = 0
         @accounted_out          = 0
       end
 
+      # :reek:TooManyStatements -- top-level run/rescue/ensure sequence for the
+      # whole process; the rescue branches are already split into their own
+      # error-shaped clauses.
       def run
         @resume_run_id ? setup_resume : setup_run
         install_signal_handlers
@@ -64,15 +82,18 @@ module RobotLab
         @git&.reset_hard unless @pending_commit_failure
         @logger.log("orchestrator:abort", reason: @abort_reason, permanent: true)
       rescue => e
-        @abort_reason = "fatal: #{e.message}"
+        message = e.message
+        @abort_reason = "fatal: #{message}"
         @git&.reset_hard unless @pending_commit_failure
-        @logger.log("orchestrator:fatal", error: e.class.to_s, message: e.message)
+        @logger.log("orchestrator:fatal", error: e.class.to_s, message: message)
       ensure
         finalize_run
       end
 
       private
 
+      # :reek:TooManyStatements -- the loop body is the iteration lifecycle in
+      # its literal execution order; splitting it further would hide that order.
       def main_loop
         loop do
           break if @stop_requested
@@ -83,8 +104,9 @@ module RobotLab
           @stop_conditions.before?
 
           @run.iteration += 1
-          @logger.log("iteration:start", iteration: @run.iteration)
-          progress "iteration #{@run.iteration} (#{@config.model})..."
+          iteration = @run.iteration
+          @logger.log("iteration:start", iteration: iteration)
+          progress "iteration #{iteration} (#{@config.model})..."
 
           result = execute_iteration
 
@@ -114,6 +136,8 @@ module RobotLab
         end
       end
 
+      # :reek:TooManyStatements -- one-time run bootstrap, each step required
+      # in this order (branch, run dir, Run record, logger, notes, collaborators).
       def setup_run
         @git = CommitManager.new
         ensure_head!
@@ -143,6 +167,8 @@ module RobotLab
 
       # Resume a prior run from its run.json — enables external scheduling (cron):
       # each tick re-enters the loop on the same branch and advances or re-pauses.
+      # :reek:TooManyStatements -- mirrors #setup_run's bootstrap order for the
+      # resume path.
       def setup_resume
         @git = CommitManager.new
         ensure_head!
@@ -152,7 +178,8 @@ module RobotLab
 
         @run       = Run.load(state_path)
         @objective = @run.objective
-        @git.checkout_branch(@run.branch)
+        branch     = @run.branch
+        @git.checkout_branch(branch)
 
         @logger.open(@run.log_path)
         @notes = NotesManager.new(@run.notes_path)  # append — do NOT re-setup (would clobber history)
@@ -160,8 +187,8 @@ module RobotLab
         build_collaborators
 
         @logger.log("orchestrator:resume", run_id: @run.run_id, iteration: @run.iteration,
-                                           branch: @run.branch, model: @config.model)
-        progress "resumed run #{@run.run_id} at iteration #{@run.iteration} → branch #{@run.branch}"
+                                           branch: branch, model: @config.model)
+        progress "resumed run #{@run.run_id} at iteration #{@run.iteration} → branch #{branch}"
       end
 
       # Shared setup used by both a fresh run and a resume.
@@ -202,11 +229,14 @@ module RobotLab
 
       # Poll the decision files until every blocking decision is resolved, the run
       # is signaled to stop, or decision_timeout elapses.
+      # :reek:TooManyStatements -- the three exit conditions (stopped, resolved,
+      # timed out) must all be checked inside one poll loop.
       def wait_for_decisions(pending)
         progress "awaiting human decision on #{pending.size} item(s):"
         pending.each { |d| progress "  #{d.path}" }
         @logger.log("decision:wait:start", count: pending.size)
-        deadline = @config.decision_timeout ? monotonic + @config.decision_timeout.to_i : nil
+        timeout  = @config.decision_timeout
+        deadline = timeout ? monotonic + timeout.to_i : nil
 
         loop do
           return if @stop_requested
@@ -216,7 +246,7 @@ module RobotLab
           break unless @decisions.blocking_pending?
 
           if deadline && monotonic >= deadline
-            raise AbortError, "awaiting human decision (timed out after #{@config.decision_timeout}s)"
+            raise AbortError, "awaiting human decision (timed out after #{timeout}s)"
           end
         end
 
@@ -238,6 +268,8 @@ module RobotLab
 
       # The happy path: build a fresh robot, run it, and return its submitted
       # result (or a not-submitted marker).
+      # :reek:TooManyStatements -- one call per lifecycle step (reset counters,
+      # build prompt/robot, run, nudge, persist decisions, return result).
       def run_agent_iteration
         @accounted_in = @accounted_out = 0
         @submit_tool   = Tools::SubmitResult.new
@@ -265,12 +297,13 @@ module RobotLab
       def persist_raised_decisions
         return unless @decision_tool
 
+        iteration = @run.iteration
         @decision_tool.captured_requests.each do |req|
-          decision = @decisions.record(**req, iteration: @run.iteration)
-          @notes.append_decision(decision, @run.iteration)
+          decision = @decisions.record(**req, iteration: iteration)
+          @notes.append_decision(decision, iteration)
           @logger.log("decision:raised", id: decision.id, blocking: decision.blocking,
                                           question: decision.question)
-          progress "iteration #{@run.iteration} raised decision: #{decision.question}"
+          progress "iteration #{iteration} raised decision: #{decision.question}"
         end
       end
 
@@ -298,10 +331,11 @@ module RobotLab
       # True when the iteration should be retried — within the retry budget and
       # not stopping. Sleeps out the backoff as a side effect before returning.
       def retry_after_backoff?
-        return false unless @run.consecutive_errors <= @config.max_retries && !@stop_requested
+        errors = @run.consecutive_errors
+        return false unless errors <= @config.max_retries && !@stop_requested
 
-        @logger.log("backoff:start", consecutive_errors: @run.consecutive_errors)
-        @backoff.sleep_for(@run.consecutive_errors)
+        @logger.log("backoff:start", consecutive_errors: errors)
+        @backoff.sleep_for(errors)
         @logger.log("backoff:end")
         true
       end
@@ -367,8 +401,9 @@ module RobotLab
 
       def handle_no_improvement(result, score)
         iteration = @run.iteration
+        detail    = score.detail
         @git.reset_hard unless @pending_commit_failure
-        @notes.append_no_improvement(result, score.detail, iteration)
+        @notes.append_no_improvement(result, detail, iteration)
         # A non-improving iteration is valid work that just wasn't better -- NOT a
         # failure. It counts toward the plateau (diminishing-returns) stop only, so
         # it must NOT trip max_consecutive_failures, which is for the robot being
@@ -377,8 +412,8 @@ module RobotLab
         # verdicts are common and normal.
         @run.iterations_since_improvement += 1
         @run.consecutive_errors = 0
-        @logger.log("iteration:no_improvement", iteration: iteration, detail: score.detail)
-        progress "iteration #{iteration} no improvement (#{score.detail}) — rolled back"
+        @logger.log("iteration:no_improvement", iteration: iteration, detail: detail)
+        progress "iteration #{iteration} no improvement (#{detail}) — rolled back"
       end
 
       # A resolved decision that was injected into this successful iteration has
@@ -405,14 +440,16 @@ module RobotLab
         score
       end
 
+      # :reek:TooManyStatements -- rollback + record + report, one statement each.
       def handle_gate_failure(result, score)
+        iteration = @run.iteration
         @git.reset_hard unless @pending_commit_failure
-        @notes.append_verify_failure(result, score.output.to_s, @run.iteration)
+        @notes.append_verify_failure(result, score.output.to_s, iteration)
         @run.consecutive_failures += 1
         @run.consecutive_errors    = 0
         @run.iterations_since_improvement += 1
-        @logger.log("iteration:gate_failure", iteration: @run.iteration)
-        progress "iteration #{@run.iteration} verification failed — rolled back"
+        @logger.log("iteration:gate_failure", iteration: iteration)
+        progress "iteration #{iteration} verification failed — rolled back"
         nil
       end
 
@@ -421,19 +458,22 @@ module RobotLab
       # the code, re-verifying after each attempt. Only fall back to a full
       # rollback once the repair budget is spent — a near-miss no longer discards
       # all the work, and nothing commits until the gate is green.
+      # :reek:TooManyStatements -- repair/re-verify loop with its own rescue;
+      # each statement is a distinct step of one repair attempt.
       def repair_until_gate(result, score)
-        budget = @config.max_verify_repairs.to_i
+        budget    = @config.max_verify_repairs.to_i
+        iteration = @run.iteration
         return [result, score] if budget.zero? || @robot.nil?
 
         budget.times do |i|
           break if @stop_requested
 
-          @logger.log("eval:repair", iteration: @run.iteration, attempt: i + 1)
-          progress "iteration #{@run.iteration}: verification failed — repairing (#{i + 1}/#{budget})"
+          @logger.log("eval:repair", iteration: iteration, attempt: i + 1)
+          progress "iteration #{iteration}: verification failed — repairing (#{i + 1}/#{budget})"
           begin
             run_robot_with_interrupt(@robot, repair_prompt(score))
           rescue StandardError => e
-            @logger.log("eval:repair_error", iteration: @run.iteration, message: e.message)
+            @logger.log("eval:repair_error", iteration: iteration, message: e.message)
             break
           end
           result = @submit_tool.captured_result || result
@@ -459,16 +499,20 @@ module RobotLab
       end
 
       def handle_failure(result)
+        iteration = @run.iteration
         @git.reset_hard unless @pending_commit_failure
-        @notes.append_failure(result, @run.iteration)
+        @notes.append_failure(result, iteration)
         @run.consecutive_failures += 1
         @run.consecutive_errors = 0
         @run.iterations_since_improvement += 1
-        @logger.log("iteration:failure", iteration: @run.iteration, summary: result.summary)
-        progress "iteration #{@run.iteration} failed: #{result.summary}"
+        @logger.log("iteration:failure", iteration: iteration, summary: result.summary)
+        progress "iteration #{iteration} failed: #{result.summary}"
       end
 
+      # :reek:TooManyStatements -- commit path plus its own CommitFailedError
+      # rescue; the two branches (success, queue-for-repair) are each tight.
       def attempt_commit(result)
+        iteration = @run.iteration
         @git.add_all
         return unless @git.staged?
 
@@ -476,16 +520,17 @@ module RobotLab
         @git.commit(message)
         @run.commits += 1
         @pending_commit_failure = nil
-        @logger.log("commit:success", iteration: @run.iteration, message: message)
-        progress "iteration #{@run.iteration} committed: #{message}"
+        @logger.log("commit:success", iteration: iteration, message: message)
+        progress "iteration #{iteration} committed: #{message}"
       rescue CommitFailedError => e
         @pending_commit_failure = e
         @run.consecutive_failures += 1
         @run.consecutive_errors = 0
-        @logger.log("commit:failed", iteration: @run.iteration, output: e.output)
-        progress "iteration #{@run.iteration} commit failed — queued for repair"
+        @logger.log("commit:failed", iteration: iteration, output: e.output)
+        progress "iteration #{iteration} commit failed — queued for repair"
       end
 
+      # :reek:FeatureEnvy -- formatting the commit message from result's own fields.
       def commit_message(result)
         if @config.commit_format == "conventional"
           type  = result.respond_to?(:type)  ? (result.type || "chore") : "chore"
@@ -552,10 +597,14 @@ module RobotLab
         tools + [Tools::Read.new, Tools::Write.new, Tools::Edit.new, Tools::Bash.new]
       end
 
+      # :reek:TooManyStatements -- the streaming callback accumulates usage and enforces the stop in one place.
       def token_tracker
         lambda do |chunk|
-          @run.input_tokens  += chunk.input_tokens.to_i
-          @run.output_tokens += chunk.output_tokens.to_i
+          # ruby_llm 2.0 nests counts under chunk.tokens (usually only on the
+          # final chunk of a stream).
+          tokens = chunk.respond_to?(:tokens) ? chunk.tokens : nil
+          @run.input_tokens  += tokens&.input.to_i
+          @run.output_tokens += tokens&.output.to_i
 
           return unless @stop_conditions.token_limit_exceeded?
 
@@ -565,6 +614,8 @@ module RobotLab
         end
       end
 
+      # :reek:TooManyStatements -- runs the robot on its own Thread so a signal
+      # can interrupt it; each statement manages that thread's lifecycle.
       def run_robot_with_interrupt(robot, task = @objective)
         thread_error = nil
         result = nil

data/lib/robot_lab/to/prompt_builder.rb

@@ -8,6 +8,8 @@ module RobotLab
         @config = config
       end
 
+      # :reek:TooManyStatements -- each line is one optional prompt section, in
+      # the exact order they appear; a data-table would hide that ordering.
       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?

data/lib/robot_lab/to/run.rb

@@ -13,6 +13,8 @@ module RobotLab
                     :commits, :input_tokens, :output_tokens,
                     :last_score_value, :iterations_since_improvement
 
+      # :reek:ControlParameter -- run_dir/decisions_path fall back to a sibling
+      # path when omitted; that's a constructor default, not a behavior branch.
       def initialize(run_id:, objective:, branch:, base_commit:, notes_path:, log_path:,
                      run_dir: nil, decisions_path: nil)
         @run_id              = run_id
@@ -38,6 +40,7 @@ module RobotLab
       def elapsed_seconds  = Time.now - started_at
       def state_path       = @run_dir.join("run.json")
 
+      # :reek:FeatureEnvy -- decomposing our own elapsed_seconds into h/m/s.
       def elapsed_human
         secs = elapsed_seconds.to_i
         h = secs / 3600
@@ -71,14 +74,11 @@ module RobotLab
                    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
+        %i[iteration consecutive_failures consecutive_errors commits input_tokens
+           output_tokens iterations_since_improvement].each do |key|
+          run.public_send(:"#{key}=", data[key].to_i)
+        end
+        run.last_score_value = data[:last_score_value]
         run.instance_variable_set(:@started_at, Time.parse(data[:started_at])) if data[:started_at]
         run
       end

data/lib/robot_lab/to/stop_conditions.rb

@@ -3,6 +3,8 @@
 module RobotLab
   module To
     # Evaluates all stop conditions against the current run state.
+    # :reek:RepeatedConditional -- each `limit` is an unrelated config value
+    # (max_iterations/max_tokens/stop_on_plateau) nil-guarded in its own check.
     class StopConditions
       def initialize(config, run)
         @config = config
@@ -38,17 +40,19 @@ module RobotLab
       private
 
       def check_max_iterations
-        return unless @config.max_iterations
-        return unless @run.iteration >= @config.max_iterations
+        limit = @config.max_iterations
+        return unless limit
+        return unless @run.iteration >= limit
 
-        raise AbortError, "max iterations reached (#{@config.max_iterations})"
+        raise AbortError, "max iterations reached (#{limit})"
       end
 
       def check_max_tokens
-        return unless @config.max_tokens
-        return unless @run.total_tokens >= @config.max_tokens
+        limit = @config.max_tokens
+        return unless limit
+        return unless @run.total_tokens >= limit
 
-        raise AbortError, "max tokens reached (#{@config.max_tokens})"
+        raise AbortError, "max tokens reached (#{limit})"
       end
 
       def check_consecutive_failures

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

@@ -17,14 +17,16 @@ module RobotLab
           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
+        parameter :command, type: "string", description: "The shell command to run"
+        parameter :timeout, type: "integer", description: "Seconds before the command is killed", required: false
 
         def initialize(robot: nil, timeout: DEFAULT_TIMEOUT)
           super(robot: robot)
           @default_timeout = timeout
         end
 
+        # :reek:ControlParameter -- falling back to the instance default when
+        # the LLM omits the optional `timeout` argument.
         def execute(command:, timeout: nil, **)
           out, status = run(command, (timeout || @default_timeout).to_i)
           format_result(out, status)
@@ -34,6 +36,9 @@ module RobotLab
         # status_string is "0".."n" for an exit code, or "timeout"/"error: ...".
         #
         # @return [Array(String, String)]
+        # :reek:TooManyStatements :reek:NestedIterators -- spawn, read
+        # concurrently, wait-or-kill, join: each step is one statement and the
+        # streaming reader inherently nests a loop inside its own Thread.
         def run(command, timeout)
           out_str = +""
           status = nil

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

@@ -14,11 +14,16 @@ module RobotLab
           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
+        parameter :path, type: "string", description: "Path of the file to edit"
+        parameter :old_text, type: "string", description: "Exact text to replace"
+        parameter :new_text, type: "string", description: "Replacement text"
+        parameter :replace_all, type: "boolean", description: "Replace every occurrence", required: false
 
+        # :reek:BooleanParameter -- replace_all is a tool param the LLM sets;
+        # the `param` declarations above fix this signature.
+        # :reek:FeatureEnvy -- inspecting #apply's own return value.
+        # :reek:TooManyStatements -- validate, transform, write, report; each
+        # step is one statement in a tool #execute contract method.
         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)

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

@@ -14,9 +14,9 @@ module RobotLab
           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
+        parameter :path, type: "string", description: "Path to the file to read"
+        parameter :offset, type: "integer", description: "1-based first line to return", required: false
+        parameter :limit, type: "integer", description: "Maximum number of lines to return", required: false
 
         def execute(path:, offset: nil, limit: nil, **)
           resolved = File.expand_path(path, Dir.pwd)

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

@@ -25,25 +25,29 @@ module RobotLab
           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"
+        parameter :question, type: "string",
+                         description: "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
+        parameter :situation, type: "string",
+                          description: "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
+        parameter :options, type: "array",
+                        description: "The distinct options you see (strings)", required: false
 
-        param :recommendation, type: "string",
-                               desc: "Your recommended option and the reasoning behind it", required: false
+        parameter :recommendation, type: "string",
+                               description: "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
+        parameter :blocking, type: "boolean",
+                         description: "true if work cannot correctly proceed until this is answered", required: false
 
         def captured_requests
           @captured_requests ||= []
         end
 
+        # :reek:BooleanParameter :reek:ControlParameter -- blocking is both
+        # stored data and legitimately changes the guidance message returned
+        # to the robot; the `param` declarations above fix this signature.
+        # :reek:LongParameterList -- one field per tool param declared above.
         def execute(question:, situation: "", options: [], recommendation: "", blocking: false, **)
           (@captured_requests ||= []) << {
             question: question,

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

@@ -13,27 +13,28 @@ module RobotLab
           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"
+        parameter :success, type: "boolean",
+                        description: "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"
+        parameter :summary, type: "string",
+                        description: "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)",
+        parameter :key_changes, type: "array",
+                            description: "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)",
+        parameter :key_learnings, type: "array",
+                              description: "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",
+        parameter :should_fully_stop, type: "boolean",
+                                  description: "Set to true only when instructed by a stop condition",
                                   required: false
 
         attr_reader :captured_result
 
+        # :reek:LongParameterList -- one field per tool param declared above.
         def execute(success:, summary:, key_changes: [], key_learnings: [], should_fully_stop: nil, **)
           @captured_result = IterationResult.new(
             success: success,

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

@@ -15,8 +15,8 @@ module RobotLab
           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"
+        parameter :path, type: "string", description: "Path of the file to create"
+        parameter :content, type: "string", description: "Full text content to write"
 
         def execute(path:, content:, **)
           resolved = File.expand_path(path, Dir.pwd)

data/lib/robot_lab/to/version.rb

@@ -2,6 +2,6 @@
 
 module RobotLab
   module To
-    VERSION = "0.2.7"
+    VERSION = "0.3.0"
   end
 end

data/lib/robot_lab/to.rb

@@ -44,6 +44,7 @@ module RobotLab
       # @return [void]
       def run(objective, **)
         config = Config.new(**)
+        ensure_provider_loaded(config.provider)
         suppress_llm_logging unless config.debug?
         Orchestrator.new(objective, config).run
       end
@@ -52,6 +53,7 @@ module RobotLab
       # objective and prior state are loaded from the run's run.json.
       def resume(run_id, **)
         config = Config.new(**)
+        ensure_provider_loaded(config.provider)
         suppress_llm_logging unless config.debug?
         Orchestrator.new(nil, config, resume_run_id: run_id).run
       end
@@ -66,6 +68,26 @@ module RobotLab
 
       private
 
+      # Provider gems register themselves on require by convention
+      # (ruby_llm-providers-<name> defines ruby_llm/providers/<name>). When the
+      # configured provider isn't registered yet — e.g. `robot-to --provider
+      # lms` from the CLI — try that conventional require so the user doesn't
+      # need a wrapper script. A miss falls through to RubyLLM's own "Unknown
+      # provider" error at request time.
+      def ensure_provider_loaded(provider)
+        return unless provider
+        return unless defined?(RubyLLM::Provider)
+
+        name = provider.to_s
+        return if RubyLLM::Provider.resolve(name)
+
+        begin
+          require "ruby_llm/providers/#{name}"
+        rescue LoadError
+          # Not a provider-gem provider; RubyLLM will report it if truly unknown.
+        end
+      end
+
       def suppress_llm_logging
         require "logger"
         null = Logger.new(File::NULL)

data/mkdocs.yml

@@ -136,7 +136,7 @@ nav:
       - CLI Reference: configuration/cli.md
   - Local Models:
       - Overview: local-models/index.md
-      - Ollama Setup: local-models/ollama.md
+      - LM Studio Setup: local-models/lm-studio.md
       - Built-in Tools: local-models/tools.md
       - Guardrails: local-models/guardrails.md
   - Reference: