robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/agent_skill.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RobotLab
+  # Value object representing an AgentSkills.io skill folder.
+  #
+  # A skill is a directory containing SKILL.md with required front matter
+  # fields (name, description) and optional scripts/, references/, assets/.
+  class AgentSkill
+    attr_reader :name, :description, :path, :capabilities
+
+    # @param skill_md_path [String, Pathname] path to the SKILL.md file
+    # @raise [ConfigurationError] if name or description is missing
+    def initialize(skill_md_path)
+      @path = Pathname.new(skill_md_path).dirname
+      content = File.read(skill_md_path)
+      front_matter, @_body = parse_skill_md(content)
+
+      @name         = front_matter["name"]
+      @description  = front_matter["description"]
+      @capabilities = Capabilities.from_front_matter(front_matter)
+
+      raise ConfigurationError, "SKILL.md at #{skill_md_path} missing 'name'"        if @name.to_s.strip.empty?
+      raise ConfigurationError, "SKILL.md at #{skill_md_path} missing 'description'" if @description.to_s.strip.empty?
+    end
+
+    # Full instruction text from the SKILL.md body (below the front matter).
+    def instructions
+      @instructions ||= @_body.strip
+    end
+
+    # Pathnames of all files inside the scripts/ subdirectory, sorted.
+    def scripts
+      @scripts ||= begin
+        dir = @path.join("scripts")
+        dir.directory? ? dir.children.select(&:file?).sort : []
+      end
+    end
+
+    # RobotLab::Tool instances wrapping each executable script.
+    # Non-executable scripts are skipped with a warning.
+    def script_tools
+      @script_tools ||= scripts.filter_map do |script_path|
+        ScriptTool.from_path(script_path, capabilities: @capabilities, skill_dir: @path.to_s)
+      end
+    end
+
+    private
+
+    # Split SKILL.md content into front matter Hash and body String.
+    def parse_skill_md(content)
+      if content.start_with?("---\n")
+        parts = content.split(/^---\s*$/, 3)
+        if parts.length >= 3
+          fm = YAML.safe_load(parts[1])
+          front_matter = fm.is_a?(Hash) ? fm : {}
+          return [front_matter, parts[2]]
+        end
+      end
+      [{}, content]
+    end
+  end
+end

data/lib/robot_lab/agent_skill_catalog.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Singleton registry that scans ~/.prompts/skills/ and provides
+  # AgentSkill lookup by ID.
+  #
+  # Skills are loaded lazily on first access (thread-safe via Mutex).
+  # Bad SKILL.md files (missing name/description) are skipped with a warning.
+  class AgentSkillCatalog
+    SKILLS_ROOT = Pathname.new(File.expand_path("~/.prompts/skills"))
+
+    class << self
+      # The process-level singleton instance (uses SKILLS_ROOT).
+      def instance
+        @instance ||= new(SKILLS_ROOT)
+      end
+
+      # Reset the singleton (used in tests to swap the skills root).
+      def reset!
+        @instance = nil
+      end
+    end
+
+    # @param skills_root [String, Pathname] directory to scan for skill folders
+    def initialize(skills_root = SKILLS_ROOT)
+      @skills_root = Pathname.new(skills_root)
+      @skills      = {}
+      @mutex       = Mutex.new
+      @loaded      = false
+    end
+
+    # Return the AgentSkill for the given ID, or nil if not found.
+    #
+    # @param id [Symbol, String] skill folder name
+    # @return [AgentSkill, nil]
+    def find(id)
+      load!
+      @skills[id.to_sym]
+    end
+
+    # All discovered AgentSkill objects.
+    #
+    # @return [Array<AgentSkill>]
+    def all
+      load!
+      @skills.values
+    end
+
+    private
+
+    def load!
+      @mutex.synchronize { load_skills! unless @loaded }
+    end
+
+    def load_skills!
+      @loaded = true
+      return unless @skills_root.directory?
+
+      @skills_root.each_child do |dir|
+        next unless dir.directory?
+
+        skill_file = dir.join("SKILL.md")
+        next unless skill_file.exist?
+
+        begin
+          skill = AgentSkill.new(skill_file)
+          @skills[skill.name.to_sym] = skill
+        rescue ConfigurationError, Psych::SyntaxError => e
+          RobotLab.config.logger.warn("AgentSkillCatalog: #{e.message}, skipping #{dir.basename}")
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/ask_user.rb

