robot_lab-ractor 0.1.0

data/examples/30_ractor_network.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 30: Ractor Network Scheduler
+#
+# Demonstrates Track 2 of RobotLab's Ractor parallelism: running a
+# multi-robot pipeline under RactorNetworkScheduler, which dispatches
+# independent tasks in parallel waves and respects depends_on ordering.
+#
+# Concepts covered:
+#   - Network.new(parallel_mode: :ractor) — opt the network into Ractor dispatch
+#   - Dependency waves                    — independent tasks run concurrently,
+#                                           dependent tasks wait for their wave
+#   - RobotSpec                           — frozen, Ractor-shareable robot descriptor
+#   - RactorNetworkScheduler              — direct use for testing / custom wiring
+#   - Result Hash                         — run_pipeline returns { name => result }
+#
+# Part 1 — simulated scheduler, no API key needed.
+#   Overrides execute_spec with a sleep-based stub so the wave ordering and
+#   timing characteristics are visible without real LLM calls.
+#
+# Part 2 — Network.new(parallel_mode: :ractor) API walkthrough.
+#   Shows how to configure the network and inspects the dependency graph.
+#   No run() call is made, so no API key is required.
+#
+# Part 3 — live LLM run (optional).
+#   Executes automatically when ANTHROPIC_API_KEY is set.
+#
+# Usage:
+#   bundle exec ruby examples/30_ractor_network.rb              # Parts 1 & 2
+#   ANTHROPIC_API_KEY=key ruby examples/30_ractor_network.rb    # Parts 1, 2 & 3
+
+require "robot_lab"
+require "robot_lab/ractor"
+
+puts "=" * 62
+puts "Example 30: Ractor Network Scheduler"
+puts "=" * 62
+puts
+
+DIVIDER = ("─" * 54).freeze
+
+# =============================================================================
+# Part 1: Simulated scheduler — dependency waves and timing
+# =============================================================================
+#
+# Pipeline topology:
+#
+#   headline_finder  ─────────────────────────────────┐
+#                                                      ├──► report_writer
+#   background_brief ─────────────────────────────────┤
+#                                                      │
+#   fact_checker     ─────────────────────────────────┘
+#
+# Wave 1 — headline_finder, background_brief, fact_checker: parallel (none depend on each other)
+# Wave 2 — report_writer: sequential (depends on all three)
+#
+# Simulated latencies (seconds):
+LATENCIES = {
+  "headline_finder"   => 0.60,
+  "background_brief"  => 0.50,
+  "fact_checker"      => 0.40,
+  "report_writer"     => 0.70
+}.freeze
+#
+# Expected times:
+#   Parallel   — wave1 = max(0.60, 0.50, 0.40) = 0.60s
+#                wave2 = 0.70s
+#                total ≈ 1.30s
+#
+#   Sequential — 0.60 + 0.50 + 0.40 + 0.70 = 2.20s
+#
+#   Speedup    ≈ 1.7×
+
+puts "── Part 1: Simulated parallel run (no API key) ───────────"
+puts
+
+# SimulatedScheduler overrides execute_spec so that instead of
+# constructing a real Robot and calling the LLM, it just sleeps for
+# the robot's configured latency and returns a synthetic result string.
+# All dependency-ordering and wave-dispatch logic is inherited unchanged.
+class SimulatedScheduler < RobotLab::RactorNetworkScheduler
+  private
+
+  def execute_spec(spec, _message)
+    delay = LATENCIES[spec.name] || 0.30
+    sleep delay
+    "#{spec.name}: completed after #{delay}s".freeze
+  end
+end
+
+# Build RobotSpec objects directly.
+# (Normally Network#run_with_ractor_scheduler builds these from Task wrappers.)
+def make_spec(name, deps = :none)
+  spec = RobotLab::RobotSpec.new(
+    name:          name.freeze,
+    template:      nil,
+    system_prompt: "You are the #{name} robot.".freeze,
+    config_hash:   {}.freeze
+  )
+  { spec: spec, depends_on: deps }
+end
+
+specs_with_deps = [
+  make_spec("headline_finder"),
+  make_spec("background_brief"),
+  make_spec("fact_checker"),
+  make_spec("report_writer", ["headline_finder", "background_brief", "fact_checker"])
+]
+
+memory    = RobotLab::Memory.new
+scheduler = SimulatedScheduler.new(memory: memory)
+
+topic = "artificial intelligence regulation in 2025"
+
+t0      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results = scheduler.run_pipeline(specs_with_deps, message: topic)
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+scheduler.shutdown
+
+sequential_total = LATENCIES.values.sum
+
+puts "  Pipeline topology:"
+puts "    Wave 1 (parallel): headline_finder · background_brief · fact_checker"
+puts "    Wave 2 (sequential): report_writer  ← waits for all three"
+puts
+
+puts "  Results (Hash { name => result_string }):"
+results.each { |name, val| puts "    \"#{name}\" => #{val.inspect}" }
+puts
+
+puts "  Wall time:         #{"%.3f" % elapsed}s"
+puts "  Sequential equiv:  #{"%.3f" % sequential_total}s  (#{LATENCIES.map { |n, d| "#{n}=#{d}" }.join(' + ')})"
+puts "  Speedup:           #{(sequential_total / elapsed).round(1)}×"
+puts
+
+# =============================================================================
+# Part 2: Network.new(parallel_mode: :ractor) API
+# =============================================================================
+
+puts "── Part 2: Network.new(parallel_mode: :ractor) ───────────"
+puts
+
+# When parallel_mode: :ractor is set on a Network, network.run(message:)
+# routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
+# The default mode is :async (unchanged SimpleFlow behavior).
+
+model = "claude-haiku-4-5-20251001"
+
+network = RobotLab::Network.new(name: "research_pipeline", parallel_mode: :ractor) do
+  task :headline_finder,  RobotLab.build(name: "headline_finder",
+                                          system_prompt: "Find the 3 most relevant news headlines. Be concise.",
+                                          model: model),
+       depends_on: :none
+
+  task :background_brief, RobotLab.build(name: "background_brief",
+                                          system_prompt: "Provide a 2-sentence background on the topic.",
+                                          model: model),
+       depends_on: :none
+
+  task :fact_checker,     RobotLab.build(name: "fact_checker",
+                                          system_prompt: "List 3 verifiable facts about the topic.",
+                                          model: model),
+       depends_on: :none
+
+  task :report_writer,    RobotLab.build(name: "report_writer",
+                                          system_prompt: "Synthesize the provided context into a 3-sentence report.",
+                                          model: model),
+       depends_on: ["headline_finder", "background_brief", "fact_checker"]
+end
+
+puts "  network.name          => #{network.name.inspect}"
+puts "  network.parallel_mode => #{network.parallel_mode.inspect}"
+puts
+puts "  Dependency graph (from network.pipeline.step_dependencies):"
+
+network.pipeline.step_dependencies.each do |step, deps|
+  dep_str = deps.empty? ? "(entry point — Wave 1)" : "depends on: #{deps.join(', ')}"
+  puts "    :#{step.to_s.ljust(18)}  #{dep_str}"
+end
+puts
+puts "  When network.run(message: ...) is called:"
+puts "    • RactorNetworkScheduler is created with the network's memory"
+puts "    • Each task is converted to a frozen RobotSpec"
+puts "    • Wave 1 tasks are dispatched concurrently (Thread per task)"
+puts "    • Each Thread submits a RactorJob to the worker queue"
+puts "    • A Ractor worker pops the job, constructs a fresh Robot from the"
+puts "      spec, calls robot.run(message), and returns the frozen result"
+puts "    • Wave 2 begins once all Wave 1 results are available"
+puts "    • Return value is a Hash { robot_name => result_string }"
+puts
+
+# =============================================================================
+# Part 3: Live LLM run (optional — requires ANTHROPIC_API_KEY)
+# =============================================================================
+
+unless ENV["ANTHROPIC_API_KEY"]
+  puts "── Part 3: Live LLM run ──────────────────────────────────"
+  puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
+  puts "   Expected behavior: headline_finder, background_brief, and"
+  puts "   fact_checker run in parallel; report_writer follows."
+  puts
+  puts "=" * 62
+  puts "Example 30 complete."
+  puts "=" * 62
+  exit 0
+end
+
+puts "── Part 3: Live LLM run (ANTHROPIC_API_KEY detected) ─────"
+puts
+
+puts "  Running 4-robot research pipeline on:"
+puts "  \"#{topic}\""
+puts
+puts "  Wave 1 (parallel): headline_finder · background_brief · fact_checker"
+puts "  Wave 2:            report_writer"
+puts
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+begin
+  result = network.run(message: topic)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+  puts "  Completed in #{"%.2f" % elapsed}s"
+  puts
+  puts "  Results:"
+  result.each do |name, text|
+    snippet = text.to_s.strip.lines.first.to_s.strip
+    puts "    [#{name}]  #{snippet[0..90]}#{snippet.length > 90 ? '…' : ''}"
+  end
+
+rescue Ractor::IsolationError, Ractor::Error => e
+  puts "  Ractor error: #{e.class}: #{e.message[0..100]}"
+  puts
+  puts "  ruby_llm is not yet Ractor-safe: it uses Procs in class"
+  puts "  definitions that cannot cross Ractor boundaries."
+  puts "  Track this at: https://github.com/crmne/ruby_llm"
+
+rescue RobotLab::Error => e
+  if e.message.include?("un-shareable Proc")
+    puts "  Live LLM runs require ruby_llm to be Ractor-safe."
+    puts "  ruby_llm stores Procs in class-level hooks that cannot cross"
+    puts "  Ractor boundaries. Part 1 (SimulatedScheduler) demonstrates wave"
+    puts "  ordering today; Part 3 will work once ruby_llm gains Ractor support."
+  else
+    puts "  RobotLab::Error: #{e.message}"
+  end
+end
+
+puts
+puts "=" * 62
+puts "Example 30 complete."
+puts "=" * 62

