robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Classification surface for "should this error be retried?" — so hosts
+  # (ActiveJob retry_on lists, robot_lab-to's takeover loop, custom retry
+  # wrappers) don't reimplement the same case statement against RobotLab's
+  # error hierarchy.
+  #
+  # - +InferenceError+ (transient LLM/API failures) is always retryable,
+  #   except its more specific subclass +ToolLoopError+ (a circuit breaker
+  #   tripped by a repeating tool-call pattern — retrying immediately would
+  #   just re-trigger the same loop).
+  # - +MCPError+ and +ToolError+ are opt-in: retryable only when raised
+  #   with +retryable: true+, since some instances are transient (a
+  #   connection drop, a timeout) and some are not (an explicit rejection
+  #   from the server or tool).
+  # - Everything else (+ConfigurationError+, +ToolNotFoundError+,
+  #   +DependencyError+, +RactorBoundaryError+, +BusError+, and any
+  #   non-RobotLab error) is never retryable.
+  module Errors
+    # @param error [Exception, nil]
+    # @return [Boolean] true when the host should retry the operation that raised +error+
+    def self.retryable?(error)
+      return false if error.nil? || error.is_a?(RobotLab::ToolLoopError)
+
+      case error
+      when RobotLab::MCPError, RobotLab::ToolError
+        error.respond_to?(:retryable) && error.retryable == true
+      when RobotLab::InferenceError
+        true
+      else
+        false
+      end
+    end
+
+    # Always-retryable error classes, for explicit ActiveJob-style
+    # +retry_on+ allow-lists. Excludes +MCPError+/+ToolError+ because
+    # their retryability is per-raise (via +retryable:+), not per-class.
+    #
+    # @return [Array<Class>]
+    def self.retryable_classes
+      [RobotLab::InferenceError].freeze
+    end
+  end
+end

data/lib/robot_lab/history_compressor.rb

@@ -124,13 +124,11 @@ module RobotLab
 
       if score >= @keep_threshold
         :keep
-      elsif score < @drop_threshold
+      elsif score < @drop_threshold || !@summarizer
         :drop
-      elsif @summarizer
+      else
         summary = @summarizer.call(text).to_s.strip
         summary.empty? ? :drop : summary
-      else
-        :drop
       end
     end
 
@@ -141,10 +139,7 @@ module RobotLab
       @messages.each_with_index do |msg, idx|
         action = actions[idx]
 
-        if action.nil?
-          # Pinned or recent: always include
-          result << msg
-        elsif action == :keep
+        if action.nil? || action == :keep
           result << msg
         elsif action == :drop
           # Omit entirely
@@ -166,7 +161,7 @@ module RobotLab
       role = msg.role
 
       return true if role == :system
-      return true if role == :tool || role == :tool_result
+      return true if %i[tool tool_result].include?(role)
 
       # Assistant tool-call dispatcher: content is nil or blank
       if role == :assistant
@@ -185,7 +180,6 @@ module RobotLab
       case content
       when String then content
       when Array  then content.filter_map { |p| p[:text] || p["text"] }.join(" ")
-      else nil
       end
     end
 

data/lib/robot_lab/hook.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Base class for hook handlers.
+  #
+  # Subclasses implement class methods for each hook they handle.
+  # Unimplemented hooks are silently skipped; around hooks passthrough
+  # automatically so the chain never breaks.
+  #
+  # The namespace defaults to the snake_case form of the last segment of the
+  # class name (e.g. TokenLogger -> :token_logger). Override with
+  # `self.namespace = :custom` when needed.
+  #
+  # @example
+  #   class AuditHook < RobotLab::Hook
+  #     def self.before_run(ctx)
+  #       ctx.local.started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  #     end
+  #
+  #     def self.after_run(ctx)
+  #       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx.local.started_at
+  #       puts "[#{ctx.robot.name}] #{(elapsed * 1000).round(1)}ms"
+  #     end
+  #
+  #     def self.on_error(ctx)
+  #       puts "[#{ctx.robot.name}] ERROR: #{ctx.error.message}"
+  #     end
+  #   end
+  #
+  #   RobotLab.on(AuditHook)
+  #   robot.on(AuditHook)
+  #   network.on(AuditHook)
+  #
+  class Hook
+    @namespace = nil
+
+    class << self
+      attr_writer :namespace
+
+      # Returns the hook's namespace symbol, derived from the class name by
+      # default. Returns nil for the base Hook class itself.
+      #
+      # @return [Symbol, nil]
+      def namespace
+        return @namespace if @namespace
+        return nil if self == Hook
+
+        name.split('::').last
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+            .to_sym
+      end
+
+      # Dispatch a single hook to this handler.
+      #
+      # If the handler implements the method it is called. For around hooks that
+      # are not implemented the block is called directly (passthrough). Non-around
+      # hooks that are not implemented are silent no-ops.
+      #
+      # @param hook_name [Symbol] e.g. :before_run, :around_tool_call
+      # @param context [HookContext] the hook context object
+      # @yield for around hooks — the next link in the chain
+      def call(hook_name, context, &block)
+        if singleton_class.public_method_defined?(hook_name)
+          block ? public_send(hook_name, context, &block)
+                : public_send(hook_name, context)
+        elsif block
+          block.call
+        end
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@namespace, nil)
+      end
+    end
+  end
+end

