samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -1,191 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "registry"
-require "digest"
-require_relative "../log"
-require_relative "../guardrails/load_failures"
-require_relative "../memory_bundle/bundle_hook"
-require_relative "../memory_bundle/provenance"
-
-module Samagotchi
-  # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
-  # evaluated inside `Samagotchi::Bundles::<BundleName>` so that two bundles
-  # shipping a file with the same basename (e.g. `guardrails.rb`) cannot collide
-  # on a top-level constant.
-  module Bundles; end
-
-  module Hooks
-    # Loads bundle-owned hook plugins into a Registry.
-    #
-    # Unlike +Hooks::Loader+ (which `require`s a file and resolves a top-level
-    # constant), this loader `module_eval`s each plugin file inside a
-    # per-bundle namespace module. This gives:
-    #   - zero class-name collisions across bundles
-    #   - a clean uninstall path (`Registry#unregister_bundle`)
-    #
-    # Each plugin must define a class whose PascalCase name matches the file
-    # basename and whose instances respond to +call(event)+.
-    #
-    # A "fail_closed" before_tool_call hook is required: if it is missing,
-    # fails to load, or its file's sha256 differs from the one recorded at
-    # install, the failure is reported and the gate denies every tool call.
-    # Any hook whose sha256 differs is not loaded (reinstall the bundle
-    # after editing a hook by hand), nor any of a bundle whose requires_chi
-    # this chi doesn't meet.
-    #
-    # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
-    #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
-    #     the tool call (fail-closed).
-    #   - "log": warn to stderr and continue.
-    #   - "skip" (default): silently continue.
-    # Whatever the policy, a hook file that raises is told to the user once
-    # per hook (its +hook_failed+ callback, the Engine's
-    # HookRoutes#plugin_hook_failed): :skip would otherwise leave no trace.
-    module BundleLoader
-      class << self
-        # Load all hook plugins for a bundle into the given registry.
-        #
-        # @param bundle_name [String]
-        # @param hooks_dir [String] directory containing the bundle's .rb hook files
-        # @param metadata [Hash] basename => { event:, on_error:, priority:,
-        #   sha256: } (MemoryBundle::BundleHook.parse reads it)
-        # @param registry [Samagotchi::Hooks::Registry]
-        # @param failures [Guardrails::LoadFailures, nil] collects hooks that
-        #   failed to load
-        # @param settings [Hash] the bundle's section of config.yml
-        #   `bundles:` (string keys); a hook class whose initialize takes an
-        #   argument gets it
-        # @param manifest [MemoryBundle::InstalledManifest, nil] the installed
-        #   bundle's manifest; when this chi doesn't meet its requires_chi no
-        #   hook loads (each is reported, as the plugin loader does)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   when a hook file raises at fire time — the Engine's HookRoutes;
-        #   nil when there is no UI to tell (the test kit)
-        # @return [Integer] number of hooks successfully registered
-        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, manifest: nil, hook_failed: nil)
-          return 0 unless metadata.is_a?(Hash)
-
-          too_old = manifest&.requires_chi_failure
-          loaded = 0
-          metadata.each do |raw_basename, raw_meta|
-            basename = raw_basename.to_s
-            next if basename.empty?
-
-            hook = MemoryBundle::BundleHook.parse(raw_meta)
-            # A hook with no declared event cannot be auto-registered.
-            next if hook.events.empty?
-
-            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
-            what = "hook #{basename} (bundle #{bundle_name})"
-            file = hooks_dir && File.join(hooks_dir, basename)
-            unless file && File.exist?(file)
-              failures&.add(what, "the file is missing", required: true) if fail_closed
-              next
-            end
-            if (mismatch = too_old || sha_mismatch(file, hook.sha256, required: fail_closed))
-              Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
-              failures&.add(what, mismatch, required: fail_closed)
-              next
-            end
-
-            begin
-              load_hook_file(bundle_name, basename, file, hook, registry, settings: settings, hook_failed: hook_failed)
-              loaded += 1
-            rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-              raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-              Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
-              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed,
-                                  location: Guardrails::LoadFailures.location(e, File.dirname(hooks_dir)))
-            end
-          end
-          loaded
-        end
-
-        # Build one hook file and register it in +registry+ under each of
-        # its events (one instance for all: its state is shared), with its
-        # priority and error policy (a fail_closed before_tool_call one
-        # denies when it raises). No missing-file, sha or requires_chi
-        # check: #load makes them; the test kit loads a bundle's source
-        # this way.
-        # @param hook [MemoryBundle::BundleHook] its manifest entry
-        # @param namespace [Module, nil] the module the file is evaluated
-        #   in (default: the bundle's, #namespace_for)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   on every raise at fire time, whatever the policy; nil gives no
-        #   notice (the log still has a :log hook's failures)
-        # @raise [Exception] what loading or building the file raised;
-        #   nothing is registered then
-        def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil, hook_failed: nil)
-          plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          hook.events.each do |event_name|
-            event_sym = event_name.to_sym
-            fail_closed = hook.fail_closed?(event_sym)
-            policy = if fail_closed then :deny
-                     elsif hook.on_error == "log" then :log
-                     else :skip
-                     end
-            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-            # Every policy tells, once per label: a hook file under the
-            # default :skip would raise with no trace anywhere. The label
-            # names the file, the bundle and the event, so one label per
-            # hook and a stream hook can't nag.
-            on_failure = hook_failed && lambda { |hook_label, failed|
-              hook_failed.call("#{hook_label} #{event_sym} hook", failed, effect: policy)
-            }
-            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                                 fields: { bundle: bundle_name }, on_failure: on_failure) { |event| plugin.call(event) }
-            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
-          end
-          nil
-        end
-
-        # Why the file doesn't match the sha256 recorded at install, or nil.
-        # With none recorded, only a required hook counts as a mismatch.
-        def sha_mismatch(file, recorded, required:)
-          return nil if MemoryBundle::Provenance.unchecked?(recorded)
-
-          expected = MemoryBundle::Provenance.recorded_sha(recorded)
-          return (required ? "no sha256 recorded for it (reinstall the bundle)" : nil) if expected.empty?
-
-          actual = MemoryBundle::Provenance.file_sha(file)
-          return nil if actual == expected
-
-          "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
-        end
-
-        # Evaluate a plugin file inside the bundle's namespace module (or
-        # +namespace+) and
-        # return an instance that responds to #call. A class whose
-        # initialize takes an argument gets the settings (one Hash, string
-        # keys); one that takes none is built bare.
-        def instantiate(bundle_name, basename, file, settings: {}, namespace: nil)
-          ns = namespace || namespace_for(bundle_name)
-          content = File.read(file)
-          ns.module_eval(content, file, 1)
-          klass = Hooks.class_for(basename, ns)
-          instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
-
-          instance
-        end
-
-        # The (lazily created) namespace module for a bundle.
-        # Sanitization is made injective by appending a short digest so that
-        # `my-bundle` and `my_bundle` do not collide.
-        def namespace_for(bundle_name)
-          raw = bundle_name.to_s
-          base = raw.gsub(/[^A-Za-z0-9_]/, "_")
-          base = "B_#{base}" unless base.match?(/\A[A-Z]/)
-          digest = Digest::MD5.hexdigest(raw)[0, 4]
-          ns_name = "#{base}_#{digest}"
-          if Samagotchi::Bundles.const_defined?(ns_name.to_sym, false)
-            Samagotchi::Bundles.const_get(ns_name.to_sym)
-          else
-            Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/samagotchi/send_command/wait_target.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../delivery"
-require_relative "../reply_wait"
-require_relative "../session"
-
-module Samagotchi
-  class SendCommand
-    # Which turn chi send --wait waits for and names in its report:
-    # ReplyWait's +turn+ (an enqueued_id; nil: the next reply), +queued+
-    # and +ended_before+, and ParentWait's +report_turn_id+ (the turn_id
-    # of the --format json line). Each run path builds it its way.
-    WaitTarget = Data.define(:turn, :report_turn_id, :queued, :ended_before) do
-      def initialize(turn: nil, report_turn_id: nil, queued: false, ended_before: false) = super
-
-      # A --new session's first message: its own turn, the ack's id (a
-      # file-delivered one's also names the outcome of a session command
-      # that runs no turn), so a worker that dies in it and the next one's
-      # settle end the wait (TurnCheckpoint.settled_turn). A message merged
-      # into a turn starting then falls back to that turn's reply
-      # (ReplyWait's turn: without queued:); no id (an older worker), the
-      # next reply. A prompt the session was created with has no delivery:
-      # its turn is the id the create gave it (+direct_turn+,
-      # Session#first_turn_id), and nothing can merge into it, so the wait
-      # is for that turn alone (ReplyWait's queued:).
-      # @param delivered [SessionManager::DeliverResult, nil] nil when the
-      #   message started the session itself (no delivery)
-      # @param direct_turn [String, nil] that first turn's id, for a direct
-      #   start
-      def self.first_message(delivered, direct_turn: nil)
-        return new unless delivered || !direct_turn.to_s.strip.empty?
-
-        return new(turn: direct_turn, report_turn_id: direct_turn, queued: true) if delivered.nil?
-
-        new(turn: delivered.enqueued_id, report_turn_id: delivered.enqueued_id)
-      end
-
-      # A message to an existing session. --queue: its own turn, the ack's
-      # id, also when the turn running at the check ended before it went in
-      # (an idle worker's ack says next_step, and the file still runs as
-      # that turn). A file fallback's id names its turn too, and so does a
-      # plain message to an idle session, as #first_message's. Otherwise
-      # (a session left running by a dead worker, the busy check's owner
-      # gone) the next reply, reported as the turn that was running when it
-      # went in (+running_turn+, ReplyWait.own_turn). A plain message the
-      # worker queued (its ack says queue: a participant's review turn was
-      # running, which takes no steer) is a --queue's.
-      # @param running [Boolean] the session was running when it went in
-      def self.message(delivered, queue:, running:, running_turn:)
-        queue ||= delivered.delivery == Delivery::QUEUE
-        turn = delivered.enqueued_id if queue || delivered.file? || !running
-        report = if queue then turn
-                 elsif running then running_turn
-                 else delivered.enqueued_id
-                 end
-        new(turn: turn, report_turn_id: report, queued: queue && !turn.nil?)
-      end
-
-      # --wait with no message: --turn's (+requested+), or the turn running
-      # now or whose continue offer stands (ReplyWait.own_turn). Settled
-      # (idle, a turn ended, no question standing: a continue offer waits
-      # for its answer), its last turn's end is the answer (ended_before);
-      # with --turn, when that turn is the last one.
-      def self.wait_only(session, session_dir:, requested:)
-        settled = session.status == Session::STATUS_IDLE && !session.last_turn.nil? && session.pending_question.nil?
-        own = requested ? nil : ReplyWait.own_turn(session, session_dir: session_dir)
-        wait_only_of(own_turn: own, settled: settled, last_turn_id: session.last_turn&.enqueued_id, requested: requested)
-      end
-
-      # #wait_only from what SessionAccess#prepare_wait read
-      # (SessionAccess::WaitStart): its own_turn, settled and last_turn_id.
-      def self.after(start, requested:)
-        wait_only_of(own_turn: start.own_turn, settled: start.settled, last_turn_id: start.last_turn_id,
-                     requested: requested)
-      end
-
-      def self.wait_only_of(own_turn:, settled:, last_turn_id:, requested:)
-        turn = requested || own_turn
-        ended_before = requested ? last_turn_id == requested : settled
-        new(turn: turn, report_turn_id: turn || (last_turn_id if settled), ended_before: ended_before)
-      end
-      private_class_method :wait_only_of
-    end
-  end
-end