robot_lab 0.2.1 → 0.2.6

data/lib/robot_lab/agent_skill.rb

@@ -8,7 +8,7 @@ module RobotLab
   # 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
+    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
@@ -17,8 +17,9 @@ module RobotLab
       content = File.read(skill_md_path)
       front_matter, @_body = parse_skill_md(content)
 
-      @name        = front_matter["name"]
-      @description = front_matter["description"]
+      @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?
@@ -41,7 +42,7 @@ module RobotLab
     # Non-executable scripts are skipped with a warning.
     def script_tools
       @script_tools ||= scripts.filter_map do |script_path|
-        ScriptTool.from_path(script_path)
+        ScriptTool.from_path(script_path, capabilities: @capabilities, skill_dir: @path.to_s)
       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/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

@@ -153,16 +153,16 @@ module RobotLab
     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/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

data/lib/robot_lab/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Classification surface for "should this error be retried?" — so hosts
+  # (ActiveJob retry_on lists, robot_lab-to's takeover loop, custom retry
+  # wrappers) don't reimplement the same case statement against RobotLab's
+  # error hierarchy.
+  #
+  # - +InferenceError+ (transient LLM/API failures) is always retryable,
+  #   except its more specific subclass +ToolLoopError+ (a circuit breaker
+  #   tripped by a repeating tool-call pattern — retrying immediately would
+  #   just re-trigger the same loop).
+  # - +MCPError+ and +ToolError+ are opt-in: retryable only when raised
+  #   with +retryable: true+, since some instances are transient (a
+  #   connection drop, a timeout) and some are not (an explicit rejection
+  #   from the server or tool).
+  # - Everything else (+ConfigurationError+, +ToolNotFoundError+,
+  #   +DependencyError+, +RactorBoundaryError+, +BusError+, and any
+  #   non-RobotLab error) is never retryable.
+  module Errors
+    # @param error [Exception, nil]
+    # @return [Boolean] true when the host should retry the operation that raised +error+
+    def self.retryable?(error)
+      return false if error.nil? || error.is_a?(RobotLab::ToolLoopError)
+
+      case error
+      when RobotLab::MCPError, RobotLab::ToolError
+        error.respond_to?(:retryable) && error.retryable == true
+      when RobotLab::InferenceError
+        true
+      else
+        false
+      end
+    end
+
+    # Always-retryable error classes, for explicit ActiveJob-style
+    # +retry_on+ allow-lists. Excludes +MCPError+/+ToolError+ because
+    # their retryability is per-raise (via +retryable:+), not per-class.
+    #
+    # @return [Array<Class>]
+    def self.retryable_classes
+      [RobotLab::InferenceError].freeze
+    end
+  end
+end

data/lib/robot_lab/hook.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Base class for hook handlers.
+  #
+  # Subclasses implement class methods for each hook they handle.
+  # Unimplemented hooks are silently skipped; around hooks passthrough
+  # automatically so the chain never breaks.
+  #
+  # The namespace defaults to the snake_case form of the last segment of the
+  # class name (e.g. TokenLogger -> :token_logger). Override with
+  # `self.namespace = :custom` when needed.
+  #
+  # @example
+  #   class AuditHook < RobotLab::Hook
+  #     def self.before_run(ctx)
+  #       ctx.local.started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  #     end
+  #
+  #     def self.after_run(ctx)
+  #       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx.local.started_at
+  #       puts "[#{ctx.robot.name}] #{(elapsed * 1000).round(1)}ms"
+  #     end
+  #
+  #     def self.on_error(ctx)
+  #       puts "[#{ctx.robot.name}] ERROR: #{ctx.error.message}"
+  #     end
+  #   end
+  #
+  #   RobotLab.on(AuditHook)
+  #   robot.on(AuditHook)
+  #   network.on(AuditHook)
+  #
+  class Hook
+    @namespace = nil
+
+    class << self
+      attr_writer :namespace
+
+      # Returns the hook's namespace symbol, derived from the class name by
+      # default. Returns nil for the base Hook class itself.
+      #
+      # @return [Symbol, nil]
+      def namespace
+        return @namespace if @namespace
+        return nil if self == Hook
+
+        name.split('::').last
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+            .to_sym
+      end
+
+      # Dispatch a single hook to this handler.
+      #
+      # If the handler implements the method it is called. For around hooks that
+      # are not implemented the block is called directly (passthrough). Non-around
+      # hooks that are not implemented are silent no-ops.
+      #
+      # @param hook_name [Symbol] e.g. :before_run, :around_tool_call
+      # @param context [HookContext] the hook context object
+      # @yield for around hooks — the next link in the chain
+      def call(hook_name, context, &block)
+        if singleton_class.public_method_defined?(hook_name)
+          block ? public_send(hook_name, context, &block)
+                : public_send(hook_name, context)
+        elsif block
+          block.call
+        end
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@namespace, nil)
+      end
+    end
+  end
+end