@@ -65,11 +65,11 @@ module RobotLab
     private
 
     def input_io
-      robot&.respond_to?(:input) && robot.input ? robot.input : $stdin
+      robot.respond_to?(:input) && robot.input ? robot.input : $stdin
     end
 
     def output_io
-      robot&.respond_to?(:output) && robot.output ? robot.output : $stdout
+      robot.respond_to?(:output) && robot.output ? robot.output : $stdout
     end
   end
 end

data/lib/robot_lab/budget/ledger.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Budget
+    # Thread-safe reserve/reconcile ledger for tracking consumption against
+    # per-dimension limits (e.g. :tokens, :cost).
+    #
+    # Call +reserve!+ before doing billable work, so an already-exhausted
+    # budget is caught before the work is attempted rather than after.
+    # Once the work completes, +reconcile!+ replaces the reservation with
+    # the actual amount consumed (which may be more or less than what was
+    # reserved — LLM call sizes aren't known in advance). +release!+ drops
+    # an unused reservation without recording any consumption.
+    #
+    # A dimension with no configured limit is treated as unlimited:
+    # +reserve!+ never raises for it and +remaining+ returns
+    # +Float::INFINITY+.
+    #
+    # @example
+    #   ledger = RobotLab::Budget::Ledger.new(limits: { tokens: 10_000, cost: 0.50 })
+    #   ledger.reserve!(:tokens, ledger.remaining(:tokens))
+    #   # ... do the billable work ...
+    #   ledger.reconcile!(:tokens, ledger.remaining(:tokens), actual_tokens_used)
+    class Ledger
+      # @!attribute [r] limits
+      #   @return [Hash{Symbol=>Numeric}] per-dimension ceilings
+      # @!attribute [r] consumed
+      #   @return [Hash{Symbol=>Numeric}] actual amount consumed per dimension so far
+      attr_reader :limits, :consumed
+
+      # @param limits [Hash{Symbol=>Numeric}] per-dimension ceilings; a dimension absent
+      #   from this hash is treated as unlimited
+      # @param consumed [Hash{Symbol=>Numeric}] starting consumption (e.g. restored from a prior run)
+      def initialize(limits: {}, consumed: {})
+        @mutex = Mutex.new
+        @limits = limits
+        @consumed = Hash.new(0).merge(consumed)
+        @reserved = Hash.new(0)
+      end
+
+      # Reserves +amount+ against +key+'s remaining budget.
+      #
+      # A no-op (never raises) when +key+ has no configured limit.
+      #
+      # @param key [Symbol] the budget dimension
+      # @param amount [Numeric] the amount to reserve
+      # @raise [RobotLab::BudgetExceeded] if the reservation would exceed the limit
+      # @return [void]
+      def reserve!(key, amount)
+        @mutex.synchronize do
+          limit = @limits[key]
+          next unless limit
+
+          committed = @consumed[key] + @reserved[key]
+          if committed + amount > limit
+            raise BudgetExceeded, "budget exceeded for #{key}: #{committed + amount} > #{limit}"
+          end
+
+          @reserved[key] += amount
+        end
+      end
+
+      # Replaces a prior reservation with the actual amount consumed.
+      #
+      # @param key [Symbol] the budget dimension
+      # @param reserved_amount [Numeric] the amount previously passed to +reserve!+
+      # @param actual_amount [Numeric] the amount actually consumed
+      # @return [void]
+      def reconcile!(key, reserved_amount, actual_amount)
+        @mutex.synchronize do
+          @reserved[key] = [0, @reserved[key] - reserved_amount].max
+          @consumed[key] += actual_amount
+        end
+      end
+
+      # Drops a reservation without recording any consumption (e.g. the
+      # reserved work was skipped).
+      #
+      # @param key [Symbol] the budget dimension
+      # @param amount [Numeric] the amount previously passed to +reserve!+
+      # @return [void]
+      def release!(key, amount)
+        @mutex.synchronize { @reserved[key] = [0, @reserved[key] - amount].max }
+      end
+
+      # @param key [Symbol] the budget dimension
+      # @return [Numeric] remaining budget for +key+, floored at 0; +Float::INFINITY+ when unlimited
+      def remaining(key)
+        @mutex.synchronize do
+          limit = @limits[key]
+          next Float::INFINITY unless limit
+
+          [limit - @consumed[key] - @reserved[key], 0].max
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/bus_poller.rb

