robot_lab 0.1.0 → 0.2.1

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 ractor_pool_size max_concurrent_robots
+                      doom_loop_threshold auto_compact compact_threshold].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,7 +105,6 @@ module RobotLab
       self.class.new(**merged)
     end
 
-
     # Applies LLM fields to a chat object via its with_* methods.
     #
     # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
@@ -119,7 +118,6 @@ module RobotLab
       end
     end
 
-
     # Build a RunConfig from prompt_manager front matter metadata.
     #
     # @param metadata [Object] a PM::Metadata object (responds to field names)
@@ -141,27 +139,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/script_tool.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'shellwords'
+
+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
+    def self.from_path(script_path)
+      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
+
+      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)]
+        output, status = Open3.capture2e(*cmd)
+        status.success? ? output : "Error (exit #{status.exitstatus}):\n#{output}"
+      end
+    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/tool.rb

@@ -94,7 +94,7 @@ 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?
+      if self.class.ractor_safe? && !self.class.name.nil? && RobotLab.extension_loaded?(:ractor)
         RobotLab.ractor_pool.submit(self.class.name, args)
       else
         super
@@ -204,8 +204,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String]
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     private

data/lib/robot_lab/tool_config.rb

@@ -94,7 +94,7 @@ module RobotLab
       def filter_tools(tools, allowed_names:)
         return [] if allowed_names.empty?
 
-        allowed_set = allowed_names.map(&:to_s).to_set
+        allowed_set = allowed_names.to_set(&:to_s)
         tools.select { |tool| allowed_set.include?(tool_name(tool)) }
       end
 

data/lib/robot_lab/tool_manifest.rb

@@ -142,8 +142,8 @@ module RobotLab
     #
     # @yield [Tool] Each tool in the manifest
     #
-    def each(&block)
-      @tools.values.each(&block)
+    def each(&)
+      @tools.values.each(&)
     end
 
     # Clear all tools
@@ -173,9 +173,7 @@ module RobotLab
     #
     def merge(other)
       case other
-      when ToolManifest
-        other.each { |tool| add(tool) }
-      when Array
+      when ToolManifest, Array
         other.each { |tool| add(tool) }
       when Tool
         add(other)
@@ -194,8 +192,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Create manifest from hash of tool definitions

data/lib/robot_lab/user_message.rb

@@ -84,8 +84,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Create from string or hash

data/lib/robot_lab/version.rb

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

data/lib/robot_lab/waiter.rb

@@ -36,7 +36,7 @@ module RobotLab
       end
 
       begin
-        ready = IO.select([@read_io], nil, nil, timeout)
+        ready = @read_io.wait_readable(timeout)
 
         @mutex.synchronize do
           @waiter_count -= 1

data/lib/robot_lab.rb

@@ -6,9 +6,6 @@ require 'securerandom'
 require 'digest'
 
 # Core dependencies
-# ActiveSupport delegation is required by ruby_llm (RubyLLM::Agent uses delegate)
-# but not declared in ruby_llm's gemspec. Load it before ruby_llm.
-require 'active_support/core_ext/module/delegation'
 require 'ruby_llm'
 require 'prompt_manager'
 require 'async'
@@ -49,8 +46,6 @@ module RobotLab
 end
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
-loader.ignore("#{__dir__}/generators")
-loader.ignore("#{__dir__}/robot_lab/rails_integration")
 loader.ignore("#{__dir__}/robot_lab/robot")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
@@ -71,7 +66,6 @@ loader.setup
 require_relative 'robot_lab/error'
 require_relative 'robot_lab/message'
 require_relative 'robot_lab/memory'
-require_relative 'robot_lab/ractor_job'
 
 # Eager load everything in Rails or when explicitly requested.
 # Otherwise Zeitwerk's lazy autoloading keeps boot fast.
@@ -80,7 +74,41 @@ loader.eager_load if defined?(Rails::Engine) || ENV["ROBOT_LAB_EAGER_LOAD"]
 module RobotLab
   # Error classes are defined in lib/robot_lab/error.rb
 
+  @extensions = {}
+
   class << self
