samagotchi 0.2.0

data/lib/samagotchi/hooks/loader.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "../config"
+require_relative "../log"
+
+module Samagotchi
+  module Hooks
+    # Plugin-based hook loader that loads Ruby classes from a directory.
+    #
+    # Each plugin is a `.rb` file that defines a class with a `#call(event)` method.
+    # The class name must match the filename (PascalCase):
+    #   `my_hook.rb` → `MyHook` class
+    #
+    # The loader:
+    # 1. Loads each plugin file via `require` (absolute path)
+    # 2. Instantiates the class
+    # 3. Registers a Proc in the given Registry that calls `plugin.call(event)`
+    #
+    # Plugins are loaded once and cached. The same plugin can be registered
+    # for multiple event types by specifying it multiple times in the config.
+    #
+    # Config format:
+    #   hooks:
+    #     hooks_dir: "~/my_hooks/"   # default: <config dir>/hooks/, next to config.yml
+    #     before_turn:
+    #       - path: "my_hook.rb"
+    #         on_error: skip  # or "log"
+    #       - path: "another.rb"
+    #     before_tool_call:
+    #       - path: "guard.rb"
+    #         required: true  # fail closed: if it can't load, or raises,
+    #                         # tool calls are denied
+    #
+    # The loader creates a `Hooks::Registry` instance, loads plugins, and
+    # registers each plugin's `call` method as a Proc under the specified event name.
+    class Loader
+      class << self
+        # $XDG_CONFIG_HOME/samagotchi/hooks/ or ~/.config/samagotchi/hooks/.
+        def default_hooks_dir(env = ENV)
+          File.join(ConfigFile.config_dir(env: env), "hooks", "")
+        end
+
+        # Load hooks from a config hash and return a Registry with registered plugins.
+        #
+        # @param config_hash [Hash, nil] the hooks section from config.yml
+        # @param env [Hash] environment variables (default: ENV)
+        # @param failures [Guardrails::LoadFailures, nil] collects hooks that
+        #   failed to load
+        # @return [Samagotchi::Hooks::Registry] the registry with all plugins registered
+        def load(config_hash, env: ENV, failures: nil)
+          return Hooks::Registry.new unless config_hash&.key?("hooks")
+
+          hooks_config = config_hash["hooks"]
+          hooks_dir = expand_path(hooks_config["hooks_dir"] || default_hooks_dir(env), env)
+
+          registry = Hooks::Registry.new
+          definitions = parse_definitions(hooks_config)
+
+          definitions.each do |defn|
+            begin
+              plugin = load_plugin(hooks_dir, defn[:path], settings: defn[:settings])
+              # Persistent: config hooks must fire on every turn, not be wiped
+              # by Engine#run_turn's per-turn clear_hooks after turn 1.
+              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)") do |event|
+                begin
+                  plugin.call(event)
+                rescue StandardError => e
+                  if defn[:required] && defn[:event_type] == "before_tool_call"
+                    deny_for_raise(event, defn[:path], e)
+                  else
+                    handle_error(defn[:on_error] || "skip", defn[:path], e)
+                  end
+                end
+              end
+            rescue ScriptError, StandardError => e
+              # ScriptError: a SyntaxError (or LoadError) from `require`.
+              Log.error(:hooks, "hook_load_failed", echo: "[samagotchi:hooks] hook #{defn[:path]} failed to load: #{e.class}: #{e.message}", hook: defn[:path].to_s, error: e.class.name)
+              failures&.add("hook #{defn[:path]} (config)", "#{e.class}: #{e.message}", required: defn[:required])
+            end
+          end
+
+          registry
+        end
+      end
+
+      # Expand a path that may start with ~.
+      def self.expand_path(path, env = ENV)
+        return path unless path.start_with?("~")
+        home = env["HOME"] || Dir.home
+        File.join(home, path[1..])
+      end
+
+      # Parse hook definitions from the config hooks section.
+      # Returns an array of { event_type:, path:, on_error: } hashes.
+      def self.parse_definitions(hooks_config)
+        definitions = []
+        hooks_config.each do |event_type, configs|
+          next unless event_type.to_s != "hooks_dir" && configs.is_a?(Array)
+          configs.each do |cfg|
+            next unless cfg.is_a?(Hash) && cfg["path"]
+            definitions << {
+              event_type: event_type.to_s,
+              path: cfg["path"],
+              on_error: (cfg["on_error"] || "skip").to_s,
+              required: cfg["required"] == true,
+              settings: cfg["settings"].is_a?(Hash) ? cfg["settings"] : {}
+            }
+          end
+        end
+        definitions
+      end
+
+      # Load a plugin from the hooks directory.
+      # Returns an instance of the plugin class. Instances are cached per
+      # [path, settings] across Engines: two entries with different
+      # settings get two instances.
+      # @param settings [Hash] the entry's `settings:` (string keys); a
+      #   class whose initialize takes an argument gets it
+      def self.load_plugin(hooks_dir, path, settings: {})
+        full_path = File.expand_path(File.join(hooks_dir, path))
+        settings = {} unless settings.is_a?(Hash)
+
+        # Check if already loaded (Ruby's require caching handles this)
+        # We cache the instance separately to avoid re-instantiating
+        unless @plugin_cache
+          @plugin_cache = {}
+        end
+
+        @plugin_cache[[full_path, settings]] ||= begin
+          require full_path
+          class_name = File.basename(path, ".rb").split("_").map(&:capitalize).join
+          klass = Object.const_get(class_name)
+          instance = Hooks.build_plugin(klass, settings)
+          # Validate that the instance responds to #call
+          raise ArgumentError, "Plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          instance
+        end
+      end
+
+      # A required before_tool_call hook that raises denies the call.
+      def self.deny_for_raise(event, hook_path, error)
+        return unless event.is_a?(Hash)
+
+        reason = "required hook #{hook_path} raised #{error.class}: #{error.message}"
+        event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
+        event[:blocked] = true
+        event[:block_reason] ||= reason
+      end
+
+      # Handle a hook error based on the on_error config.
+      def self.handle_error(on_error, hook_path, error = nil)
+        case on_error
+        when "log"
+          Log.warn(:hooks, "hook_failed", echo: "[samagotchi:hook] #{error ? "#{error.class}: #{error.message}" : "hook failed"} (#{hook_path})", hook: hook_path.to_s, error: error&.class&.name)
+        when "skip"
+          # Silent — just skip
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/hooks/registry.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Samagotchi
+  module Hooks
+    # A hook plugin instance: a class whose initialize takes an argument
+    # gets its settings (one positional Hash with string keys), any other
+    # is built bare. `initialize(**kw)` is not told apart (arity -1 too)
+    # and not supported.
+    # @param klass [Class]
+    # @param settings [Hash]
+    def self.build_plugin(klass, settings)
+      takes_settings = klass.instance_method(:initialize).arity != 0
+      takes_settings ? klass.new(settings.is_a?(Hash) ? settings : {}) : klass.new
+    end
+
+    # What a hook can do beyond reading its event: the Engine's three
+    # callables, each given the hook's label. +notify+ takes
+    # (text:, level:, hook:) and shows one line to the user; +ask_user+
+    # takes (question:, options:, header:, allow_freeform:, hook:) and
+    # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
+    # cancels the running turn (true when it did). A registry without one
+    # gives hooks no-op helpers.
+    Runtime = Struct.new(:notify, :ask_user, :stop_turn, keyword_init: true)
+
+    # A thread-safe registry for named hook callbacks.
+    #
+    # Each hook is stored as a Proc that receives an event hash (passed by
+    # reference — mutations on the hash survive). The registry supports
+    # per-hook registration/unregistration, clearing all hooks, and
+    # synchronous dispatch.
+    #
+    # Every fire puts the hook runtime on the event: +event[:hook]+ (the
+    # label of the proc about to run: "<file> (bundle <name>)", a config
+    # hook's label, or "turn hook"), and the helpers +event[:notify]+,
+    # +event[:ask_user]+ and +event[:stop_turn]+ (see #fire). Keys the fire
+    # site put on the event are never overwritten.
+    #
+    # Thread safety is achieved via Monitor.
+    class Registry
+      TURN_HOOK_LABEL = "turn hook"
+      CONFIG_HOOK_LABEL = "config hook"
+      # Events after which there is no turn left to stop.
+      TURN_OVER_EVENTS = %i[after_turn session_end].freeze
+
+      # @return [Runtime, nil] what the helpers call (the Engine sets it)
+      attr_accessor :runtime
+
+      def initialize
+        @mutex = Monitor.new
+        @hooks = {} # name -> Array<Proc> (manual, turn-scoped hooks, run last)
+        @persistent_hooks = {} # name -> Array<{label:, proc:}> (config.yml hooks, survive clear_all)
+        @bundle_hooks = {} # name -> Array<{bundle:, hook_name:, priority:, proc:}>
+        @runtime = nil
+      end
+
+      # Register a hook with the given name.
+      # Multiple hooks can be registered under the same name; they fire in
+      # registration order.
+      # @param name [Symbol] hook event identifier
+      # @param block [Proc] receives an event hash (mutated in place)
+      # @return [void]
+      def register(name, &block)
+        raise ArgumentError, "hook name must be a Symbol" unless name.is_a?(Symbol)
+        raise ArgumentError, "hook block is required" unless block_given?
+        @mutex.synchronize { (@hooks[name] ||= []) << block }
+      end
+
+      # Register a process-scoped plain hook (config.yml). Unlike #register it
+      # survives the per-turn #clear_all, so configured hooks fire on every
+      # turn, not only the first. Fires after bundle hooks, before
+      # turn-scoped ones.
+      # @param name [Symbol] hook event identifier
+      # @param label [String, nil] what event[:hook] names the hook by
+      #   (the loader passes the file); default "config hook"
+      # @return [void]
+      def register_persistent(name, label: nil, &block)
+        raise ArgumentError, "hook name must be a Symbol" unless name.is_a?(Symbol)
+        raise ArgumentError, "hook block is required" unless block_given?
+        label = label.to_s.strip
+        label = CONFIG_HOOK_LABEL if label.empty?
+        @mutex.synchronize { (@persistent_hooks[name] ||= []) << { label: label, proc: block } }
+      end
+
+      # Register a bundle-owned hook. Bundle hooks are ordered by
+      # (priority, bundle_name, hook_name) and fire BEFORE any plain
+      # (config.yml / manual) hooks registered via #register.
+      #
+      # @param bundle_name [String] owning bundle
+      # @param event_name [Symbol] hook event identifier
+      # @param hook_name [String] logical hook name (e.g. file basename)
+      # @param priority [Integer] lower runs first
+      # @return [void]
+      def register_bundle(bundle_name, event_name, hook_name:, priority: 100, &block)
+        raise ArgumentError, "hook block is required" unless block_given?
+        @mutex.synchronize do
+          (@bundle_hooks[event_name] ||= []) << {
+            bundle: bundle_name,
+            hook_name: hook_name,
+            priority: priority,
+            proc: block
+          }
+        end
+      end
+
+      # Unregister all hooks owned by a bundle.
+      # @param bundle_name [String]
+      # @param event_name [Symbol, nil] restrict to one event (nil = all events)
+      # @return [Integer] number of hooks removed
+      def unregister_bundle(bundle_name, event_name = nil)
+        removed = 0
+        @mutex.synchronize do
+          if event_name
+            arr = @bundle_hooks[event_name]
+            return 0 unless arr
+            before = arr.size
+            @bundle_hooks[event_name] = arr.reject { |h| h[:bundle] == bundle_name }
+            removed = before - @bundle_hooks[event_name].size
+            @bundle_hooks.delete(event_name) if @bundle_hooks[event_name].empty?
+          else
+            @bundle_hooks.each do |_event, arr|
+              before = arr.size
+              arr.reject! { |h| h[:bundle] == bundle_name }
+              removed += before - arr.size
+            end
+            @bundle_hooks.reject! { |_, arr| arr.empty? }
+          end
+        end
+        removed
+      end
+
+      # Unregister a hook by name.
+      # @param name [Symbol]
+      # @return [Boolean] true if it was removed, false if not found
+      def unregister(name)
+        @mutex.synchronize do
+          removed_plain = @hooks.delete(name)
+          removed_persistent = @persistent_hooks.delete(name)
+          !!(removed_plain || removed_persistent)
+        end
+      end
+
+      # Remove all turn-scoped hooks (registered via #register).
+      # Bundle hooks (#unregister_bundle) and config hooks (#register_persistent)
+      # are process-scoped and survive the per-turn clear_all, so guardrails
+      # and configured hooks apply to every turn.
+      # @return [void]
+      def clear_all
+        @mutex.synchronize do
+          @hooks.clear
+        end
+      end
+
+      # Dispatch an event to all registered hooks under the given name.
+      #
+      # Each hook receives the *same* event hash by reference, so hooks can
+      # mutate fields to affect downstream behavior. A hook that raises is
+      # caught and ignored so that one misbehaving hook cannot break the
+      # running turn.
+      #
+      # Ordering: bundle hooks (sorted by priority, then bundle, then hook
+      # name) fire first; config hooks next; turn-scoped hooks last, each in
+      # registration order.
+      #
+      # All procs get the same hash, so event[:hook] is set before each one;
+      # the helpers are set once per fire and read event[:hook] when called:
+      #   event[:notify].call(text, level: :info)   one line to the user
+      #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false)
+      #     -> {selected:, freeform:, selected_indices:} or nil (no one to
+      #     ask, cancelled, bad options)
+      #   event[:stop_turn].call(reason) -> true when the turn was cancelled;
+      #     in a before_tool_call event it also denies the call; from
+      #     after_turn / session_end it does nothing (false)
+      #
+      # @param name [Symbol] the hook name to fire
+      # @param event [Hash] the event payload (may be mutated by hooks)
+      # @return [void]
+      def fire(name, event)
+        procs = ordered_procs(name)
+        return if procs.empty?
+
+        with_runtime(event)
+        procs.each do |label, hook_proc|
+          event[:hook] = label if event.is_a?(Hash)
+          begin
+            hook_proc.call(event)
+          rescue StandardError
+            # A failing hook must not break the turn.
+          end
+        end
+      end
+
+      # Like #fire, and yields the event after each hook (a raising one
+      # too), so the caller can fold what that hook did before the next one
+      # runs (the guardrail gate keeps a deny sticky this way).
+      # @yieldparam event [Hash]
+      # @return [void]
+      def fire_each(name, event)
+        procs = ordered_procs(name)
+        return if procs.empty?
+
+        with_runtime(event)
+        procs.each do |label, hook_proc|
+          event[:hook] = label if event.is_a?(Hash)
+          begin
+            hook_proc.call(event)
+          rescue StandardError
+            # A failing hook must not break the turn.
+          end
+          yield event
+        end
+      end
+
+      # @return [Integer] total number of registered hooks (bundle + plain)
+      def size
+        @mutex.synchronize do
+          @hooks.values.sum(&:size) + @persistent_hooks.values.sum(&:size) + @bundle_hooks.values.sum(&:size)
+        end
+      end
+
+      private
+
+      # Returns the ordered [label, proc] pairs for an event: bundle hooks
+      # sorted by (priority, bundle, hook_name), then config hooks, then
+      # turn-scoped hooks, each in registration order.
+      def ordered_procs(name)
+        @mutex.synchronize do
+          bundle_procs = (@bundle_hooks[name] || [])
+            .sort_by { |h| [h[:priority].to_i, h[:bundle].to_s, h[:hook_name].to_s] }
+            .map { |h| ["#{h[:hook_name]} (bundle #{h[:bundle]})", h[:proc]] }
+          config_procs = (@persistent_hooks[name] || []).map { |h| [h[:label], h[:proc]] }
+          turn_procs = (@hooks[name] || []).map { |hook_proc| [TURN_HOOK_LABEL, hook_proc] }
+          bundle_procs + config_procs + turn_procs
+        end
+      end
+
+      # The three helpers, once per fire; a fire site's own keys stay.
+      def with_runtime(event)
+        return unless event.is_a?(Hash)
+
+        event[:notify] ||= lambda { |text, level: :info|
+          @runtime&.notify&.call(text: text.to_s, level: level, hook: event[:hook])
+          nil
+        }
+        event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false|
+          @runtime&.ask_user&.call(question: question, options: options, header: header,
+                                   allow_freeform: allow_freeform, hook: event[:hook])
+        }
+        event[:stop_turn] ||= lambda { |reason|
+          next false if TURN_OVER_EVENTS.include?(event[:type])
+
+          if event[:type] == :before_tool_call && event[:guardrail].respond_to?(:deny!)
+            event[:guardrail].deny!("the turn was stopped by #{event[:hook]}: #{reason}")
+          end
+          @runtime&.stop_turn&.call(reason: reason.to_s, hook: event[:hook]) ? true : false
+        }
+      end
+    end
+  end
+end

