robot_lab 0.2.6 → 0.2.8

data/lib/robot_lab/robot/template_rendering.rb

@@ -35,6 +35,7 @@ module RobotLab
       # Apply a prompt_manager template to the persistent chat.
       # If required parameters are missing, applies front matter config but
       # defers rendering until run time when all values are available.
+      # :reek:TooManyStatements -- linear parse/merge/apply/render sequence with a documented deferred-render rescue.
       def apply_template_to_chat(context)
         parsed = PM.parse(@template)
 
@@ -64,6 +65,11 @@ module RobotLab
 
       # Re-render the template with run-time context merged into build-time context.
       # prompt_manager parameters may be required (null) and only available at run time.
+      #
+      # Re-rendering replaces the system message, so the inline system_prompt must be
+      # re-appended here exactly as apply_system_prompt does at construction --
+      # otherwise it would be silently dropped on any run that supplies context.
+      # :reek:TooManyStatements -- must rebuild skills + template + inline prompt in one pass (see comment above).
       def rerender_template(run_context)
         merged = (@build_context || {}).merge(run_context)
         resolved_ctx = resolve_context(merged, network: nil)
@@ -81,15 +87,24 @@ module RobotLab
             bodies << body if body
           end
 
-          combined = bodies.join("\n\n")
-          @chat.with_instructions(combined)
+          @chat.with_instructions(with_system_prompt_appended(bodies.join("\n\n")))
         else
           parsed = PM.parse(@template)
           rendered = parsed.to_s(**resolved_ctx)
-          @chat.with_instructions(rendered)
+          @chat.with_instructions(with_system_prompt_appended(rendered))
         end
       end
 
+      # Append the inline system_prompt to freshly rendered template text.
+      #
+      # @param rendered [String] newly rendered template body
+      # @return [String] rendered text with system_prompt appended, if one is set
+      def with_system_prompt_appended(rendered)
+        return rendered unless @system_prompt
+
+        [rendered, @system_prompt].reject { |s| s.to_s.empty? }.join("\n\n")
+      end
+
       # Orchestrate skill expansion and template application.
       #
       # @param skill_ids [Array<Symbol>] skill IDs from constructor + front matter
@@ -103,6 +118,7 @@ module RobotLab
       # Pure computation — reads ivars but does not mutate @chat.
       #
       # @return [Array(Array<String>, RunConfig, Hash)] bodies, merged config, extras hash
+      # :reek:TooManyStatements -- accumulates bodies/config/extras across skills then the main template in one pure pass.
       def collect_prompt_content(skill_ids, context)
         visited = Set.new
         visited.add(@template) if @template
@@ -115,16 +131,18 @@ module RobotLab
 
         @expanded_skills.each do |skill_id|
           parsed = PM.parse(skill_id)
-          accumulate_extras(parsed.metadata, extras)
-          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
+          metadata = parsed.metadata
+          accumulate_extras(metadata, extras)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
 
         if @template
           parsed = PM.parse(@template)
-          accumulate_extras(parsed.metadata, extras)
-          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
+          metadata = parsed.metadata
+          accumulate_extras(metadata, extras)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
@@ -168,6 +186,7 @@ module RobotLab
       # @param visited [Set<Symbol>] already-visited IDs for cycle detection
       # @param catalog [AgentSkillCatalog] catalog to check first
       # @return [Array<Symbol>] flat ordered list of PM-based skill IDs
+      # :reek:TooManyStatements -- depth-first skill expansion with cycle guard and catalog-vs-PM branching.
       def expand_skills_with_catalog(skill_ids, visited, catalog)
         result = []
 
@@ -213,6 +232,7 @@ module RobotLab
       #
       # @param metadata [PM::Metadata] front matter metadata
       # @return [Array<Symbol>]
+      # :reek:FeatureEnvy -- reading the metadata argument's skills list is the extraction itself.
       def extract_skills_from_metadata(metadata)
         return [] unless metadata.respond_to?(:skills) && metadata.skills
 
