robot_lab 0.2.1 → 0.2.7

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/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