+    # Registers an extension gem so core can detect it without depending on it.
+    #
+    # Extension gems call this at load time to announce themselves. Core uses
+    # extension_loaded? to guard optional behavior instead of defined?/respond_to?.
+    #
+    # @param name [Symbol] identifier for the extension (e.g. :durable, :ractor)
+    # @param mod [Module, Object] the extension's primary module or a sentinel value
+    def register_extension(name, mod)
+      @extensions[name] = mod
+    end
+
+    # Returns true if the named extension gem has been loaded.
+    #
+    # @param name [Symbol] extension identifier
+    def extension_loaded?(name)
+      @extensions.key?(name)
+    end
+
+    # Returns the module registered for the named extension, or nil.
+    #
+    # @param name [Symbol] extension identifier
+    def extension(name)
+      @extensions[name]
+    end
+
+    # Returns the list of registered extension names.
+    #
+    # @return [Array<Symbol>]
+    def loaded_extensions
+      @extensions.keys
+    end
+
     # Returns the Config object (MywayConfig-based).
     #
     # Configuration is automatically loaded from:
@@ -100,7 +128,6 @@ module RobotLab
       @config ||= Config.new.tap(&:after_load)
     end
 
-
     # Yields the Config object for block-style configuration.
     #
     # @yield [Config] the config instance
@@ -114,7 +141,6 @@ module RobotLab
       yield config
     end
 
-
     # Reload configuration from all sources.
     #
     # Clears the cached Config instance, forcing it to be
@@ -126,7 +152,6 @@ module RobotLab
       config
     end
 
-
     # Factory method to create a new Robot instance.
     #
     # @param name [String, nil] the unique identifier for the robot (auto-generated if nil)
@@ -153,7 +178,8 @@ module RobotLab
     #     name: "helper",
     #     system_prompt: "You are a helpful assistant."
     #   )
-    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil, **options)
+    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil,
+              config: nil, **)
       Robot.new(
         name: name,
         template: template,
@@ -163,11 +189,10 @@ module RobotLab
         bus: bus,
         skills: skills,
         config: config,
-        **options
+        **
       )
     end
 
-
     # Factory method to create a new Network of robots.
     #
     # @param name [String] the unique identifier for the network
@@ -195,11 +220,10 @@ module RobotLab
     #     step :entities, entity_bot, depends_on: [:fetch]
     #     step :merge, merger, depends_on: [:sentiment, :entities]
     #   end
-    def create_network(name:, concurrency: :auto, config: nil, &block)
-      Network.new(name: name, concurrency: concurrency, config: config, &block)
+    def create_network(name:, concurrency: :auto, config: nil, &)
+      Network.new(name: name, concurrency: concurrency, config: config, &)
     end
 
-
     # Factory method to create a new Memory object.
     #
     # @param data [Hash] initial runtime data
@@ -216,43 +240,8 @@ module RobotLab
     #
     # @example Memory with caching disabled
     #   memory = RobotLab.create_memory(data: {}, enable_cache: false)
-    def create_memory(data: {}, enable_cache: true, **options)
-      Memory.new(data: data, enable_cache: enable_cache, **options)
-    end
-
-
-    # Returns the shared RactorWorkerPool, lazily initialized.
-    #
-    # Pool size is determined by RobotLab.config.ractor_pool_size or
-    # defaults to Etc.nprocessors (:auto). The pool lives for the lifetime
-    # of the process. Call RobotLab.shutdown_ractor_pool to drain and
-    # close it explicitly.
-    #
-    # @return [RactorWorkerPool]
-    def ractor_pool
-      @ractor_pool ||= begin
-        size = config.respond_to?(:ractor_pool_size) ? (config.ractor_pool_size || :auto) : :auto
-        RactorWorkerPool.new(size: size)
-      end
-    end
-
-    # Shut down the shared Ractor worker pool, draining in-flight jobs.
-    #
-    # @return [void]
-    def shutdown_ractor_pool
-      @ractor_pool&.shutdown
-      @ractor_pool = nil
+    def create_memory(data: {}, enable_cache: true, **)
+      Memory.new(data: data, enable_cache: enable_cache, **)
     end
   end
 end
-
-# Load Rails integration if Rails is defined
-if defined?(Rails::Engine)
-  require 'robot_lab/rails_integration/engine'
-  require 'robot_lab/rails_integration/railtie'
-  require 'robot_lab/rails_integration/turbo_stream_callbacks'
-  require 'robot_lab/rails_integration/job'
-
-  # Convenience alias so job subclasses can inherit from RobotLab::Job
-  RobotLab::Job = RobotLab::RailsIntegration::Job
-end

data/logfile