data/lib/robot_lab/hook_context.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class HookContext
+    attr_reader :event, :metadata
+
+    def initialize(event:, metadata: nil)
+      @event = event.to_sym
+      @metadata = metadata || ExtensionState.new
+    end
+
+    def ext(name)
+      metadata.ext(name)
+    end
+
+    def local
+      raise ArgumentError, "No hook namespace active" unless @namespace
+
+      ext(@namespace)
+    end
+
+    def with_namespace(namespace)
+      previous = @namespace
+      @namespace = namespace&.to_sym
+      yield self
+    ensure
+      @namespace = previous
+    end
+
+    def to_h
+      public_snapshot.merge(metadata: metadata.to_h)
+    end
+
+    private
+
+    def public_snapshot
+      public_methods(false)
+        .grep_v(/=\z/)
+        .reject { |name| %i[to_h local].include?(name) }
+        .sort
+        .to_h { |name| [name, public_send(name)] }
+    end
+  end
+
+  class RunHookContext < HookContext
+    attr_reader :robot, :network, :task, :memory, :config
+    attr_accessor :request, :response, :error
+
+    def initialize(robot:, request:, network: nil, task: nil, memory: nil, config: nil, response: nil, error: nil, **)
+      super(event: :run, **)
+      @robot = robot
+      @network = network
+      @task = task
+      @memory = memory
+      @config = config
+      @request = request
+      @response = response
+      @error = error
+    end
+  end
+
+  class LlmGenerationHookContext < RunHookContext
+    attr_reader :iteration
+    attr_accessor :generation_response
+
+    def initialize(iteration: 0, generation_response: nil, **)
+      super(**)
+      @iteration = iteration
+      @generation_response = generation_response
+    end
+  end
+
+  class ToolCallHookContext < HookContext
+    attr_reader :tool, :tool_name, :tool_args, :robot
+    attr_accessor :tool_result, :tool_error
+
+    def initialize(tool:, tool_args:, robot: nil, tool_result: nil, tool_error: nil, **)
+      super(event: :tool_call, **)
+      @tool = tool
+      @tool_name = tool.respond_to?(:name) ? tool.name : tool.class.name
+      @tool_args = tool_args
+      @robot = robot
+      @tool_result = tool_result
+      @tool_error = tool_error
+    end
+  end
+
+  class NetworkRunHookContext < HookContext
+    attr_reader :network, :memory, :config
+    attr_accessor :context, :result, :error
+
+    def initialize(network:, context:, memory: nil, config: nil, result: nil, error: nil, **)
+      super(event: :network_run, **)
+      @network = network
+      @context = context
+      @memory = memory
+      @config = config
+      @result = result
+      @error = error
+    end
+  end
+
+  class TaskHookContext < HookContext
+    attr_reader :network, :task, :task_name, :robot, :memory, :config
+    attr_accessor :result, :error
+
+    def initialize(task:, network: nil, robot: nil, memory: nil, config: nil, result: nil, error: nil, **)
+      super(event: :task, **)
+      @network = network
+      @task = task
+      @task_name = task.name
+      @robot = robot || task.robot
+      @memory = memory
+      @config = config
+      @result = result
+      @error = error
+    end
+  end
+
+  class LearnHookContext < HookContext
+    attr_reader :robot, :text, :learnings_before
+    attr_accessor :stored, :error
+
+    def initialize(robot:, text:, learnings_before:, **)
+      super(event: :learn, **)
+      @robot            = robot
+      @text             = text
+      @learnings_before = learnings_before.freeze
+      @stored           = false
+    end
+  end
+
+  class CompactionHookContext < HookContext
+    attr_reader :robot, :messages_before, :config, :strategy
+    attr_accessor :compacted_messages, :error
+
+    def initialize(robot:, messages_before:, config:, strategy:, **)
+      super(event: :compaction, **)
+      @robot            = robot
+      @messages_before  = messages_before.freeze
+      @config           = config
+      @strategy         = strategy
+      @compacted_messages = nil
+    end
+
+    # True once an on_compaction handler has supplied a replacement message set.
+    def handled?
+      !@compacted_messages.nil?
+    end
+  end
+
+  class ExtensionState
+    def initialize
+      @states = Hash.new { |h, key| h[key] = DotState.new }
+    end
+
+    def ext(name)
+      @states[name.to_sym]
+    end
+
+    def to_h
+      @states.transform_values(&:to_h)
+    end
+  end
+
+  class DotState
+    def initialize
+      @data = {}
+    end
+
+    def merge_defaults(hash)
+      hash.each { |k, v| @data[k.to_sym] = v unless @data.key?(k.to_sym) }
+      self
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s.delete_suffix('=').to_sym
+
+      if name.to_s.end_with?('=')
+        @data[key] = args.first
+      else
+        @data[key]
+      end
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
+    def to_h
+      @data.dup
+    end
+  end
+end

