robot_lab 0.2.1 → 0.2.7

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

@@ -2,6 +2,7 @@
 
 require 'open3'
 require 'shellwords'
+require 'timeout'
 
 module RobotLab
   # Factory module for wrapping AgentSkills scripts as RobotLab::Tool instances.
@@ -14,7 +15,11 @@ module RobotLab
     #
     # @param script_path [String, Pathname] path to the script file
     # @return [RobotLab::Tool, nil] nil if the script is not executable
-    def self.from_path(script_path)
+    # @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?
@@ -27,6 +32,8 @@ module RobotLab
       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,
@@ -41,11 +48,62 @@ module RobotLab
       ) 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)
-        status.success? ? output : "Error (exit #{status.exitstatus}):\n#{output}"
+        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)

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

data/lib/robot_lab/tool.rb

@@ -94,19 +94,17 @@ module RobotLab
     # @param args [Hash] the tool arguments from the LLM
     # @return [Object] the tool result or an error string
     def call(args)
-      if self.class.ractor_safe? && !self.class.name.nil? && RobotLab.extension_loaded?(:ractor)
-        RobotLab.ractor_pool.submit(self.class.name, args)
-      else
-        super
+      context = ToolCallHookContext.new(tool: self, tool_args: args, robot: @robot)
+
+      RobotLab::Hooks.run(:tool_call, context, **tool_hook_options) do
+        context.tool_result = use_ractor_pool? ? execute_ractor_tool_call(args) : super
+      rescue RobotLab::ToolError => e
+        handle_tool_error(context, e)
+      rescue StandardError => e
+        handle_standard_error(context, e)
       end
-    rescue RobotLab::ToolError => e
-      raise if self.class.raise_on_error?
-      "Error (#{name}): #{e.message}"
-    rescue StandardError => e
-      raise if self.class.raise_on_error?
 
-      RobotLab.config.logger.warn("Tool '#{name}' error: #{e.class}: #{e.message}")
-      "Error (#{name}): #{e.message}"
+      context.tool_result
     end
 
     # Override name to support explicit names for dynamic/MCP tools.
@@ -210,6 +208,49 @@ module RobotLab
 
     private
 
+    def tool_hook_options
+      hook_scope = RobotLab.current_hook_scope
+
+      {
+        registries: tool_hook_registries(hook_scope),
+        per_run_hooks: hook_scope && hook_scope[:per_run_hooks]
+      }
+    end
+
+    def tool_hook_registries(hook_scope)
+      return hook_scope[:registries] if hook_scope
+
+      [RobotLab.hooks, robot_hook_registry]
+    end
+
+    def robot_hook_registry
+      @robot.hooks if @robot.respond_to?(:hooks)
+    end
+
+    def execute_ractor_tool_call(args)
+      RobotLab.ractor_pool.submit(self.class.name, args)
+    end
+
+    def use_ractor_pool?
+      self.class.ractor_safe? && !self.class.name.nil? && RobotLab.extension_loaded?(:ractor)
+    end
+
+    def handle_tool_error(context, error)
+      context.tool_error = error
+      raise if self.class.raise_on_error?
+
+      suffix = RobotLab::Errors.retryable?(error) ? " (retryable)" : ""
+      context.tool_result = "Error (#{name}): #{error.message}#{suffix}"
+    end
+
+    def handle_standard_error(context, error)
+      context.tool_error = error
+      raise if self.class.raise_on_error?
+
+      RobotLab.config.logger.warn("Tool '#{name}' error: #{error.class}: #{error.message}")
+      context.tool_result = "Error (#{name}): #{error.message}"
+    end
+
     def deep_symbolize_keys(obj)
       case obj
       when Hash

data/lib/robot_lab/version.rb

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

data/lib/robot_lab.rb

@@ -24,9 +24,9 @@ require 'typed_bus'
 #
 # @example Creating a network of robots
 #   network = RobotLab.create_network(name: "pipeline") do
-#     step :analyzer, analyzer, depends_on: :none
-#     step :writer, writer, depends_on: [:analyzer]
-#     step :reviewer, reviewer, depends_on: [:writer]
+#     task :analyzer, analyzer, depends_on: :none
+#     task :writer, writer, depends_on: [:analyzer]
+#     task :reviewer, reviewer, depends_on: [:writer]
 #   end
 #   result = network.run(message: "Process this document")
 #
@@ -35,7 +35,7 @@ require 'typed_bus'
 #   # ROBOT_LAB_DEFAULT_MODEL=gpt-4
 #   # ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
 #
-#   # Or via config files (~/.config/robot_lab/config.yml or ./config/robot_lab.yml)
+#   # Or via config files (~/.config/robot_lab/robot_lab.yml or ./config/robot_lab.yml)
 #   # See lib/robot_lab/config/defaults.yml for all options
 #
 #   # Access configuration values:
@@ -47,6 +47,7 @@ end
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore("#{__dir__}/robot_lab/robot")
+loader.ignore("#{__dir__}/robot_lab/names.rb")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
 loader.inflector.inflect(
@@ -64,9 +65,18 @@ loader.setup
 # individually (e.g. TextMessage lives in message.rb, not text_message.rb).
 # Require them explicitly so their constants are available without eager loading.
 require_relative 'robot_lab/error'
+require_relative 'robot_lab/hook_context'
+require_relative 'robot_lab/hook'
+require_relative 'robot_lab/hook_registry'
+require_relative 'robot_lab/hooks'
 require_relative 'robot_lab/message'
 require_relative 'robot_lab/memory'
 
+# names.rb defines the NAMES data constant plus helper methods directly on
+# RobotLab, not a RobotLab::Names class/module, so Zeitwerk can't autoload it
+# by convention — ignored above and required explicitly instead.
+require_relative 'robot_lab/names'
+
 # Eager load everything in Rails or when explicitly requested.
 # Otherwise Zeitwerk's lazy autoloading keeps boot fast.
 loader.eager_load if defined?(Rails::Engine) || ENV["ROBOT_LAB_EAGER_LOAD"]
@@ -109,12 +119,39 @@ module RobotLab
       @extensions.keys
     end
 
+    def hooks
+      @hooks ||= HookRegistry.new
+    end
+
+    def on(handler_class, context: nil)
+      hooks.on(handler_class, context: context)
+    end
+
+    def clear_hooks!
+      @hooks = HookRegistry.new
+    end
+
+    def with_hook_scope(registries, per_run_hooks)
+      previous = Thread.current[:robot_lab_hook_scope]
+      Thread.current[:robot_lab_hook_scope] = {
+        registries: registries,
+        per_run_hooks: per_run_hooks
+      }
+      yield
+    ensure
+      Thread.current[:robot_lab_hook_scope] = previous
+    end
+
+    def current_hook_scope
+      Thread.current[:robot_lab_hook_scope]
+    end
+
     # Returns the Config object (MywayConfig-based).
     #
     # Configuration is automatically loaded from:
     # - Bundled defaults (lib/robot_lab/config/defaults.yml)
     # - Environment-specific overrides (development, test, production)
-    # - XDG config files (~/.config/robot_lab/config.yml)
+    # - XDG config file (~/.config/robot_lab/robot_lab.yml)
     # - Project config (./config/robot_lab.yml)
     # - Environment variables (ROBOT_LAB_*)
     #
@@ -152,6 +189,24 @@ module RobotLab
       config
     end
 
+    # Render a named prompt template to a String using the configured template
+    # library (the prompts_dir from config / ROBOT_LAB_TEMPLATE_PATH). Front
+    # matter parameters are supplied as keyword arguments.
+    #
+    # Unlike #build (which renders a template as a robot's *system prompt*), this
+    # returns the plain text, so callers can use it as a task, a message, or a
+    # grading rubric.
+    #
+    # @param name [Symbol, String] template id (filename without extension)
+    # @param context [Hash] values for the template's parameters
+    # @return [String] the rendered prompt text
+    #
+    # @example
+    #   RobotLab.render_template(:objective, topic: "commit messages")
+    def render_template(name, **context)
+      PM.parse(name.to_sym).to_s(**context)
+    end
+
     # Factory method to create a new Robot instance.
     #
     # @param name [String, nil] the unique identifier for the robot (auto-generated if nil)
@@ -197,28 +252,28 @@ module RobotLab
     #
     # @param name [String] the unique identifier for the network
     # @param concurrency [Symbol] concurrency model (:auto, :threads, :async)
-    # @yield Block for defining pipeline steps
+    # @yield Block for defining pipeline tasks (the DSL method is `task`)
     # @return [Network] a new Network instance
     #
     # @example Sequential pipeline
     #   network = RobotLab.create_network(name: "pipeline") do
-    #     step :first, robot1, depends_on: :none
-    #     step :second, robot2, depends_on: [:first]
+    #     task :first, robot1, depends_on: :none
+    #     task :second, robot2, depends_on: [:first]
     #   end
     #
     # @example With optional routing
     #   network = RobotLab.create_network(name: "support") do
-    #     step :classifier, classifier, depends_on: :none
-    #     step :billing, billing_robot, depends_on: :optional
-    #     step :technical, technical_robot, depends_on: :optional
+    #     task :classifier, classifier, depends_on: :none
+    #     task :billing, billing_robot, depends_on: :optional
+    #     task :technical, technical_robot, depends_on: :optional
     #   end
     #
     # @example Parallel execution
     #   network = RobotLab.create_network(name: "analysis") do
-    #     step :fetch, fetcher, depends_on: :none
-    #     step :sentiment, sentiment_bot, depends_on: [:fetch]
-    #     step :entities, entity_bot, depends_on: [:fetch]
-    #     step :merge, merger, depends_on: [:sentiment, :entities]
+    #     task :fetch, fetcher, depends_on: :none
+    #     task :sentiment, sentiment_bot, depends_on: [:fetch]
+    #     task :entities, entity_bot, depends_on: [:fetch]
+    #     task :merge, merger, depends_on: [:sentiment, :entities]
     #   end
     def create_network(name:, concurrency: :auto, config: nil, &)
       Network.new(name: name, concurrency: concurrency, config: config, &)

data/mkdocs.yml

@@ -170,16 +170,22 @@ nav:
       - Streaming Responses: guides/streaming.md
       - Memory System: guides/memory.md
       - Observability & Safety: guides/observability.md
+      - Hook System: guides/hooks.md
       - Knowledge Search: guides/knowledge.md
   - API Reference:
       - api/index.md
       - Core Classes:
           - api/core/index.md
           - Robot: api/core/robot.md
+          - RobotResult: api/core/result.md
           - Network: api/core/network.md
-          - State: api/core/state.md
           - Tool: api/core/tool.md
           - Memory: api/core/memory.md
+          - StateProxy: api/core/state.md
+      - Hooks: api/hooks.md
+      - Skills: api/skills.md
+      - Support Classes: api/support.md
+      - Errors: api/errors.md
       - Messages:
           - api/messages/index.md
           - UserMessage: api/messages/user-message.md