data/lib/robot_lab/ractor/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # RactorPool (not Ractor) avoids shadowing Ruby's built-in Ractor class
+  # for all code within the RobotLab namespace.
+  module RactorPool
+    VERSION = "0.1.0"
+  end
+end

data/lib/robot_lab/ractor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# NOTE: This file intentionally does NOT open module RobotLab::Ractor.
+# Defining that module would shadow Ruby's built-in Ractor class for all
+# code inside the RobotLab namespace, breaking Ractor.new / Ractor.make_shareable
+# calls in RactorWorkerPool, RactorNetworkScheduler, etc.
+
+require "etc"
+require "ractor_queue"
+require "ractor/wrapper"
+
+require_relative "ractor/version"
+require_relative "ractor_job"
+require_relative "ractor_boundary"
+require_relative "ractor_worker_pool"
+require_relative "ractor_memory_proxy"
+require_relative "ractor_network_scheduler"
+
+# Extend the RobotLab module with Ractor pool lifecycle methods.
+# Once robot_lab removes its own copies and adds robot_lab-ractor as a
+# dependency, this becomes the single source of truth for ractor_pool.
+module RobotLab
+  class << self
+    def ractor_pool
+      @ractor_pool ||= begin
+        size = respond_to?(:config) && config.respond_to?(:ractor_pool_size) \
+          ? (config.ractor_pool_size || :auto) : :auto
+        RactorWorkerPool.new(size: size)
+      end
+    end
+
+    def shutdown_ractor_pool
+      @ractor_pool&.shutdown
+      @ractor_pool = nil
+    end
+  end
+end