data/lib/robot_lab/hook_registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class HookRegistry
+    Registration = Data.define(:handler_class, :context) do
+      def initialize(handler_class:, context: nil)
+        super
+      end
+
+      def namespace
+        handler_class.namespace
+      end
+    end
+
+    def initialize
+      @registrations = []
+    end
+
+    # Register a hook handler class.
+    #
+    # @param handler_class [Class] a RobotLab::Hook subclass
+    # @param context [Hash, nil] optional default values merged into ctx.local on each call
+    # @return [Registration]
+    def on(handler_class, context: nil)
+      unless handler_class.is_a?(Class) && handler_class < RobotLab::Hook
+        raise ArgumentError, "#{handler_class.inspect} must be a RobotLab::Hook subclass"
+      end
+      raise ArgumentError, "#{handler_class} has no namespace" if handler_class.namespace.nil?
+
+      registration = Registration.new(handler_class: handler_class, context: context)
+      @registrations << registration
+      registration
+    end
+
+    # Returns registrations whose handler implements the given hook method.
+    #
+    # @param hook_name [Symbol]
+    # @return [Array<Registration>]
+    def registrations_for(hook_name)
+      hook_sym = hook_name.to_sym
+      @registrations.select { |reg| reg.handler_class.singleton_class.public_method_defined?(hook_sym) }
+    end
+
+    # Returns all registrations (defensive copy).
+    #
+    # @return [Array<Registration>]
+    def registrations
+      @registrations.dup
+    end
+
+    def clear
+      @registrations.clear
+    end
+  end
+end