data/lib/samagotchi/hooks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "hooks/registry"
+require_relative "hooks/loader"
+require_relative "hooks/bundle_loader"
+
+module Samagotchi
+  # Thin wrapper that exposes the Hooks::Registry, Hooks::Loader and
+  # Hooks::BundleLoader (bundle-owned hook plugins).
+  #
+  # The Engine holds an instance of Hooks::Registry and provides:
+  # - #register_hook(name, &block) — register a turn-scoped hook
+  # - #unregister_hook(name)        — remove a hook
+  # - #clear_hooks                  — auto-cleaned after each run_turn
+  #
+  # Hook event vocabulary:
+  #   :before_turn        — before the turn starts
+  #   :after_turn         — after the turn completes (success or cancel)
+  #   :before_generation  — before calling the LLM API
+  #   :after_generation   — after LLM returns, before tool parse
+  #   :before_tool_call   — before a tool is dispatched: vote with event[:guardrail].deny!/ask!
+  #                         (or the older event[:blocked]=true + event[:block_reason]); the
+  #                         event also has context: and targets: (docs/guardrails.md)
+  #   :after_tool_call    — after tool execution, before result injection
+  module Hooks
+    REGISTRY_CLASS = Registry
+    LOADER_CLASS = Loader
+    BUNDLE_LOADER_CLASS = BundleLoader
+  end
+end