data/lib/robot_lab/ractor_boundary.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Utility for making values safe to pass across Ractor boundaries.
+  #
+  # Recursively freezes Hash and Array structures. Raises RactorBoundaryError
+  # if a value cannot be made Ractor-shareable (e.g. a live IO or Proc).
+  #
+  # @example
+  #   safe = RactorBoundary.freeze_deep({ model: "sonnet", args: { x: 1 } })
+  #   Ractor.shareable?(safe)  #=> true
+  #
+  module RactorBoundary
+    # Recursively freeze an object for safe Ractor boundary crossing.
+    #
+    # @param obj [Object] the value to freeze
+    # @return [Object] a frozen, Ractor-shareable copy
+    # @raise [RactorBoundaryError] if the value cannot be made shareable
+    def self.freeze_deep(obj)
+      return obj if Ractor.shareable?(obj)
+
+      result = case obj
+               when Hash
+                 obj.transform_keys { |k| freeze_deep(k) }
+                    .transform_values { |v| freeze_deep(v) }
+               when Array
+                 obj.map { |v| freeze_deep(v) }
+               else
+                 begin
+                   obj.dup
+                 rescue TypeError
+                   raise RactorBoundaryError,
+                         "Cannot make #{obj.class} Ractor-shareable: dup not supported"
+                 end
+               end
+
+      Ractor.make_shareable(result)
+    rescue ::Ractor::IsolationError, ::Ractor::Error => e
+      raise RactorBoundaryError, "Cannot make value Ractor-shareable: #{e.message}"
+    end
+  end
+end