data/lib/robot_lab/hooks.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Hooks
+    module_function
+
+    def run(family, context, registries:, per_run_hooks: nil, &)
+      before = registrations(:"before_#{family}", registries, per_run_hooks)
+      around = registrations(:"around_#{family}", registries, per_run_hooks)
+      after  = registrations(:"after_#{family}", registries, per_run_hooks)
+      errors = error_registrations(family, registries, per_run_hooks)
+
+      call_all(before, :"before_#{family}", context)
+      result = call_around(around, :"around_#{family}", context, &)
+      set_result(context, family, result)
+      call_all(after, :"after_#{family}", context)
+      result
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      context.error = e if context.respond_to?(:error=)
+      call_all(errors, :on_error, context)
+      raise
+    end
+
+    def call(hook_name, context, registries:, per_run_hooks: nil)
+      call_all(registrations(hook_name, registries, per_run_hooks), hook_name, context)
+    end
+
+    def around(hook_name, context, registries:, per_run_hooks: nil, &)
+      call_around(registrations(hook_name, registries, per_run_hooks), hook_name, context, &)
+    end
+
+    def registrations(hook_name, registries, per_run_hooks)
+      registry_entries = registries.compact.flat_map { |registry| registry.registrations_for(hook_name) }
+      registry_entries + per_run_entries(hook_name, per_run_hooks)
+    end
+
+    def error_registrations(family, registries, per_run_hooks)
+      return [] unless %i[run network_run task].include?(family.to_sym)
+
+      registrations(:on_error, registries, per_run_hooks)
+    end
+
+    def call_all(registrations, hook_name, context)
+      registrations.each { |registration| call_registration(registration, hook_name, context) }
+    end
+
+    def call_around(registrations, hook_name, context, &block)
+      chain = registrations.reverse.inject(block) do |next_link, registration|
+        proc { call_registration(registration, hook_name, context, &next_link) }
+      end
+
+      chain.call
+    end
+
+    def call_registration(registration, hook_name, context, &)
+      context.with_namespace(registration.namespace) do
+        if registration.context && registration.namespace
+          context.ext(registration.namespace).merge_defaults(registration.context)
+        end
+        registration.handler_class.call(hook_name, context, &)
+      end
+    end
+
+    # per_run_hooks is now a single handler class or an array of handler classes.
+    def per_run_entries(hook_name, hooks)
+      return [] unless hooks
+
+      hook_sym = hook_name.to_sym
+      Array(hooks).filter_map do |handler_class|
+        next unless handler_class.singleton_class.public_method_defined?(hook_sym)
+
+        HookRegistry::Registration.new(handler_class: handler_class)
+      end
+    end
+
+    def set_result(context, family, result)
+      case family.to_sym
+      when :run
+        context.response = result if context.respond_to?(:response=)
+      when :network_run, :task
+        context.result = result if context.respond_to?(:result=)
+      when :llm_generation
+        context.generation_response = result if context.respond_to?(:generation_response=)
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/client.rb

@@ -141,8 +141,7 @@ module RobotLab
       #
       def get_prompt(name, arguments = {})
         ensure_connected!
-        response = request(method: "prompts/get", params: { name: name, arguments: arguments })
-        response
+        request(method: "prompts/get", params: { name: name, arguments: arguments })
       end
 
       # Checks if the client is connected to the server.

data/lib/robot_lab/mcp/connection_poller.rb

@@ -115,7 +115,7 @@ module RobotLab
           client.transport.stdin.flush
         rescue Errno::EPIPE, IOError => e
           @mutex.synchronize { @clients[io][:queue] = nil }
-          raise MCPError, "MCP connection lost: #{e.message}"
+          raise MCPError.new("MCP connection lost: #{e.message}", retryable: true)
         end
 
         response = Timeout.timeout(timeout) { queue.pop }
@@ -127,7 +127,7 @@ module RobotLab
         response
       rescue Timeout::Error
         @mutex.synchronize { @clients[io]&.[]= :queue, nil }
-        raise MCPError, "MCP server did not respond within #{timeout}s"
+        raise MCPError.new("MCP server did not respond within #{timeout}s", retryable: true)
       ensure
         @mutex.synchronize { @clients[io]&.[]= :queue, nil }
       end
@@ -145,15 +145,15 @@ module RobotLab
         loop do
           ios = @mutex.synchronize { @clients.keys.reject(&:closed?) }
 
-          unless ios.empty?
+          if ios.empty?
+            sleep POLL_INTERVAL
+          else
             begin
               ready, = IO.select(ios, nil, nil, POLL_INTERVAL)
               dispatch(ready) if ready
             rescue Errno::EBADF
               # A pipe was closed between the reject and IO.select — harmless, loop again
             end
-          else
-            sleep POLL_INTERVAL
           end
 
           break unless @mutex.synchronize { @running }

data/lib/robot_lab/mcp/server.rb

@@ -99,7 +99,7 @@ module RobotLab
 
         seconds = value.to_f
         # If the caller passed milliseconds (>= 1000), convert to seconds
-        seconds = seconds / 1000.0 if seconds >= 1000
+        seconds /= 1000.0 if seconds >= 1000
         [seconds, 1].max
       end
     end

data/lib/robot_lab/mcp/server_discovery.rb

@@ -76,8 +76,6 @@ module RobotLab
         from
       end
 
-      private
-
       # @param servers [Array<Hash, MCP::Server>]
       def self.any_descriptions?(servers)
         servers.any? { |s| !description_for(s).empty? }