@@ -115,7 +115,16 @@ module RobotLab
     # Process one delivery, then drain any queued deliveries for the robot.
     def process_and_drain(robot, delivery)
       robot.send(:process_delivery, delivery)
+      drain_queued_deliveries(robot)
+    rescue BusError => e
+      release_robot(robot)
+      RobotLab.config.logger.warn("BusPoller: delivery error: #{e.message}")
+    rescue => e
+      release_robot(robot)
+      RobotLab.config.logger.warn("BusPoller: unexpected error: #{e.message}")
+    end
 
+    def drain_queued_deliveries(robot)
       loop do
         next_delivery = @mutex.synchronize do
           name  = robot.name
@@ -138,12 +147,10 @@ module RobotLab
           RobotLab.config.logger.warn("BusPoller: delivery error: #{e.message}")
         end
       end
-    rescue BusError => e
-      @mutex.synchronize { @robot_busy[robot.name] = false }
-      RobotLab.config.logger.warn("BusPoller: delivery error: #{e.message}")
-    rescue => e
+    end
+
+    def release_robot(robot)
       @mutex.synchronize { @robot_busy[robot.name] = false }
-      RobotLab.config.logger.warn("BusPoller: unexpected error: #{e.message}")
     end
   end
 end

data/lib/robot_lab/capabilities.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Declared execution capabilities for a skill script: which paths it may read
+  # and write, whether it may use the network, how long it may run, and how much
+  # it is trusted.
+  #
+  # A skill declares what it *wants* in SKILL.md front matter; the global config
+  # declares the *ceiling* of what any skill may have. The effective grant is the
+  # intersection of the two (see {#intersect}) — anything the skill asks for that
+  # the ceiling does not permit is dropped.
+  class Capabilities
+    DEFAULT_TIMEOUT = 60
+    TRUST_LEVELS    = %w[core external].freeze
+
+    attr_reader :fs_read, :fs_write, :network, :timeout, :trust
+
+    def initialize(fs_read: [], fs_write: [], network: false, timeout: DEFAULT_TIMEOUT, trust: "external")
+      @fs_read  = Array(fs_read).map(&:to_s)
+      @fs_write = Array(fs_write).map(&:to_s)
+      @network  = network ? true : false
+      @timeout  = timeout.to_i.positive? ? timeout.to_i : DEFAULT_TIMEOUT
+      @trust    = TRUST_LEVELS.include?(trust.to_s) ? trust.to_s : "external"
+    end
+
+    # Build from a SKILL.md front matter hash (string or symbol keys).
+    def self.from_front_matter(front_matter)
+      fm = front_matter || {}
+      new(
+        fs_read:  fm_value(fm, :fs_read, []),
+        fs_write: fm_value(fm, :fs_write, []),
+        network:  fm_value(fm, :network, false),
+        timeout:  fm_value(fm, :timeout, DEFAULT_TIMEOUT),
+        trust:    fm_value(fm, :trust, "external")
+      )
+    end
+
+    # Look up a front-matter key tolerating string or symbol keys.
+    def self.fm_value(front_matter, key, default)
+      value = front_matter[key.to_s]
+      value = front_matter[key] if value.nil?
+      value.nil? ? default : value
+    end
+
+    # Build the ceiling from the global config's sandbox section.
+    def self.ceiling(config = RobotLab.config)
+      section = config.respond_to?(:sandbox) ? config.sandbox : nil
+      return new(fs_read: ["."]) unless section
+
+      new(
+        fs_read:  section.fs_read  || ["."],
+        fs_write: section.fs_write || [],
+        network:  section.network  || false,
+        timeout:  section.timeout  || DEFAULT_TIMEOUT
+      )
+    end
+
+    def core? = trust == "core"
+
+    # Effective grant = this (declared) ∩ ceiling. Paths survive only when
+    # inside a ceiling root; network requires both; timeout is the smaller;
+    # trust stays as declared.
+    def intersect(ceiling)
+      self.class.new(
+        fs_read:  clamp_paths(@fs_read, ceiling.fs_read),
+        fs_write: clamp_paths(@fs_write, ceiling.fs_write),
+        network:  @network && ceiling.network,
+        timeout:  [@timeout, ceiling.timeout].min,
+        trust:    @trust
+      )
+    end
+
+    private
+
+    def clamp_paths(requested, allowed)
+      roots = expand(allowed)
+      expand(requested).select { |p| roots.any? { |r| p == r || p.start_with?("#{r}/") } }
+    end
+
+    def expand(paths)
+      Array(paths).map { |p| File.expand_path(p.to_s) }
+    end
+  end
+end