@@ -263,6 +283,7 @@ module RobotLab
 
       # Extract identity and capability keys from front matter metadata.
       # Constructor-provided values take precedence over frontmatter.
+      # :reek:FeatureEnvy -- copying front-matter metadata fields into this robot's ivars is the method's purpose.
       def apply_front_matter_extras(metadata)
         if metadata.respond_to?(:robot_name) && metadata.robot_name && !@name_from_constructor
           @name = metadata.robot_name.to_s
@@ -296,6 +317,7 @@ module RobotLab
       # Resolve string tool names from frontmatter to Ruby constants.
       # Tool subclasses are instantiated; instances are used as-is.
       # Unresolvable names are skipped with a warning.
+      # :reek:FeatureEnvy -- inspecting each resolved constant to decide instantiate-vs-use-as-is.
       def resolve_frontmatter_tools(tool_names)
         tool_names.filter_map do |name|
           case name

data/lib/robot_lab/robot.rb

@@ -41,6 +41,12 @@ module RobotLab
   #     local_tools: [OrderLookup, RefundProcessor]
   #   )
   #
+  # :reek:TooManyMethods :reek:TooManyInstanceVariables -- Robot is intentionally the central orchestrator
+  #   (see CLAUDE.md); behavior is split into the included modules below.
+  # :reek:InstanceVariableAssumption -- every ivar is assigned in #initialize via assign_identity_ivars/
+  #   extract_config_ivars/initialize_runtime_state/initialize_memory; reek does not trace those helpers.
+  # :reek:RepeatedConditional -- `@bus` presence gates optional bus wiring at each independent site.
+  # :reek:DataClump -- (context, system_prompt, template) travel together as the robot's identity triple across construction APIs.
   class Robot < RubyLLM::Agent
     include Robot::TemplateRendering
     include Robot::MCPManagement
@@ -155,6 +161,8 @@ module RobotLab
     # @param stop [String, Array, nil] stop sequences
     # @param skills [Symbol, Array<Symbol>, nil] skill templates to prepend
     # @param config [RunConfig, nil] shared configuration (merged with explicit kwargs)