data/lib/robot_lab/ractor_job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Carrier for work crossing a Ractor boundary.
+  #
+  # All fields must be Ractor-shareable (frozen Data, frozen String,
+  # frozen Hash, or a RactorQueue). Build with RactorBoundary.freeze_deep
+  # on the payload before constructing.
+  #
+  # @example
+  #   job = RactorJob.new(
+  #     id:          SecureRandom.uuid.freeze,
+  #     type:        :tool,
+  #     payload:     RactorBoundary.freeze_deep({ tool_class: "MyTool", args: { x: 1 } }),
+  #     reply_queue: RactorQueue.new(capacity: 1)
+  #   )
+  RactorJob = Data.define(:id, :type, :payload, :reply_queue)
+
+  # Frozen error representation for exceptions raised inside a Ractor worker.
+  # Serialized at the Ractor boundary and re-raised on the thread side.
+  #
+  # @example
+  #   err = RactorJobError.new(message: e.message.freeze, backtrace: e.backtrace.freeze)
+  RactorJobError = Data.define(:message, :backtrace)
+
+  # Carries everything needed to reconstruct a Robot inside a Ractor.
+  # All fields must be frozen strings, symbols, or hashes.
+  #
+  # @example
+  #   spec = RobotSpec.new(
+  #     name:          "analyst",
+  #     template:      :analyst,
+  #     system_prompt: nil,
+  #     config_hash:   { model: "claude-sonnet-4" }.freeze
+  #   )
+  RobotSpec = Data.define(:name, :template, :system_prompt, :config_hash)
+end

data/lib/robot_lab/ractor_memory_proxy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Wraps a Memory instance via Ractor::Wrapper so Ractor workers can safely
+  # read and write shared state.
+  #
+  # Only get, set, and keys are proxied across the Ractor boundary.
+  # Subscriptions and callbacks are NOT proxied — closures are not
+  # Ractor-safe. Use the thread-side Memory directly for reactive subscriptions.
+  #
+  # Values passed to set() must be Ractor-shareable; RactorBoundary.freeze_deep
+  # is applied automatically.
+  #
+  # @example
+  #   memory = Memory.new
+  #   proxy  = RactorMemoryProxy.new(memory)
+  #
+  #   # From any Ractor via the stub:
+  #   proxy.set(:result, "done")
+  #   proxy.get(:result)   #=> "done"
+  #
+  #   proxy.shutdown  # call when done
+  #
+  class RactorMemoryProxy
+    # @param memory [Memory] the memory instance to wrap
+    def initialize(memory)
+      @memory  = memory
+      @wrapper = ::Ractor::Wrapper.new(memory, use_current_ractor: true)
+      @stub    = @wrapper.stub
+    end
+
+    # Returns the Ractor-shareable stub for use inside Ractors.
+    # @return [Ractor::Wrapper stub]
+    def stub
+      @stub
+    end
+
+    # Read a value from the proxied Memory.
+    # @param key [Symbol]
+    # @return [Object, nil]
+    def get(key)
+      @stub.get(key)
+    end
+
+    # Write a frozen value to the proxied Memory.
+    # @param key [Symbol]
+    # @param value [Object] must be Ractor-shareable after freeze_deep
+    # @raise [RactorBoundaryError] if value cannot be made shareable
+    def set(key, value)
+      frozen_value = RactorBoundary.freeze_deep(value)
+      @stub.set(key, frozen_value)
+    end
+
+    # List all keys currently set in the proxied Memory.
+    # @return [Array<Symbol>]
+    def keys
+      @stub.keys
+    end
+
+    # Shut down the ractor-wrapper.
+    def shutdown
+      @wrapper.async_stop
+      @wrapper.join
+    rescue => e
+      warn "RactorMemoryProxy shutdown error: #{e.message}"
+    end
+  end
+end