data/lib/robot_lab/hook_context.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class HookContext
+    attr_reader :event, :metadata
+
+    def initialize(event:, metadata: nil)
+      @event = event.to_sym
+      @metadata = metadata || ExtensionState.new
+    end
+
+    def ext(name)
+      metadata.ext(name)
+    end
+
+    def local
+      raise ArgumentError, "No hook namespace active" unless @namespace
+
+      ext(@namespace)
+    end
+
+    def with_namespace(namespace)
+      previous = @namespace
+      @namespace = namespace&.to_sym
+      yield self
+    ensure
+      @namespace = previous
+    end
+
+    def to_h
+      public_snapshot.merge(metadata: metadata.to_h)
+    end
+
+    private
+
+    def public_snapshot
+      public_methods(false)
+        .grep_v(/=\z/)
+        .reject { |name| %i[to_h local].include?(name) }
+        .sort
+        .to_h { |name| [name, public_send(name)] }
+    end
+  end
+
+  class RunHookContext < HookContext
+    attr_reader :robot, :network, :task, :memory, :config
+    attr_accessor :request, :response, :error
+
+    def initialize(robot:, request:, network: nil, task: nil, memory: nil, config: nil, response: nil, error: nil, **)
+      super(event: :run, **)
+      @robot = robot
+      @network = network
+      @task = task
+      @memory = memory
+      @config = config
+      @request = request
+      @response = response
+      @error = error
+    end
+  end
+
+  class LlmGenerationHookContext < RunHookContext
+    attr_reader :iteration
+    attr_accessor :generation_response
+
+    def initialize(iteration: 0, generation_response: nil, **)
+      super(**)
+      @iteration = iteration
+      @generation_response = generation_response
+    end
+  end
+
+  class ToolCallHookContext < HookContext
+    attr_reader :tool, :tool_name, :tool_args, :robot
+    attr_accessor :tool_result, :tool_error
+
+    def initialize(tool:, tool_args:, robot: nil, tool_result: nil, tool_error: nil, **)
+      super(event: :tool_call, **)
+      @tool = tool
+      @tool_name = tool.respond_to?(:name) ? tool.name : tool.class.name
+      @tool_args = tool_args
+      @robot = robot
+      @tool_result = tool_result
+      @tool_error = tool_error
+    end
+  end
+
+  class NetworkRunHookContext < HookContext
+    attr_reader :network, :memory, :config
+    attr_accessor :context, :result, :error
+
+    def initialize(network:, context:, memory: nil, config: nil, result: nil, error: nil, **)
+      super(event: :network_run, **)
+      @network = network
+      @context = context
+      @memory = memory
+      @config = config
+      @result = result
+      @error = error
+    end
+  end
+
+  class TaskHookContext < HookContext
+    attr_reader :network, :task, :task_name, :robot, :memory, :config
+    attr_accessor :result, :error
+
+    def initialize(task:, network: nil, robot: nil, memory: nil, config: nil, result: nil, error: nil, **)
+      super(event: :task, **)
+      @network = network
+      @task = task
+      @task_name = task.name
+      @robot = robot || task.robot
+      @memory = memory
+      @config = config
+      @result = result
+      @error = error
+    end
+  end
+
+  class LearnHookContext < HookContext
+    attr_reader :robot, :text, :learnings_before
+    attr_accessor :stored, :error
+
+    def initialize(robot:, text:, learnings_before:, **)
+      super(event: :learn, **)
+      @robot            = robot
+      @text             = text
+      @learnings_before = learnings_before.freeze
+      @stored           = false
+    end
+  end
+
+  class CompactionHookContext < HookContext
+    attr_reader :robot, :messages_before, :config, :strategy
+    attr_accessor :compacted_messages, :error
+
+    def initialize(robot:, messages_before:, config:, strategy:, **)
+      super(event: :compaction, **)
+      @robot            = robot
+      @messages_before  = messages_before.freeze
+      @config           = config
+      @strategy         = strategy
+      @compacted_messages = nil
+    end
+
+    # True once an on_compaction handler has supplied a replacement message set.
+    def handled?
+      !@compacted_messages.nil?
+    end
+  end
+
+  class ExtensionState
+    def initialize
+      @states = Hash.new { |h, key| h[key] = DotState.new }
+    end
+
+    def ext(name)
+      @states[name.to_sym]
+    end
+
+    def to_h
+      @states.transform_values(&:to_h)
+    end
+  end
+
+  class DotState
+    def initialize
+      @data = {}
+    end
+
+    def merge_defaults(hash)
+      hash.each { |k, v| @data[k.to_sym] = v unless @data.key?(k.to_sym) }
+      self
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s.delete_suffix('=').to_sym
+
+      if name.to_s.end_with?('=')
+        @data[key] = args.first
+      else
+        @data[key]
+      end
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
+    def to_h
+      @data.dup
+    end
+  end
+end

data/lib/robot_lab/hook_registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class HookRegistry
+    Registration = Data.define(:handler_class, :context) do
+      def initialize(handler_class:, context: nil)
+        super
+      end
+
+      def namespace
+        handler_class.namespace
+      end
+    end
+
+    def initialize
+      @registrations = []
+    end
+
+    # Register a hook handler class.
+    #
+    # @param handler_class [Class] a RobotLab::Hook subclass
+    # @param context [Hash, nil] optional default values merged into ctx.local on each call
+    # @return [Registration]
+    def on(handler_class, context: nil)
+      unless handler_class.is_a?(Class) && handler_class < RobotLab::Hook
+        raise ArgumentError, "#{handler_class.inspect} must be a RobotLab::Hook subclass"
+      end
+      raise ArgumentError, "#{handler_class} has no namespace" if handler_class.namespace.nil?
+
+      registration = Registration.new(handler_class: handler_class, context: context)
+      @registrations << registration
+      registration
+    end
+
+    # Returns registrations whose handler implements the given hook method.
+    #
+    # @param hook_name [Symbol]
+    # @return [Array<Registration>]
+    def registrations_for(hook_name)
+      hook_sym = hook_name.to_sym
+      @registrations.select { |reg| reg.handler_class.singleton_class.public_method_defined?(hook_sym) }
+    end
+
+    # Returns all registrations (defensive copy).
+    #
+    # @return [Array<Registration>]
+    def registrations
+      @registrations.dup
+    end
+
+    def clear
+      @registrations.clear
+    end
+  end
+end