data/lib/robot_lab/config/defaults.yml

@@ -25,6 +25,16 @@ defaults:
   mcp: :none
   tools: :none
 
+  # Skill-script sandboxing (opt-in). When enabled, skill scripts run confined
+  # to the effective grant (their SKILL.md declaration ∩ this ceiling). macOS
+  # uses sandbox-exec; other platforms run unconfined with a warning.
+  sandbox:
+    enabled: false        # opt-in; off = scripts run exactly as before
+    fs_read: ["."]        # ceiling: paths any skill may read (relative to cwd)
+    fs_write: []          # ceiling: paths any skill may write
+    network: false        # ceiling: may any skill use the network
+    timeout: 60           # ceiling: max seconds a skill script may run
+
   # Chat Configuration (passed to RubyLLM.chat)
   # These are global defaults that can be overridden per-robot or per-run
   chat:

data/lib/robot_lab/config.rb

@@ -43,7 +43,6 @@ module RobotLab
       @logger ||= default_logger
     end
 
-
     # Apply RubyLLM configuration after loading.
     #
     # This method should be called after initialization to configure
@@ -56,7 +55,6 @@ module RobotLab
       apply_prompt_manager!
     end
 
-
     # Apply all RubyLLM settings from the ruby_llm configuration section.
     #
     # @return [void]
@@ -100,7 +98,6 @@ module RobotLab
       set_if_present(c, :vertexai_location, :vertexai_location, 'GOOGLE_CLOUD_LOCATION')
     end
 
-
     def apply_provider_endpoints(c)
       c.openai_api_base = ruby_llm.openai_api_base if ruby_llm.openai_api_base
       c.gemini_api_base = ruby_llm.gemini_api_base if ruby_llm.gemini_api_base
@@ -109,14 +106,12 @@ module RobotLab
       c.xai_api_base = ruby_llm.xai_api_base if ruby_llm.xai_api_base
     end
 
-
     def apply_openai_options(c)
       c.openai_organization_id = ruby_llm.openai_organization_id if ruby_llm.openai_organization_id
       c.openai_project_id = ruby_llm.openai_project_id if ruby_llm.openai_project_id
       c.openai_use_system_role = ruby_llm.openai_use_system_role unless ruby_llm.openai_use_system_role.nil?
     end
 