data/lib/robot_lab/ractor_network_scheduler.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Schedules frozen robot task descriptions across Ractor workers.
+  #
+  # Robots stay in threads for LLM calls (ruby_llm is not Ractor-safe).
+  # The scheduler distributes frozen RobotSpec payloads; each worker
+  # constructs a fresh Robot, runs the task, and returns a frozen result.
+  #
+  # Task ordering respects depends_on: tasks are only dispatched once all
+  # named dependencies have resolved (same topological semantics as
+  # SimpleFlow::Pipeline).
+  #
+  # @example
+  #   scheduler = RactorNetworkScheduler.new(memory: shared_memory)
+  #   scheduler.run_pipeline([
+  #     { spec: analyst_spec, depends_on: :none },
+  #     { spec: writer_spec,  depends_on: ["analyst"] }
+  #   ], message: "Process this")
+  #   scheduler.shutdown
+  #
+  class RactorNetworkScheduler
+    QUEUE_CAPACITY = 256
+
+    # @param memory [Memory] shared network memory for all robot tasks
+    # @param pool_size [Integer, :auto] number of Ractor workers
+    def initialize(memory:, pool_size: :auto)
+      @memory  = memory
+      @work_q  = RactorQueue.new(capacity: QUEUE_CAPACITY)
+      @size    = pool_size == :auto ? Etc.nprocessors : pool_size.to_i
+      @workers = @size.times.map { spawn_worker(@work_q) }
+      @closed  = false
+    end
+
+    # Run a single spec and return the result string.
+    # @param spec [RobotSpec]
+    # @param message [String]
+    # @return [String] the robot's last_text_content
+    def run_spec(spec, message:)
+      execute_spec(spec, message)
+    end
+
+    # Run a pipeline of specs in dependency order.
+    #
+    # @param specs_with_deps [Array<Hash>] each entry has :spec and :depends_on
+    # @param message [String] initial message passed to entry-point robots
+    # @return [Hash<String, String>] name => result for each completed robot
+    def run_pipeline(specs_with_deps, message:)
+      completed = {}
+      remaining = specs_with_deps.dup
+
+      until remaining.empty?
+        ready, remaining = remaining.partition do |entry|
+          deps = entry[:depends_on]
+          deps == :none || deps == :optional ||
+            Array(deps).all? { |d| completed.key?(d) }
+        end
+
+        raise RobotLab::Error, "Circular dependency or unresolvable deps in RactorNetworkScheduler" if ready.empty?
+
+        threads = ready.map do |entry|
+          spec = entry[:spec]
+          msg  = completed.values.last || message
+          Thread.new { [spec.name, execute_spec(spec, msg)] }.tap { |t| t.report_on_exception = false }
+        end
+
+        threads.each do |t|
+          name, result = t.value
+          completed[name] = result
+        end
+      end
+
+      completed
+    end
+
+    # Gracefully shut down worker Ractors.
+    def shutdown
+      return if @closed
+
+      @closed = true
+      @size.times { @work_q.push(nil) }
+      @workers.each { |w| w.join rescue nil }
+    end
+
+    private
+
+    def execute_spec(spec, message)
+      frozen_spec    = ::Ractor.make_shareable(spec)
+      frozen_message = message.to_s.freeze
+      reply_q        = RactorQueue.new(capacity: 1)
+
+      job = RactorJob.new(
+        id:          SecureRandom.uuid.freeze,
+        type:        :robot,
+        payload:     RactorBoundary.freeze_deep({ spec: frozen_spec, message: frozen_message }),
+        reply_queue: reply_q
+      )
+
+      @work_q.push(job)
+      result = reply_q.pop
+
+      if result.is_a?(RactorJobError)
+        raise RobotLab::Error, "Robot '#{spec.name}' failed in Ractor: #{result.message}"
+      end
+
+      result
+    end
+
+    def spawn_worker(work_q)
+      ::Ractor.new(work_q) do |q|
+        loop do
+          job = q.pop
+          break if job.nil?
+
+          begin
+            spec   = job.payload[:spec]
+            message = job.payload[:message]
+
+            robot = RobotLab::Robot.new(
+              name:          spec.name,
+              template:      spec.template ? spec.template.to_sym : nil,
+              system_prompt: spec.system_prompt,
+              config:        spec.config_hash.empty? ? nil : RobotLab::RunConfig.new(**spec.config_hash.transform_keys(&:to_sym))
+            )
+
+            robot_result = robot.run(message)
+            job.reply_queue.push(robot_result.last_text_content.to_s.freeze)
+          rescue => e
+            err = RobotLab::RactorJobError.new(
+              message:   e.message.freeze,
+              backtrace: (e.backtrace || []).map(&:freeze).freeze
+            )
+            job.reply_queue.push(err)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/ractor_worker_pool.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # A pool of Ractor workers that execute CPU-bound, Ractor-safe tools.
+  #
+  # Work is distributed via a shared RactorQueue. Each worker runs a
+  # blocking loop, pops RactorJob instances, dispatches to the named
+  # tool class, and pushes the frozen result (or a RactorJobError) to
+  # the job's per-job reply_queue.
+  #
+  # Shutdown uses a poison-pill pattern: one nil sentinel per worker is
+  # pushed to the work queue; each worker exits when it pops nil.
+  #
+  # Only tools that declare +ractor_safe true+ should be submitted.
+  # Tool classes are instantiated fresh inside the Ractor for each call.
+  #
+  # @example
+  #   pool = RactorWorkerPool.new(size: 4)
+  #   result = pool.submit("MyTool", { "arg" => "value" })
+  #   pool.shutdown
+  #
+  class RactorWorkerPool
+    QUEUE_CAPACITY = 1024
+
+    attr_reader :size
+
+    # @param size [Integer, :auto] number of workers (:auto = Etc.nprocessors)
+    def initialize(size: :auto)
+      @size    = size == :auto ? Etc.nprocessors : size.to_i
+      @closed  = false
+      @work_q  = RactorQueue.new(capacity: QUEUE_CAPACITY)
+      @workers = @size.times.map { spawn_worker(@work_q) }
+    end
+
+    # Submit a tool job and block until the result is available.
+    #
+    # @param tool_class_name [String] fully-qualified Ruby constant name of the tool class
+    # @param args [Hash] tool arguments (deep-frozen before crossing Ractor boundary)
+    # @return [Object] the tool's return value
+    # @raise [ToolError] if the tool raises inside the Ractor
+    def submit(tool_class_name, args)
+      raise ToolError, "Pool is shut down" if @closed
+
+      reply_q = RactorQueue.new(capacity: 1)
+      payload = RactorBoundary.freeze_deep({
+        tool_class: tool_class_name.to_s,
+        args:       args
+      })
+
+      job = RactorJob.new(
+        id:          SecureRandom.uuid.freeze,
+        type:        :tool,
+        payload:     payload,
+        reply_queue: reply_q
+      )
+
+      @work_q.push(job)
+      result = reply_q.pop
+
+      if result.is_a?(RactorJobError)
+        raise ToolError, "Tool '#{tool_class_name}' failed in Ractor: #{result.message}"
+      end
+
+      result
+    end
+
+    # Gracefully shut down the pool via poison-pill pattern.
+    # @return [void]
+    def shutdown
+      return if @closed
+
+      @closed = true
+      @size.times { @work_q.push(nil) }
+      @workers.each { |w| w.join rescue nil }
+    end
+
+    private
+
+    def spawn_worker(work_q)
+      ::Ractor.new(work_q) do |q|
+        loop do
+          job = q.pop
+          break if job.nil?
+
+          begin
+            tool_class    = Object.const_get(job.payload[:tool_class])
+            tool          = tool_class.new
+            result        = tool.execute(**job.payload[:args].transform_keys(&:to_sym))
+            frozen_result = ::Ractor.make_shareable(result.frozen? ? result : result.dup.freeze)
+            job.reply_queue.push(frozen_result)
+          rescue => e
+            err = RobotLab::RactorJobError.new(
+              message:   e.message.freeze,
+              backtrace: (e.backtrace || []).map(&:freeze).freeze
+            )
+            job.reply_queue.push(err)
+          end
+        end
+      end
+    end
+  end
+end