+    # :reek:LongParameterList -- the documented public constructor: one keyword per robot capability.
+    # :reek:BooleanParameter -- enable_cache and mcp_discovery are documented feature toggles.
     def initialize(
       name:,
       template: nil,
@@ -230,6 +238,7 @@ module RobotLab
     # Returns the model identifier
     #
     # @return [String, nil] the LLM model ID string
+    # :reek:FeatureEnvy -- duck-type unwrapping of the chat's model object into an id string.
     def model
       return nil unless @chat.respond_to?(:model)
 
@@ -245,6 +254,8 @@ module RobotLab
     # @param model [String, nil] new model
     # @param temperature [Float, nil] new temperature
     # @return [self]
+    # :reek:LongParameterList :reek:TooManyStatements -- public reconfiguration API; one guarded with_* application per option.
+    # :reek:ControlParameter -- `context || @build_context` is a fallback default, not behavior selection.
     def update(template: nil, context: nil, system_prompt: nil, model: nil, temperature: nil, **kwargs)
       if template
         @template = template
@@ -268,6 +279,8 @@ module RobotLab
     #
     # @param result [SimpleFlow::Result] incoming result from previous step
     # @return [SimpleFlow::Result] result with robot output
+    # :reek:TooManyStatements -- SimpleFlow step: timing, run, and error-shielding belong together.
+    # :reek:DuplicateMethodCall -- each clock_gettime samples a different instant (start/stop/rescue); a local would be wrong.
     def call(result)
       run_context = extract_run_context(result)
 
@@ -369,6 +382,7 @@ module RobotLab
     #
     # @param keep_system [Boolean] whether to preserve the system message
     # @return [self]
+    # :reek:BooleanParameter :reek:ControlParameter -- keep_system is a documented public API toggle.
     def clear_messages(keep_system: true)
       if keep_system
         system_msg = @chat.messages.find { |m| m.role == :system }
@@ -448,6 +462,10 @@ module RobotLab
     # @param kwargs [Hash] additional keyword args forwarded to Robot#run
     # @return [RobotResult] when async: false
     # @return [DelegationFuture] when async: true
+    # :reek:BooleanParameter :reek:ControlParameter -- async is the documented sync/future API switch.
+    # :reek:TooManyStatements -- the sync and async timing/annotation paths read best side by side.
+    # :reek:DuplicateMethodCall -- clock_gettime pairs sample distinct start/stop instants in each branch.
+    # :reek:FeatureEnvy -- annotating the delegatee's result with duration and delegator is the point of delegate.
     def delegate(to:, task:, async: false, **)
       if async
         future = DelegationFuture.new(robot_name: to.name, delegated_by: @name)
@@ -478,6 +496,7 @@ module RobotLab
     # into chat internals.
     #
     # @return [String, nil]
+    # :reek:FeatureEnvy -- duck-type unwrapping of the chat's model object.
     def chat_provider
       m = @chat.model
       m.respond_to?(:provider) ? m.provider : nil
@@ -504,6 +523,7 @@ module RobotLab
     #
     # @param text [String] the insight to record
     # @return [self]
+    # :reek:TooManyStatements -- dedupe/store/hook sequence shares the learnings state throughout.
     def learn(text)
       text = text.to_s.strip
       return self if text.empty?
@@ -561,6 +581,7 @@ module RobotLab
     # `tools:` is a NAME allowlist (a filter over available tools), not a place
     # to attach tool instances — passing instances there silently attaches
     # nothing. Catch the mistake with a clear, actionable error.
+    # :reek:FeatureEnvy -- inspecting each offending entry to build an actionable error message.
     def validate_tools_filter!(tools)
       return unless tools.is_a?(Array)
 
@@ -574,6 +595,8 @@ module RobotLab
             "(e.g. RobotLab.build(local_tools: [MyTool.new]))."
     end
 
+    # :reek:LongParameterList :reek:TooManyStatements -- one keyword and one assignment per identity ivar;
+    #   a hash would lose keyword checking.
     def assign_identity_ivars(name:, template:, system_prompt:, context:, description:,
                               local_tools:, skills:, mcp_discovery:)
       @name = name.to_s
@@ -592,6 +615,8 @@ module RobotLab
 
     # Build RunConfig from explicit kwargs, merged on top of any passed-in config.
     # Explicit constructor kwargs always win.
+    # :reek:LongParameterList -- mirrors the constructor's LLM kwargs one-to-one so explicit values win over config.
+    # :reek:FeatureEnvy -- assembling the explicit_fields hash it just built is the merge itself.
     def build_effective_config(model:, temperature:, top_p:, top_k:, max_tokens:,
                                presence_penalty:, frequency_penalty:, stop:,
                                on_tool_call:, on_tool_result:, on_content:,
@@ -666,8 +691,27 @@ module RobotLab
       end
     end
 
+    # Append the inline system prompt to whatever apply_template already set.
+    #
+    # The template renders first and establishes the base instructions; the
+    # inline system_prompt is appended so both survive. Combining into a single
+    # system message (rather than using with_instructions(append: true), which
+    # adds a second one) keeps readers that look at only the first system
+    # message -- notably AgentSkillMatching's snapshot/restore -- correct.
     def apply_system_prompt
-      @chat.with_instructions(@system_prompt) if @system_prompt
+      return unless @system_prompt
+
+      base     = current_system_instructions.to_s
+      combined = [base, @system_prompt].reject(&:empty?).join("\n\n")
+      @chat.with_instructions(combined)
+    end
+
+    # Content of the chat's system message, or nil when none is set.
+    #
+    # @return [String, nil]
+    def current_system_instructions
+      messages = @chat.instance_variable_get(:@messages)
+      messages&.find { |m| m.role.to_s == "system" }&.content
     end
 
     def apply_chat_params
@@ -691,6 +735,7 @@ module RobotLab
 
     # Dynamically delegate all with_* methods from @chat, returning self for chaining.
     # Discovered from the actual Chat class to avoid maintenance sync issues.
+    # :reek:NestedIterators -- the inner block is the delegator method body being defined, not an iteration.
     def define_chat_delegators
       @chat.class.public_instance_methods(false)
            .select { |m| m.start_with?('with_') }
@@ -702,6 +747,7 @@ module RobotLab
            end
     end
 
+    # :reek:ControlParameter -- `network_memory || network&.memory || @memory` is the documented memory cascade.
     def resolve_active_memory(network: nil, network_memory: nil)
       network_memory || network&.memory || @memory
     end
@@ -757,17 +803,21 @@ module RobotLab
     # is the definitive choke point: tools are fully resolved (MCP connected)
     # and about to be handed to the chat, so the cap holds no matter how the
     # tools were configured, filtered, or connected. Cap value comes from
-    # RunConfig#max_tools, defaulting to DEFAULT_MAX_TOOLS; nil/<=0 disables it.
+    # RunConfig#max_tools, defaulting to DEFAULT_MAX_TOOLS; a nil, zero, or
+    # negative max_tools falls back to that default, so the cap cannot be
+    # disabled from configuration.
     #
     # @param tools [Array<Tool>] the resolved tools
     # @return [Array<Tool>] at most `max_tools` tools
+    # :reek:FeatureEnvy -- clamping the passed-in tool list against the provider limit is a pure filter.
     def cap_tools(tools)
-      max = effective_max_tools
-      return tools if max.nil? || tools.size <= max
+      max  = effective_max_tools
+      size = tools.size
+      return tools if max.nil? || size <= max
 
       RobotLab.config.logger.warn(
-        "[#{@name}] tool list (#{tools.size}) exceeds max_tools (#{max}); " \
-        "sending #{max}, dropping #{tools.size - max}"
+        "[#{@name}] tool list (#{size}) exceeds max_tools (#{max}); " \
+        "sending #{max}, dropping #{size - max}"
       )
       tools.first(max)
     end
@@ -781,10 +831,12 @@ module RobotLab
       configured&.positive? ? configured : DEFAULT_MAX_TOOLS
     end
 
+    # :reek:TooManyStatements -- builds the generation hook context then runs the pre-ask setup chain in order.
     def invoke_ask(context:, kwargs:, hooks:, block:)
+      network = context.network
       generation_context = LlmGenerationHookContext.new(
         robot: self,
-        network: context.network,
+        network: network,
         task: context.task,
         memory: context.memory,
         config: context.config,
@@ -793,9 +845,9 @@ module RobotLab
       )
 
       RobotLab::Hooks.run(:llm_generation, generation_context,
-                          registries: hook_registries(context.network), per_run_hooks: hooks) do
+                          registries: hook_registries(network), per_run_hooks: hooks) do
         effective_message = inject_learnings(generation_context.request)
-        maybe_compact(network: context.network)
+        maybe_compact(network: network)
         install_circuit_breaker if @config.max_tool_rounds
         install_doom_loop_detection
         ask_kwargs = kwargs.slice(:with)
@@ -809,6 +861,7 @@ module RobotLab
     end
 
     # Extract run context from SimpleFlow::Result
+    # :reek:TooManyStatements -- one delete/re-add per robot-specific run param; a loop would hide which keys are special.
     def extract_run_context(result)
       run_params = (result.context[:run_params] || {}).dup
 
@@ -825,15 +878,16 @@ module RobotLab
       base = run_params.dup
 
       # Merge current value into context
-      merged = case result.value
+      value  = result.value
+      merged = case value
                when Hash
-                 base.merge(result.value.transform_keys(&:to_sym))
+                 base.merge(value.transform_keys(&:to_sym))
                when RobotResult
-                 base.merge(message: result.value.last_text_content)
+                 base.merge(message: value.last_text_content)
                when String
-                 base.merge(message: result.value)
+                 base.merge(message: value)
                else
-                 base.merge(message: result.value.to_s)
+                 base.merge(message: value.to_s)
                end
 
       # Add back the special params
@@ -848,6 +902,8 @@ module RobotLab
       merged
     end
 
+    # :reek:TooManyStatements :reek:FeatureEnvy -- adapting a provider response's many optional fields into
+    #   a RobotResult is inherently response-centric.
     def build_result(response, _memory)
       text = result_text(response)
       output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
@@ -855,11 +911,10 @@ module RobotLab
       tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
 
       # Extract token usage from the response
-      input_toks = 0
-      output_toks = 0
-      if response.respond_to?(:tokens) && response.tokens
-        input_toks = response.tokens.input.to_i
-        output_toks = response.tokens.output.to_i
+      input_toks = output_toks = 0
+      if response.respond_to?(:tokens) && (tokens = response.tokens)
+        input_toks = tokens.input.to_i
+        output_toks = tokens.output.to_i
       elsif response.respond_to?(:input_tokens)
         input_toks = response.input_tokens.to_i
         output_toks = response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0
@@ -888,6 +943,7 @@ module RobotLab
     # The chat-history fallback is scoped to messages AFTER the last user message
     # (the current turn) to prevent a previous turn's response from being returned
     # when a thinking-mode model emits nothing in response.content.
+    # :reek:TooManyStatements :reek:FeatureEnvy -- documented fallback chain over the response's optional content/thinking/history fields.
     def result_text(response)
       content = response.content if response.respond_to?(:content)
       return content if content && !content.to_s.empty?
@@ -966,6 +1022,8 @@ module RobotLab
     # Tracks tool call names; when a consecutive or cyclic repetition exceeds
     # the threshold, embeds a self-correction warning in the tool result so the
     # LLM can change strategy without requiring an external circuit breaker.
+    # :reek:TooManyStatements :reek:FeatureEnvy -- the singleton override closes over the detector;
+    #   tracking/checking it there is the design.
     def install_doom_loop_detection
       threshold = @config.doom_loop_threshold || DoomLoopDetector::DEFAULT_THRESHOLD
       detector = DoomLoopDetector.new(threshold: threshold)
@@ -989,6 +1047,7 @@ module RobotLab
     end
 
     # Remove the doom loop detection singleton method from @chat.
+    # :reek:FeatureEnvy -- checking-then-removing on the chat's singleton class is one atomic operation.
     def remove_doom_loop_detection
       sc = @chat.singleton_class
       sc.remove_method(:execute_tool) if sc.method_defined?(:execute_tool)
@@ -1004,6 +1063,9 @@ module RobotLab
     # Fires the :compaction hook family (before/around/after_compaction).
     # An on_compaction handler can replace the default strategy entirely by
     # setting ctx.compacted_messages; the core algorithm is skipped when handled.
+    # :reek:TooManyStatements -- guard chain plus hook-wrapped strategy dispatch; splitting would separate the hook from its guards.
+    # :reek:DuplicateMethodCall -- @chat.messages is read at different lifecycle points
+    #   (guard, before-snapshot, after-snapshot); it mutates in between.
     def maybe_compact(network: nil)
       return if @chat.messages.empty?
 

data/lib/robot_lab/robot_result.rb

@@ -60,6 +60,8 @@ module RobotLab
     # @param stop_reason [String, nil] reason for stopping
     # @param input_tokens [Integer] input tokens consumed (default 0)
     # @param output_tokens [Integer] output tokens generated (default 0)
+    # :reek:LongParameterList -- serializable value object: one keyword per persisted field.
+    # :reek:ControlParameter -- `created_at || Time.now` and `id || SecureRandom.uuid` are nil-safe defaults.
     def initialize(
       robot_name:,
       output:,
@@ -178,6 +180,7 @@ module RobotLab
     # @param hash [Hash] Serialized result data
     # @return [RobotResult]
     #
+    # :reek:DuplicateMethodCall -- Message.from_hash maps four distinct message collections; there is no shared receiver to hoist.
     def self.from_hash(hash)
       hash = hash.transform_keys(&:to_sym)
 

data/lib/robot_lab/run_config.rb

@@ -27,6 +27,7 @@ module RobotLab
   #   effective.temperature  #=> 0.9
   #   effective.model        #=> "claude-sonnet-4"
   #
+  # :reek:RepeatedConditional -- `if value` guards in independent field loops; each skips unset fields.
   class RunConfig
     # LLM configuration fields (applied to chat via with_* methods)
     LLM_FIELDS = %i[
@@ -119,6 +120,8 @@ module RobotLab
     # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
     # @param provider [String, Symbol, nil] passed through to chat.with_model's provider: kwarg
     # @param assume_model_exists [Boolean] passed through to chat.with_model's assume_exists: kwarg
+    # :reek:BooleanParameter -- assume_model_exists is a pass-through to RubyLLM's with_model kwarg.
+    # :reek:FeatureEnvy -- configuring the chat object handed in is exactly what apply_to is for.
     def apply_to(chat, provider: nil, assume_model_exists: false)
       LLM_FIELDS.each do |field|
         value = @fields[field]
@@ -141,6 +144,7 @@ module RobotLab
     #
     # @param metadata [Object] a PM::Metadata object (responds to field names)
     # @return [RunConfig]
+    # :reek:TooManyStatements -- linear duck-typed extraction of LLM then tool fields from front matter.
     def self.from_front_matter(metadata)
       fields = {}
 
@@ -171,6 +175,7 @@ module RobotLab
 
     # @param other [RunConfig] the other RunConfig to compare
     # @return [Boolean]
+    # :reek:FeatureEnvy -- equality naturally reads the other operand.
     def ==(other)
       other.is_a?(RunConfig) && to_h == other.to_h
     end

data/lib/robot_lab/script_tool.rb

@@ -2,7 +2,6 @@
 
 require 'open3'
 require 'shellwords'
-require 'timeout'
 
 module RobotLab
   # Factory module for wrapping AgentSkills scripts as RobotLab::Tool instances.
@@ -10,7 +9,18 @@ module RobotLab
   # Given a path to an executable shell script, produces a Tool that shells
   # out to the script and returns its combined stdout+stderr output.
   # Non-executable scripts return nil with a logged warning.
+  #
+  # Core has no sandboxing of its own: by default every script runs unconfined
+  # with no timeout. An extension gem (e.g. robot_lab-sandbox) can install a
+  # confinement strategy by setting {.executor} to an object responding to
+  # +call(cmd, capabilities:, skill_dir:)+; when set, ScriptTool.execute
+  # delegates to it instead of running the command directly.
   module ScriptTool
+    class << self
+      # @return [#call, nil] optional executor installed by an extension gem
+      attr_accessor :executor
+    end
+
     # Wrap a script file as a RobotLab::Tool.
     #
     # @param script_path [String, Pathname] path to the script file
@@ -19,6 +29,8 @@ module RobotLab
     # @param capabilities [Capabilities, nil] declared capabilities (from SKILL.md)
     # @param skill_dir [String, nil] skill bundle root (defaults to the script's dir)
     # @return [RobotLab::Tool, nil] nil if the script is not executable
+    # :reek:ControlParameter -- `capabilities || ...` and `skill_dir || ...` are nil-safe defaults, not behavior selection.
+    # :reek:TooManyStatements -- linear derive/validate/build factory; the closure needs every derived local.
     def self.from_path(script_path, capabilities: nil, skill_dir: nil)
       path = Pathname.new(script_path)
 
@@ -52,49 +64,18 @@ module RobotLab
       end
     end
 
-    # Run a command, optionally confined by the sandbox and a timeout.
+    # Run a command, delegating to the installed {.executor} if one is present.
     #
-    # When sandboxing is disabled (the default) this is the original, unconfined
-    # capture2e path with no timeout — behaviour is unchanged. When enabled, the
-    # command is wrapped by the sandbox strategy for the effective grant and
-    # bounded by the grant's timeout.
+    # With no executor installed (the default — core has no sandboxing), this
+    # is a plain, unconfined capture2e path with no timeout. An extension gem
+    # that sets {.executor} controls confinement and timeout behavior entirely.
     #
     # @return [String] combined stdout+stderr, or an error string on failure
     def self.execute(cmd, capabilities:, skill_dir:)
-      unless Sandbox.enabled?
-        output, status = Open3.capture2e(*cmd)
-        return format_result(output, status)
-      end
+      return executor.call(cmd, capabilities: capabilities, skill_dir: skill_dir) if executor
 
-      grant   = capabilities.intersect(Capabilities.ceiling)
-      sandbox = Sandbox.for(grant, skill_dir: skill_dir)
-      begin
-        output, status = run_with_timeout(sandbox.wrap(cmd), grant.timeout)
-        format_result(output, status)
-      ensure
-        sandbox.cleanup
-      end
-    end
-
-    # @return [Array(String, Process::Status|nil)] output and status (nil = timed out)
-    def self.run_with_timeout(cmd, timeout)
-      Open3.popen2e(*cmd, pgroup: true) do |stdin, out, wait|
-        stdin.close
-        output = +''
-        begin
-          Timeout.timeout(timeout) { output << out.read }
-        rescue Timeout::Error
-          terminate(wait.pid)
-          return ["#{output}\n[killed: exceeded #{timeout}s]", nil]
-        end
-        [output, wait.value]
-      end
-    end
-
-    def self.terminate(pid)
-      Process.kill('-TERM', Process.getpgid(pid))
-    rescue StandardError
-      nil
+      output, status = Open3.capture2e(*cmd)
+      format_result(output, status)
     end
 
     # @param status [Process::Status, nil] nil indicates a timeout kill

data/lib/robot_lab/state_proxy.rb

@@ -147,6 +147,7 @@ module RobotLab
 
     # Respond to method calls as hash access
     #
+    # :reek:BooleanParameter -- include_private is Ruby's respond_to_missing? contract signature.
     def respond_to_missing?(method_name, include_private = false)
       key = method_name.to_s.chomp("=").to_sym
       @data.key?(key) || super

data/lib/robot_lab/streaming/context.rb

@@ -36,6 +36,7 @@ module RobotLab
       # @param publish [Proc] callback for publishing events
       # @param parent_run_id [String, nil] parent run identifier
       # @param sequence_counter [SequenceCounter, nil] shared sequence counter
+      # :reek:ControlParameter -- `sequence_counter || SequenceCounter.new` is a nil-safe default.
       def initialize(run_id:, message_id:, scope:, publish:, parent_run_id: nil, sequence_counter: nil)
         @run_id = run_id
         @parent_run_id = parent_run_id

data/lib/robot_lab/streaming/events.rb

@@ -7,6 +7,7 @@ module RobotLab
     # Defines the structure and types of events emitted during
     # robot and network execution.
     #
+    # :reek:TooManyConstants -- deliberately a flat catalog of every streaming event name.
     module Events
       # Run lifecycle events
       RUN_STARTED = "run.started"

data/lib/robot_lab/task.rb

@@ -89,6 +89,7 @@ module RobotLab
 
     private
 
+    # :reek:TooManyStatements -- one guarded assignment per task-level override injected into run params.
     def enhanced_result(result)
       run_params = deep_merge(result.context[:run_params] || {}, @context)
       run_params[:mcp] = @mcp unless @mcp == :none
@@ -114,6 +115,7 @@ module RobotLab
     # @param override [Hash] the overriding hash
     # @return [Hash] the merged result
     #
+    # :reek:FeatureEnvy -- pure recursive hash merge of its two arguments; it has no useful self.
     def deep_merge(base, override)
       base = base.transform_keys(&:to_sym)
       override = override.transform_keys(&:to_sym)

data/lib/robot_lab/tool.rb

@@ -27,6 +27,8 @@ module RobotLab
   # enabling tools that modify their robot's state (temperature,
   # system prompt, spawning, etc.).
   #
+  # :reek:InstanceVariableAssumption -- @custom_name/@mcp are set by Tool.create via instance_variable_set,
+  #   @raise_on_error/@ractor_safe are class-level DSL ivars; every read is defined?-guarded.
   class Tool < RubyLLM::Tool
     # @!attribute [rw] robot
     #   @return [Robot, nil] the robot that owns this tool
@@ -93,6 +95,7 @@ module RobotLab
     #
     # @param args [Hash] the tool arguments from the LLM
     # @return [Object] the tool result or an error string
+    # :reek:TooManyStatements -- hook-wrapped dispatch with per-error-class handling; the rescue clauses are the method.
     def call(args)
       context = ToolCallHookContext.new(tool: self, tool_args: args, robot: @robot)
 
@@ -145,6 +148,7 @@ module RobotLab
     #     mcp: "brave_search"
     #   ) { |args| mcp_client.call_tool("search", args) }
     #
+    # :reek:TooManyStatements -- anonymous-class factory: DSL application and instance wiring form one linear build.
     def self.create(name:, description: nil, parameters: nil, mcp: nil, robot: nil, &handler)
       desc_text = description
       params_hash = parameters

data/lib/robot_lab/user_message.rb

@@ -41,6 +41,7 @@ module RobotLab
     # @param system_prompt [String, nil] additional system prompt
     # @param metadata [Hash, nil] additional metadata
     # @param id [String, nil] unique identifier (defaults to UUID)
+    # :reek:ControlParameter -- `metadata || {}` and `id || SecureRandom.uuid` are nil-safe defaults.
     def initialize(content, session_id: nil, system_prompt: nil, metadata: nil, id: nil)
       @content = content.to_s
       @session_id = session_id

data/lib/robot_lab/utils.rb

@@ -13,6 +13,7 @@ module RobotLab
     # When already inside an Async reactor, creates a child task.
     # Otherwise, creates a temporary reactor that runs the block
     # and cleans up automatically.
+    # :reek:FeatureEnvy -- formatting the rescued exception for the log line; there is nothing else to reference.
     def dispatch_async(&block)
       Async do
         block.call
@@ -25,6 +26,7 @@ module RobotLab
     #
     # @param obj [Object] the object to duplicate
     # @return [Object] the deep copy
+    # :reek:FeatureEnvy -- pure recursive copy of its argument; it has no useful self.
     def deep_dup(obj)
       case obj
       when Hash

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.2.6"
+  VERSION = "0.2.8"
 end

data/lib/robot_lab/waiter.rb

@@ -28,6 +28,9 @@ module RobotLab
     # @param timeout [Numeric, nil] maximum seconds to wait (nil = indefinite)
     # @return [Object, :timeout] the signaled value, or :timeout if timed out
     #
+    # :reek:TooManyStatements -- register/block/drain steps of the wake-pipe protocol are one atomic unit.
+    # :reek:DuplicateMethodCall -- the synchronize blocks are deliberately separate: the lock must be released
+    #   around the blocking wait_readable.
     def wait(timeout: nil)
       @mutex.synchronize do
         return @value if @signaled