-
     def apply_default_models(c)
       c.default_model = ruby_llm.default_model if ruby_llm.default_model
       c.default_embedding_model = ruby_llm.default_embedding_model if ruby_llm.default_embedding_model
@@ -124,7 +119,6 @@ module RobotLab
       c.default_moderation_model = ruby_llm.default_moderation_model if ruby_llm.default_moderation_model
     end
 
-
     def apply_connection_settings(c)
       c.request_timeout = ruby_llm.request_timeout if ruby_llm.request_timeout
       c.max_retries = ruby_llm.max_retries if ruby_llm.max_retries
@@ -134,14 +128,12 @@ module RobotLab
       c.http_proxy = ruby_llm.http_proxy if ruby_llm.http_proxy
     end
 
-
     def apply_logging_options(c)
       c.log_file = ruby_llm.log_file if ruby_llm.log_file
       c.log_level = ruby_llm.log_level if ruby_llm.log_level
       c.log_stream_debug = ruby_llm.log_stream_debug unless ruby_llm.log_stream_debug.nil?
     end
 
-
     def apply_prompt_manager!
       path = resolved_template_path
       return unless path
@@ -151,29 +143,26 @@ module RobotLab
       end
     end
 
-
     # Set a RubyLLM config attribute from config value or standard env var.
     # Only sets when a non-nil value is found, to avoid overwriting defaults.
     def set_if_present(c, setter, config_key, env_var)
-      value = ruby_llm.public_send(config_key) || ENV[env_var]
+      value = ruby_llm.public_send(config_key) || ENV.fetch(env_var, nil)
       c.public_send(:"#{setter}=", value) if value
     end
 
-
     def resolved_template_path
       return template_path if template_path
 
-      if defined?(Rails) && Rails.root
-        Rails.root.join('app', 'prompts').to_s
+      if defined?(::Rails) && ::Rails.root
+        ::Rails.root.join('app', 'prompts').to_s
       else
         'prompts'
       end
     end
 
-
     def default_logger
-      if defined?(Rails) && Rails.respond_to?(:logger)
-        Rails.logger
+      if defined?(::Rails) && ::Rails.respond_to?(:logger)
+        ::Rails.logger
       else
         require 'logger'
         Logger.new($stdout, level: Logger::INFO)

data/lib/robot_lab/delegation_future.rb

@@ -70,7 +70,7 @@ module RobotLab
         @result
       end
     end
-    alias_method :wait, :value
+    alias wait value
 
     # @api private — called by Robot#delegate from the worker thread
     def resolve!(result)

