robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/robot_result.rb

@@ -143,8 +143,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      export.to_json(*args)
+    def to_json(*)
+      export.to_json(*)
     end
 
     # Get the last text content from output
@@ -152,9 +152,9 @@ module RobotLab
     # @return [String, nil] The content of the last text message
     #
     def last_text_content
-      output.reverse.find(&:text?)&.content
+      output.rfind(&:text?)&.content
     end
-    alias_method :reply, :last_text_content
+    alias reply last_text_content
 
     # Check if result contains tool calls
     #
@@ -217,7 +217,8 @@ module RobotLab
         when ToolResultMessage
           result
         when Hash
-          result[:type] == "tool_result" ? ToolResultMessage.new(**result.slice(:tool, :content, :stop_reason)) : Message.from_hash(result)
+          result[:type] == "tool_result" ? ToolResultMessage.new(**result.slice(:tool, :content,
+                                                                                :stop_reason)) : Message.from_hash(result)
         else
           raise ArgumentError, "Invalid tool result: must be ToolResultMessage or Hash"
         end

data/lib/robot_lab/run_config.rb

@@ -41,13 +41,15 @@ module RobotLab
     CALLBACK_FIELDS = %i[on_tool_call on_tool_result on_content].freeze
 
     # Infrastructure fields
-    INFRA_FIELDS = %i[bus enable_cache max_tool_rounds token_budget ractor_pool_size max_concurrent_robots].freeze
+    INFRA_FIELDS = %i[bus enable_cache max_tool_rounds token_budget cost_budget ractor_pool_size
+                      max_concurrent_robots doom_loop_threshold auto_compact compact_threshold max_tools].freeze
 
     # All recognized fields
     FIELDS = (LLM_FIELDS + TOOL_FIELDS + CALLBACK_FIELDS + INFRA_FIELDS).freeze
 
     # Fields that cannot be serialized to JSON (Procs, IO objects, etc.)
-    NON_SERIALIZABLE_FIELDS = (CALLBACK_FIELDS + %i[bus]).freeze
+    # auto_compact is excluded because it may be a Proc.
+    NON_SERIALIZABLE_FIELDS = (CALLBACK_FIELDS + %i[bus auto_compact]).freeze
 
     # Creates a new RunConfig.
     #
@@ -85,15 +87,13 @@ module RobotLab
       @fields.dup
     end
 
-
     # Returns a JSON-safe hash (skips Procs, IO, and other non-serializable values).
     #
     # @return [Hash]
     def to_json_hash
-      @fields.reject { |k, _| NON_SERIALIZABLE_FIELDS.include?(k) }
+      @fields.except(*NON_SERIALIZABLE_FIELDS)
     end
 
-
     # Merges another RunConfig (or Hash) on top of this one.
     # The other's non-nil values win. Returns a new RunConfig.
     #
@@ -105,21 +105,38 @@ module RobotLab
       self.class.new(**merged)
     end
 
-
     # Applies LLM fields to a chat object via its with_* methods.
     #
+    # +provider+/+assume_model_exists+ are threaded through to +with_model+
+    # specifically (RunConfig itself has no provider field -- provider lives
+    # on the Robot). Without this, re-applying a RunConfig after the chat's
+    # provider/model were already set via Robot#initialize (e.g. during
+    # template front-matter merging) drops that context on the floor and
+    # `with_model` falls back to the static model registry lookup, which
+    # raises ModelNotFoundError for any local-provider model (Ollama, etc.)
+    # not in RubyLLM's bundled registry.
+    #
     # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
-    def apply_to(chat)
+    # @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
+    def apply_to(chat, provider: nil, assume_model_exists: false)
       LLM_FIELDS.each do |field|
         value = @fields[field]
         next unless value
 
-        method = :"with_#{field}"
-        chat.public_send(method, value) if chat.respond_to?(method)
+        if field == :model && provider
+          # Only take the provider-aware path when a provider was actually
+          # given -- preserves the original single-arg call (and thus
+          # compatibility with any chat-like object exposing only
+          # `with_model(value)`) for the common case.
+          chat.with_model(value, provider:, assume_exists: assume_model_exists) if chat.respond_to?(:with_model)
+        else
+          method = :"with_#{field}"
+          chat.public_send(method, value) if chat.respond_to?(method)
+        end
       end
     end
 
-
     # Build a RunConfig from prompt_manager front matter metadata.
     #
     # @param metadata [Object] a PM::Metadata object (responds to field names)
@@ -141,27 +158,23 @@ module RobotLab
       new(**fields)
     end
 
-
     # @return [Boolean] true if no fields have been set
     def empty?
       @fields.empty?
     end
 
-
     # @param field [Symbol] the field name
     # @return [Boolean] true if the field has been explicitly set
     def key?(field)
       @fields.key?(field)
     end
 
