robot_lab 0.2.6 → 0.2.8

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(
@@ -71,6 +72,11 @@ 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"]
@@ -126,14 +132,15 @@ module RobotLab
     end
 
     def with_hook_scope(registries, per_run_hooks)
-      previous = Thread.current[:robot_lab_hook_scope]
-      Thread.current[:robot_lab_hook_scope] = {
+      thread = Thread.current
+      previous = thread[:robot_lab_hook_scope]
+      thread[:robot_lab_hook_scope] = {
         registries: registries,
         per_run_hooks: per_run_hooks
       }
       yield
     ensure
-      Thread.current[:robot_lab_hook_scope] = previous
+      thread[:robot_lab_hook_scope] = previous
     end
 
     def current_hook_scope
@@ -145,7 +152,7 @@ module RobotLab
     # 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_*)
     #
@@ -227,6 +234,7 @@ module RobotLab
     #     name: "helper",
     #     system_prompt: "You are a helpful assistant."
     #   )
+    # :reek:LongParameterList :reek:BooleanParameter -- documented factory API mirroring Robot#initialize; enable_cache is a feature toggle.
     def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil,
               config: nil, **)
       Robot.new(
@@ -246,28 +254,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, &)
@@ -289,6 +297,7 @@ module RobotLab
     #
     # @example Memory with caching disabled
     #   memory = RobotLab.create_memory(data: {}, enable_cache: false)
+    # :reek:BooleanParameter -- enable_cache is a documented feature toggle forwarded to Memory.new.
     def create_memory(data: {}, enable_cache: true, **)
       Memory.new(data: data, enable_cache: enable_cache, **)
     end

data/mkdocs.yml

@@ -177,10 +177,15 @@ nav:
       - 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -197,8 +197,9 @@ description: |
   memory; networks for coordinating multiple robots with intelligent routing; MCP (Model
   Context Protocol) integration for external tool servers; and a memory system with Redis
   backend and semantic caching. Optional gems add Rails integration (robot_lab-rails),
-  durable learning (robot_lab-durable), Ractor concurrency (robot_lab-ractor), and
-  document storage (robot_lab-document_store).
+  durable learning (robot_lab-durable), Ractor concurrency (robot_lab-ractor), document
+  storage (robot_lab-document_store), and OS-level skill-script confinement
+  (robot_lab-sandbox). Core itself imposes no execution limitations.
 email:
 - dvanhoozer@gmail.com
 executables: []
@@ -218,12 +219,14 @@ files:
 - ".loki"
 - ".quality/reek_baseline.txt"
 - ".rubocop.yml"
+- Archspec.rb
 - CHANGELOG.md
 - CLAUDE.md
 - COMMITS.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- _typos.toml
 - agent2agent_review.md
 - agentf_improvements.md
 - agents.md
@@ -235,6 +238,7 @@ files:
 - docs/api/core/state.md
 - docs/api/core/tool.md
 - docs/api/errors.md
+- docs/api/hooks.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md
@@ -245,9 +249,11 @@ files:
 - docs/api/messages/tool-call-message.md
 - docs/api/messages/tool-result-message.md
 - docs/api/messages/user-message.md
+- docs/api/skills.md
 - docs/api/streaming/context.md
 - docs/api/streaming/events.md
 - docs/api/streaming/index.md
+- docs/api/support.md
 - docs/architecture/core-concepts.md
 - docs/architecture/index.md
 - docs/architecture/message-flow.md
@@ -295,6 +301,7 @@ files:
 - examples/13_spawn.rb
 - examples/14_rusty_circuit/.envrc
 - examples/14_rusty_circuit/.gitignore
+- examples/14_rusty_circuit/README.md
 - examples/14_rusty_circuit/comic.rb
 - examples/14_rusty_circuit/display.rb
 - examples/14_rusty_circuit/heckler.rb
@@ -473,6 +480,7 @@ files:
 - lib/robot_lab/memory.rb
 - lib/robot_lab/memory_change.rb
 - lib/robot_lab/message.rb
+- lib/robot_lab/names.rb
 - lib/robot_lab/narrator.rb
 - lib/robot_lab/network.rb
 - lib/robot_lab/robot.rb
@@ -487,9 +495,6 @@ files:
 - lib/robot_lab/robot_result.rb
 - lib/robot_lab/run_config.rb
 - lib/robot_lab/runnable.rb
-- lib/robot_lab/sandbox.rb
-- lib/robot_lab/sandbox/null.rb
-- lib/robot_lab/sandbox/seatbelt.rb
 - lib/robot_lab/script_tool.rb
 - lib/robot_lab/state_proxy.rb
 - lib/robot_lab/streaming/context.rb
@@ -536,7 +541,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby framework for building and orchestrating multi-robot LLM workflows
 test_files: []

data/lib/robot_lab/sandbox/null.rb

@@ -1,13 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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