@@ -0,0 +1,8 @@
+2026-02-25 20:56:30.644 CST [47152] LOG:  starting PostgreSQL 18.2 (Homebrew) on aarch64-apple-darwin25.2.0, compiled by Apple clang version 17.0.0 (clang-1700.6.3.2), 64-bit
+2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv6 address "::1": Address already in use
+2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
+2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv4 address "127.0.0.1": Address already in use
+2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
+2026-02-25 20:56:30.646 CST [47152] WARNING:  could not create listen socket for "localhost"
+2026-02-25 20:56:30.646 CST [47152] FATAL:  could not create any TCP/IP sockets
+2026-02-25 20:56:30.646 CST [47152] LOG:  database system is shut down

data/mkdocs.yml

@@ -169,8 +169,8 @@ nav:
       - MCP Integration: guides/mcp-integration.md
       - Streaming Responses: guides/streaming.md
       - Memory System: guides/memory.md
-      - Rails Integration: guides/rails-integration.md
-      - Ractor Parallelism: guides/ractor-parallelism.md
+      - Observability & Safety: guides/observability.md
+      - Knowledge Search: guides/knowledge.md
   - API Reference:
       - api/index.md
       - Core Classes:
@@ -201,4 +201,3 @@ nav:
       - Multi-Robot Network: examples/multi-robot-network.md
       - Tool Usage: examples/tool-usage.md
       - MCP Server: examples/mcp-server.md
-      - Rails Application: examples/rails-application.md

data/robot_concurrency.md

@@ -0,0 +1,38 @@
+# Ruby Concurrency Review — RobotLab
+
+Source: https://paolino.me/ruby-concurrency-what-actually-happens/
+
+## What Applies to RobotLab
+
+### 1. You're Already in the Right Model — Lean Into It
+
+RobotLab uses `async (~> 2.0)`, which is exactly the fiber-based scheduler the article describes. LLM calls are pure I/O-bound work (HTTP streaming), so fibers are the correct and lowest-cost primitive. The article validates this architecture choice. No changes needed here — but be deliberate about not mixing blocking thread-style calls into the `Async` reactor unnecessarily.
+
+### 2. The Ractor Caution Is Real (Recent Commit: `feat(ractor-parallelism)`)
+
+The article is clear: Ractors in Ruby 4.0 are still experimental and practically incompatible with gems that use global state. RobotLab's dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`) almost certainly use global state. Worth auditing whether the new Ractor code hits `Ractor::IsolationError` under realistic load. The article's recommendation: **use Processes** for CPU parallelism if Rails-style gems are involved.
+
+### 3. ~~The `Waiter` Class May Be Misfit in Fiber Context~~ — RESOLVED
+
+`lib/robot_lab/waiter.rb` was updated to use `IO.pipe` + `IO.select` instead of `ConditionVariable`. `IO.select` is hooked by the Ruby 3.1+ fiber scheduler protocol, so it correctly yields to the Async scheduler when called from within an Async task, and correctly blocks the calling thread when used outside one. `Async::Condition` was considered but rejected: it only works inside an Async block, whereas `Memory` is intentionally usable from both plain threads and Async fibers.
+
+### 4. Parallel Network Execution — Check the Primitive
+
+`call_parallel()` in `Network` (built on `SimpleFlow::Pipeline`) — if it spawns OS threads rather than async tasks, you get heavier overhead than necessary for I/O-bound robot calls. The article's guidance: for I/O work, fiber-based `Async::Barrier` with concurrent tasks is 10-20x cheaper than threads.
+
+### 5. Resource Semaphores for Parallel Networks
+
+When a Network runs multiple robots concurrently, each making LLM API calls, you can exhaust API rate limits or connection pools with no back-pressure. The article's semaphore pattern applies directly — cap in-flight robot tasks to match your API tier's concurrency limit. This is worth adding to `RunConfig` as a `max_concurrent_robots` infra field.
+
+### 6. Colorless Concurrency — This Is Already Your Story
+
+The article's main point about Ruby fibers being "colorless" (no `async/await` propagation required) is directly reflected in how `robot.run("...")` stays synchronous-looking whether run standalone or in a parallel network. This is an underappreciated design strength worth highlighting in docs/README.
+
+---
+
+## Summary
+
+The async/fiber architecture is correct for LLM I/O work. The two actionable concerns are:
+
+1. **Audit the Ractor code** for isolation errors with gem dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`).
+2. **Check `Waiter`** (condition variable in `lib/robot_lab/waiter.rb`) — if called inside an `Async` reactor block, replace with `Async::Condition` to avoid stalling the reactor.