-
     # @param other [RunConfig] the other RunConfig to compare
     # @return [Boolean]
     def ==(other)
       other.is_a?(RunConfig) && to_h == other.to_h
     end
 
-
     # @return [String]
     def inspect
       "#<#{self.class} #{@fields.inspect}>"

data/lib/robot_lab/runnable.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Shared interface for things you can run with a message: a single {Robot} or a
+  # multi-robot {Network}. It lets callers treat them uniformly instead of
+  # branching on `is_a?(RobotLab::Network)` — which otherwise spreads concrete
+  # type knowledge across every consumer.
+  #
+  # Implementers provide:
+  #   - #run(message = nil, **opts) — execute with the given message (both Robot
+  #     and Network accept a positional message and keyword options)
+  #   - #crew                       — the constituent robots, as an Array
+  #   - #network?                   — true for a multi-robot network
+  #
+  # The rest (chief, robot_count, single?) derive from those.
+  #
+  # @example treat either uniformly
+  #   runnable.run(prompt, mcp: :inherit, tools: :inherit)
+  #   names = runnable.crew.map(&:name)
+  #   show_network(runnable) if runnable.network?
+  module Runnable
+    # The constituent robots as an Array. A single Robot is a crew of one.
+    #
+    # @return [Array<Robot>]
+    def crew
+      raise NotImplementedError, "#{self.class} must implement #crew"
+    end
+
+    # The lead robot — the chief of the crew.
+    #
+    # @return [Robot, nil]
+    def chief
+      crew.first
+    end
+
+    # @return [Integer] number of constituent robots
+    def robot_count
+      crew.size
+    end
+
+    # @return [Boolean] true for a multi-robot network
+    def network?
+      false
+    end
+
+    # @return [Boolean] true for a single robot
+    def single?
+      !network?
+    end
+  end
+end

data/lib/robot_lab/sandbox/null.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Sandbox
+    # Passthrough strategy: runs the command with no confinement. Used when
+    # sandboxing is unavailable (non-macOS) or unnecessary (trust: core).
+    class Null
+      def wrap(cmd) = cmd
+
+      def cleanup; end
+    end
+  end
+end

data/lib/robot_lab/sandbox/seatbelt.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module RobotLab
+  module Sandbox
+    # macOS strategy: generates a deny-by-default sandbox-exec profile from the
+    # effective grant and wraps the command as
+    #   sandbox-exec -f <profile> <cmd...>
+    #
+    # The profile allows process exec plus reads of system locations (so the
+    # interpreter can load), reads of the skill bundle and granted paths, writes
+    # only to granted paths (and the standard /dev sinks), and network only when
+    # granted. Everything else -- notably $HOME, so SSH/cloud credentials --
+    # is denied. Interpreters installed under $HOME (e.g. rbenv) are not visible;
+    # declare them in fs_read or mark the skill trust: core.
+    class Seatbelt
+      # System locations a typical interpreter needs to read to start up.
+      SYSTEM_READ = %w[/usr /bin /sbin /System /Library /opt /private/etc /dev /var/select].freeze
+      DEV_WRITE   = %w[/dev/null /dev/stdout /dev/stderr /dev/dtracehelper /dev/tty].freeze
+
+      def initialize(grant, skill_dir:)
+        @grant     = grant
+        @skill_dir = File.expand_path(skill_dir.to_s)
+        @profile   = nil
+      end
+
+      def wrap(cmd)
+        @profile = write_profile
+        ["sandbox-exec", "-f", @profile, *cmd]
+      end
+
+      def cleanup
+        File.unlink(@profile) if @profile && File.exist?(@profile)
+      rescue StandardError
+        nil
+      end
+
+      # The generated Seatbelt profile text (public for testing).
+      def profile_text
+        reads  = canonicalize(SYSTEM_READ + [@skill_dir] + @grant.fs_read)
+        writes = canonicalize(@grant.fs_write)
+        lines = [
+          "(version 1)",
+          # bsd.sb supplies the base rules a process needs to start (dyld, mach
+          # bootstrap, etc.); without it a deny-default profile aborts the binary.
+          '(import "bsd.sb")',
+          "(deny default)",
+          "(allow process-fork)",
+          "(allow process-exec)",
+          "(allow sysctl-read)",
+          "(allow mach-lookup)",
+          # Metadata (stat/lookup) on any path so the interpreter can traverse to
+          # granted files; reading file *contents* stays restricted below.
+          "(allow file-read-metadata)",
+          read_rule(reads),
+          write_rule(DEV_WRITE.map { |p| [:literal, p] } + writes.map { |p| [:subpath, p] })
+        ]
+        lines << "(allow network*)" if @grant.network
+        "#{lines.compact.join("\n")}\n"
+      end
+
+      private
+
+      def write_profile
+        file = Tempfile.create(["robot_lab-sandbox-", ".sb"])
+        file.write(profile_text)
+        file.close
+        file.path
+      end
+
+      # Resolve to the real (symlink-free) path the kernel matches against. macOS
+      # symlinks /tmp -> /private/tmp, /var -> /private/var, etc., so logical
+      # paths would never match. For not-yet-existing write targets, resolve the
+      # nearest existing ancestor and re-append the remainder.
+      def canonicalize(paths)
+        Array(paths).map { |p| real_path(File.expand_path(p.to_s)) }.compact.uniq
+      end
+
+      def real_path(expanded)
+        existing = expanded
+        rest     = []
+        until File.exist?(existing) || existing == "/"
+          rest.unshift(File.basename(existing))
+          existing = File.dirname(existing)
+        end
+        real = File.realpath(existing)
+        rest.empty? ? real : File.join(real, *rest)
+      rescue StandardError
+        expanded
+      end
+
+      def read_rule(paths)
+        subpaths = paths.map { |p| "(subpath #{p.inspect})" }.join(" ")
+        "(allow file-read* #{subpaths})"
+      end
+
+      def write_rule(entries)
+        clauses = entries.map { |kind, p| "(#{kind} #{p.inspect})" }.join(" ")
+        "(allow file-write* #{clauses})"
+      end
+    end
+  end
+end