data/lib/robot_lab/doom_loop_detector.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Detects and interrupts tool-call doom loops inside the LLM agent loop.
+  #
+  # A doom loop occurs when the LLM repeatedly calls the same tool(s) in a
+  # cycle — either identical consecutive calls (A, A, A) or a repeating
+  # multi-step pattern (A, B, C, A, B, C, A, B, C).
+  #
+  # When a doom loop is detected the warning is embedded in the tool result
+  # so the LLM sees it in its next context window and can self-correct.
+  #
+  # @example Basic usage
+  #   detector = DoomLoopDetector.new(threshold: 3)
+  #   detector.track("search")
+  #   detector.track("search")
+  #   detector.track("search")
+  #   detector.doom_loop?  # => true
+  #   detector.warning_message
+  #   # => "Tool 'search' has been called 3 times consecutively..."
+  class DoomLoopDetector
+    DEFAULT_THRESHOLD = 3
+    MAX_PERIOD = 10
+
+    attr_reader :sequence
+
+    def initialize(threshold: DEFAULT_THRESHOLD)
+      @threshold = threshold
+      @sequence  = []
+    end
+
+    def track(tool_name)
+      @sequence << tool_name.to_s
+    end
+
+    def doom_loop?
+      seq = @sequence
+      return false if seq.length < @threshold
+
+      # Consecutive identical calls: A, A, A
+      tail = seq.last(@threshold)
+      return true if tail.uniq.length == 1
+
+      # Cyclic multi-step patterns: A,B,C, A,B,C, A,B,C
+      max_period = [MAX_PERIOD, seq.length / @threshold].min
+      (2..max_period).each do |period|
+        window = @threshold * period
+        next if seq.length < window
+
+        chunk = seq.last(window)
+        pattern = chunk.first(period)
+        return true if chunk == pattern * @threshold
+      end
+
+      false
+    end
+
+    def reset
+      @sequence = []
+    end
+
+    def warning_message
+      seq = @sequence
+      return "" if seq.empty?
+
+      period = detect_period(seq)
+      if period == 1
+        tool = seq.last
+        "Tool '#{tool}' has been called #{@threshold}+ times consecutively with " \
+          "no progress. You appear to be stuck in a loop. Try a fundamentally " \
+          "different approach, use a different tool, or ask for clarification."
+      else
+        pattern = seq.last(period).join(" → ")
+        "Tool call pattern [#{pattern}] has repeated #{@threshold}+ times. " \
+          "You appear to be stuck in a loop. Try a fundamentally different " \
+          "approach, use a different tool, or ask for clarification."
+      end
+    end
+
+    private
+
+    def detect_period(seq)
+      return 1 if seq.last(@threshold).uniq.length == 1
+
+      max_period = [MAX_PERIOD, seq.length / @threshold].min
+      (2..max_period).each do |period|
+        window = @threshold * period
+        next if seq.length < window
+
+        chunk = seq.last(window)
+        pattern = chunk.first(period)
+        return period if chunk == pattern * @threshold
+      end
+
+      1
+    end
+  end
+end

data/lib/robot_lab/error.rb

@@ -26,9 +26,19 @@ module RobotLab
 
   # Raised when MCP communication fails.
   #
+  # @param retryable [Boolean, nil] opt-in hint for RobotLab::Errors.retryable? —
+  #   set true at the raise site for transient failures (connection drop, timeout)
+  #
   # @example
-  #   raise MCPError, "Connection to MCP server refused"
-  class MCPError < Error; end
+  #   raise MCPError.new("Connection to MCP server refused", retryable: true)
+  class MCPError < Error
+    attr_reader :retryable
+
+    def initialize(message = nil, retryable: nil)
+      @retryable = retryable
+      super(message)
+    end
+  end
 
   # Raised when message bus communication fails.
   #
@@ -36,6 +46,16 @@ module RobotLab
   #   raise BusError, "No bus configured on this robot"
   class BusError < Error; end
 
+  # Raised when a Robot's configured token or cost budget is already
+  # exhausted before an LLM call is attempted (see RobotLab::Budget::Ledger).
+  # Distinct from InferenceError, which covers a call that completed but
+  # pushed cumulative usage over budget — BudgetExceeded means the call
+  # was refused outright.
+  #
+  # @example
+  #   raise BudgetExceeded, "budget exceeded for cost: 0.62 > 0.5"
+  class BudgetExceeded < Error; end
+
   # Raised when a robot's tool call loop exceeds the configured limit.
   #
   # @example
@@ -57,7 +77,17 @@ module RobotLab
 
   # Raised when a tool fails during execution, including inside a Ractor worker.
   #
+  # @param retryable [Boolean, nil] opt-in hint for RobotLab::Errors.retryable? —
+  #   set true at the raise site for transient failures worth retrying
+  #
   # @example
-  #   raise ToolError, "Tool 'MyTool' failed: division by zero"
-  class ToolError < Error; end
+  #   raise ToolError.new("Tool 'MyTool' failed: division by zero")
+  class ToolError < Error
+    attr_reader :retryable
+
+    def initialize(message = nil, retryable: nil)
+      @retryable = retryable
+      super(message)
+    end
+  end
 end