data/lib/robot_lab/sandbox.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Confines skill-script execution to a granted set of capabilities.
+  #
+  # Sandboxing is opt-in (config.sandbox.enabled). When off, every script runs
+  # unconfined exactly as before. When on, each script runs under a strategy:
+  #
+  # - {Sandbox::Seatbelt} on macOS — a generated deny-by-default sandbox-exec
+  #   profile derived from the effective {Capabilities} grant.
+  # - {Sandbox::Null} elsewhere (or for +trust: core+ skills) — a passthrough.
+  #
+  # OS-level confinement is therefore best-effort and platform-specific; it is
+  # never a hard dependency.
+  module Sandbox
+    module_function
+
+    # @return [Boolean] whether sandboxing is turned on in config
+    def enabled?(config = RobotLab.config)
+      config.respond_to?(:sandbox) && config.sandbox && config.sandbox.enabled == true
+    end
+
+    def macos?
+      RUBY_PLATFORM.include?("darwin")
+    end
+
+    # Pick a strategy for the given (already-intersected) grant.
+    #
+    # @param grant [Capabilities] effective grant
+    # @param skill_dir [String] skill bundle root, always granted read access
+    # @param macos [Boolean] whether to use the macOS strategy; defaults to the
+    #   real platform check and is injectable so both branches are testable on
+    #   any host without stubbing.
+    # @return [#wrap, #cleanup]
+    def for(grant, skill_dir:, macos: macos?)
+      return Null.new if grant.core?
+      return Seatbelt.new(grant, skill_dir: skill_dir) if macos
+
+      warn_once_non_macos
+      Null.new
+    end
+
+    def warn_once_non_macos
+      return if @warned_non_macos
+
+      @warned_non_macos = true
+      RobotLab.config.logger.warn(
+        "Sandbox: OS-level confinement is only available on macOS; scripts run unconfined here"
+      )
+    end
+  end
+end

data/lib/robot_lab/script_tool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'shellwords'
+require 'timeout'
+
+module RobotLab
+  # Factory module for wrapping AgentSkills scripts as RobotLab::Tool instances.
+  #
+  # 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.
+  module ScriptTool
+    # Wrap a script file as a RobotLab::Tool.
+    #
+    # @param script_path [String, Pathname] path to the script file
+    # @return [RobotLab::Tool, nil] nil if the script is not executable
+    # @param script_path [String, Pathname] path to the script file
+    # @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
+    def self.from_path(script_path, capabilities: nil, skill_dir: nil)
+      path = Pathname.new(script_path)
+
+      unless path.executable?
+        RobotLab.config.logger.warn(
+          "ScriptTool: #{path.basename} is not executable, skipping"
+        )
+        return nil
+      end
+
+      tool_name   = derive_name(path)
+      description = extract_description(path)
+      script      = path.to_s
+      caps        = capabilities || Capabilities.new
+      dir         = skill_dir || path.dirname.to_s
+
+      Tool.create(
+        name: tool_name,
+        description: description,
+        parameters: {
+          type: 'object',
+          properties: {
+            args: { type: 'string', description: 'Optional command-line arguments' }
+          },
+          required: []
+        }
+      ) do |tool_args|
+        cli_args = tool_args[:args].to_s.strip
+        cmd      = cli_args.empty? ? ['bash', script] : ['bash', script, *Shellwords.split(cli_args)]
+        ScriptTool.execute(cmd, capabilities: caps, skill_dir: dir)
+      end
+    end
+
+    # Run a command, optionally confined by the sandbox and a timeout.
+    #
+    # 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.
+    #
+    # @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
+
+      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
+    end
+
+    # @param status [Process::Status, nil] nil indicates a timeout kill
+    def self.format_result(output, status)
+      return "Error (timed out):\n#{output}" if status.nil?
+
+      status.success? ? output : "Error (exit #{status.exitstatus}):\n#{output}"
+    end
+
+    # @param path [Pathname]
+    # @return [String] snake_case tool name derived from filename
+    def self.derive_name(path)
+      path.basename.to_s
+          .sub(/\.[^.]+$/, '')
+          .gsub(/[^a-zA-Z0-9]+/, '_')
+          .gsub(/^_+|_+$/, '')
+    end
+
+    # Extract tool description from the first non-shebang comment line.
+    #
+    # @param path [Pathname]
+    # @return [String]
+    def self.extract_description(path)
+      File.foreach(path) do |line|
+        stripped = line.strip
+        next unless stripped.start_with?('#')
+        next if stripped.start_with?('#!') # skip shebang
+
+        desc = stripped.sub(/^#+\s*/, '').strip
+        return desc unless desc.empty?
+      end
+      derive_name(path)
+    rescue StandardError
+      derive_name(path)
+    end
+  end
+end

data/lib/robot_lab/state_proxy.rb

@@ -46,7 +46,6 @@ module RobotLab
       old_value = @data[key]
       @data[key] = value
       @on_change&.call(key, old_value, value) if old_value != value
-      value
     end
 
     # Check if key exists
@@ -85,8 +84,12 @@ module RobotLab
     #
     # @yield [Symbol, Object]
     #
-    def each(&block)
-      @data.each(&block)
+    def each(&)
+      @data.each(&)
+    end
+
+    def map(&)
+      @data.map(&)
     end
 
     # Delete a key
@@ -155,7 +158,7 @@ module RobotLab
     #   proxy.name        # Same as proxy[:name]
     #   proxy.name = "x"  # Same as proxy[:name] = "x"
     #
-    def method_missing(method_name, *args, &block)
+    def method_missing(method_name, *args, &)
       method_str = method_name.to_s
 
       if method_str.end_with?("=")
@@ -173,6 +176,5 @@ module RobotLab
     def inspect
       "#<RobotLab::StateProxy #{@data.inspect}>"
     end
-
   end
 end

data/lib/robot_lab/task.rb

@@ -39,7 +39,7 @@ module RobotLab
     # @param tools [Symbol, Array] tools config (:none, :inherit, or array)
     # @param memory [Memory, Hash, nil] task-specific memory
     #
-    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil, config: nil)
+    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, network: nil)
       @name = name.to_sym
       @robot = robot
       @context = context
@@ -47,6 +47,7 @@ module RobotLab
       @tools = tools
       @memory = memory
       @config = config
+      @network = network
     end
 
     # SimpleFlow step interface
@@ -58,28 +59,17 @@ module RobotLab
     # @return [SimpleFlow::Result] result with robot output
     #
     def call(result)
-      # Get current run params and deep merge with task context
-      run_params = deep_merge(
-        result.context[:run_params] || {},
-        @context
+      context = TaskHookContext.new(
+        network: @network,
+        task: self,
+        robot: @robot,
+        memory: @memory || @network&.memory,
+        config: @config
       )
 
-      # Add task-specific robot config
-      run_params[:mcp] = @mcp unless @mcp == :none
-      run_params[:tools] = @tools unless @tools == :none
-      run_params[:memory] = @memory if @memory
-
-      # Merge task's config on top of network's config
-      if @config
-        network_rc = run_params[:network_config]
-        run_params[:network_config] = network_rc ? network_rc.merge(@config) : @config
+      RobotLab::Hooks.run(:task, context, registries: [RobotLab.hooks, @network&.hooks]) do
+        @robot.call(enhanced_result(result))
       end
-
-      # Create enhanced result with merged params
-      enhanced_result = result.with_context(:run_params, run_params)
-
-      # Delegate to robot
-      @robot.call(enhanced_result)
     end
 
     # Converts the task to a hash representation.
@@ -99,6 +89,22 @@ module RobotLab
 
     private
 
+    def enhanced_result(result)
+      run_params = deep_merge(result.context[:run_params] || {}, @context)
+      run_params[:mcp] = @mcp unless @mcp == :none
+      run_params[:tools] = @tools unless @tools == :none
+      run_params[:memory] = @memory if @memory
+      run_params[:task] = self
+      run_params[:network] = @network if @network
+
+      if @config
+        network_rc = run_params[:network_config]
+        run_params[:network_config] = network_rc ? network_rc.merge(@config) : @config
+      end
+
+      result.with_context(:run_params, run_params)
+    end
+
     # Deep merge two hashes
     #
     # Values from `override` take precedence. Nested hashes are merged