samagotchi 0.8.1 → 0.10.0

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -30,9 +30,9 @@ module Samagotchi
     # Any hook whose sha256 differs is not loaded (reinstall the bundle
     # after editing a hook by hand).
     #
-    # The +on_error+ policy is applied per hook at fire time:
-    #   - "fail_closed" (on :before_tool_call): a raising guardrail sets
-    #     event[:blocked] = true — the tool call is prevented (fail-closed).
+    # 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.
     module BundleLoader
@@ -80,16 +80,14 @@ module Samagotchi
 
             begin
               plugin = instantiate(bundle_name, basename, file, settings: settings)
-              log_failure = Hooks.failure_log_gate(event_sym)
-
-              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority) do |event|
-                begin
-                  plugin.call(event)
-                rescue Exception => e
-                  # A veto always applies; only the log line is throttled.
-                  handle_error(bundle_name, basename, on_error, fail_closed, event, e) if fail_closed || log_failure.call
-                end
-              end
+              policy = if fail_closed then :deny
+                       elsif on_error == "log" then :log
+                       else :skip
+                       end
+              label = "#{fail_closed ? "guardrail " : ""}#{basename} (bundle #{bundle_name})"
+              handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                   fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority, &handler)
               loaded += 1
             rescue Exception => e
               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)
@@ -119,10 +117,9 @@ module Samagotchi
           ns = namespace_for(bundle_name)
           content = File.read(file)
           ns.module_eval(content, file, 1)
-          class_name = File.basename(basename, ".rb").split("_").map(&:capitalize).join
-          klass = ns.const_get(class_name, false)
+          klass = Hooks.class_for(basename, ns)
           instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
           instance
         end
 
@@ -141,20 +138,6 @@ module Samagotchi
             Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
           end
         end
-
-        # Apply the per-hook on_error policy when a plugin raises.
-        def handle_error(bundle_name, basename, on_error, fail_closed, event, error)
-          if fail_closed && event.is_a?(Hash)
-            event[:blocked] = true
-            reason = "guardrail #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}"
-            event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
-            existing = event[:block_reason].to_s
-            event[:block_reason] = existing.empty? ? reason : "#{existing}; #{reason}"
-          elsif on_error == "log"
-            Log.warn(:hooks, "bundle_hook_failed", echo: "[samagotchi:hooks] #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}", bundle: bundle_name, hook: basename.to_s, error: error.class.name)
-          end
-          # "skip" (and fail_closed on non-veto events) is silent.
-        end
       end
     end
   end

data/lib/samagotchi/hooks/loader.rb

@@ -41,6 +41,15 @@ module Samagotchi
           File.join(ConfigFile.config_dir(env: env), "hooks", "")
         end
 
+        # The hooks folder: config.yml's hooks.hooks_dir, or the default,
+        # "~" expanded.
+        # @param data [Hash, nil] the parsed config.yml (read when not given)
+        def hooks_dir(env = ENV, data: ConfigFile.read_yaml(path: ConfigFile.global_path(env: env)))
+          section = data.is_a?(Hash) ? data["hooks"] : nil
+          configured = section.is_a?(Hash) ? section["hooks_dir"] : nil
+          expand_path(configured || default_hooks_dir(env), env)
+        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
@@ -52,7 +61,7 @@ module Samagotchi
           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)
+          hooks_dir = hooks_dir(env, data: config_hash)
 
           registry = Hooks::Registry.new
           definitions = parse_definitions(hooks_config)
@@ -60,20 +69,10 @@ module Samagotchi
           definitions.each do |defn|
             begin
               plugin = load_plugin(hooks_dir, defn[:path], settings: defn[:settings])
-              log_failure = Hooks.failure_log_gate(defn[:event_type])
               # 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) if log_failure.call
-                  end
-                end
-              end
+              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)",
+                                           &wrapped(plugin, defn))
             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)
@@ -130,33 +129,24 @@ module Samagotchi
 
         @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)
+          klass = Hooks.class_for(path)
           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)
+          raise ArgumentError, "Plugin #{klass.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
+      # The plugin's #call under the entry's error policy: a required
+      # before_tool_call hook that raises denies the call; otherwise
+      # on_error: log warns and skip is silent.
+      def self.wrapped(plugin, defn)
+        if defn[:required] && defn[:event_type] == "before_tool_call"
+          policy, label = :deny, "required hook #{defn[:path]}"
+        else
+          policy, label = (defn[:on_error] == "log" ? :log : :skip), "#{defn[:path]} (config)"
         end
+        Hooks.wrap(label: label, event: defn[:event_type].to_sym, policy: policy) { |event| plugin.call(event) }
       end
     end
   end

data/lib/samagotchi/hooks/registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "../log"
 
 module Samagotchi
   module Hooks
@@ -36,6 +37,46 @@ module Samagotchi
       end
     end
 
+    # A hook file's class: the PascalCase of its basename (my_hook.rb →
+    # MyHook), looked up in +namespace+ (a bundle's module; Object for a
+    # config hook).
+    # @return [Class]
+    def self.class_for(file, namespace = Object)
+      namespace.const_get(File.basename(file.to_s, ".rb").split("_").map(&:capitalize).join, false)
+    end
+
+    # A hook's block wrapped in its error policy: what a loader registers.
+    # When the block raises,
+    #   :deny  denies the call (event[:guardrail], the Gate's Verdict),
+    #          whatever was raised: a fail-closed before_tool_call guardrail.
+    #          The Gate folds the verdict into event[:blocked] and
+    #          event[:block_reason] for the hooks after it.
+    #   :log   warns (a stream hook at most once a minute, failure_log_gate)
+    #   :skip  is silent
+    # :log and :skip rescue StandardError and ScriptError.
+    # @param label [String] the hook, for the deny reason and the warning
+    # @param event [Symbol] the hook's event
+    # @param log [Array(Symbol, String)] the warning's tag and record name
+    # @param echo [Boolean] the warning also goes to stderr
+    # @param fields [Hash] more fields for the warning's record
+    def self.wrap(label:, event:, policy:, log: [:hooks, "hook_failed"], echo: true, fields: {}, &block)
+      log_failure = failure_log_gate(event)
+      lambda do |payload|
+        block.call(payload)
+      rescue Exception => e # rubocop:disable Lint/RescueException -- :deny fails closed on anything
+        raise unless policy == :deny || e.is_a?(StandardError) || e.is_a?(ScriptError)
+
+        failed = "#{e.class}: #{e.message}"
+        if policy == :deny
+          payload[:guardrail]&.deny!("#{label} raised #{failed}", rule: "guardrail-load", source: "core", decided_by: "core") if payload.is_a?(Hash)
+        elsif policy == :log && log_failure.call
+          text = "#{label} failed: #{failed}"
+          Log.warn(log[0], log[1], echo: echo ? "[samagotchi:hooks] #{text}" : nil, hook: label, event: event.to_s,
+                                   error: e.class.name, msg: text, **fields)
+        end
+      end
+    end
+
     # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:) and shows one line to the user; +ask_user+

data/lib/samagotchi/hooks.rb

@@ -26,8 +26,5 @@ module Samagotchi
   #                         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

data/lib/samagotchi/host_registry.rb

@@ -77,6 +77,7 @@ module Samagotchi
     # @param clock [#call, nil] monotonic seconds (specs)
     def initialize(hosts_config: nil, env: ENV, client_override: nil, clock: nil)
       @client_override = client_override
+      @env = env
       @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       @adapters = {}
       @host_lists = {}
@@ -133,6 +134,20 @@ module Samagotchi
       ConfigFile.parse_host_qualified_model(raw, hosts: @entries)
     end
 
+    # The names a models: entry may be under, in the order they are looked
+    # up: +typed+ as given (maybe an alias), its alias's target, +resolved+
+    # (what the model became, e.g. the default for a blank one), the part
+    # after a host prefix, and the bare model the host is asked for.
+    # Thinking, SamplingSettings, VisionSupport and ModelProfile all take these.
+    # @param target [ModelTarget, nil] the resolved model's target (resolved when not given)
+    # @return [Array<String>]
+    def lookup_names(typed, resolved: nil, target: nil)
+      aliased = ConfigFile.resolve_model_alias(typed, env: @env)
+      target ||= resolve(resolved || aliased)
+      [typed, aliased, resolved, parse_qualified_model(typed).last, target.bare_model]
+        .map { |name| name.to_s.strip }.reject(&:empty?).uniq
+    end
+
     # Resolve model string (already alias-resolved, may be qualified) to a HostEntry.
     # If qualified explicitly, return that host. If unqualified, try cached model index,
     # else fallback to default host.

data/lib/samagotchi/idle_reminders.rb

@@ -36,13 +36,6 @@ module Samagotchi
       @due_reminder_name = nil
     end
 
-    # Get the currently pending due reminder name (for Engine to read).
-    # Kept for backward compatibility.
-    # Called by Engine#collect_due_reminders. Thread-safe.
-    def due_reminder_name
-      @mutex.synchronize { @due_reminder_name }
-    end
-
     # Get all due reminders (from ReminderStore). Called by Engine#collect_due_reminders.
     # Thread-safe. Returns all due reminders, not just one.
     # @return [Array<Hash>] [{name:, description:, interval_minutes:}, ...]

data/lib/samagotchi/image_store.rb

@@ -197,6 +197,8 @@ module Samagotchi
     REF_RE = %r{\Aimages/[0-9a-f]{16}\.(png|jpe?g|gif|webp)\z}
     MIME = { png: "image/png", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" }.freeze
     EXT = { png: "png", jpeg: "jpg", gif: "gif", webp: "webp" }.freeze
+    # The most images one turn may carry (a client's refs, check_refs).
+    MAX_TURN_REFS = 20
     # Nothing larger is even read.
     MAX_SOURCE_BYTES = 50 * 1024 * 1024
 
@@ -251,6 +253,26 @@ module Samagotchi
       File.file?(path) && !File.symlink?(path)
     end
 
+    # A turn's images from a client (the web, a Bridge request) as
+    # [{file:, name:}], or a String saying what's wrong. Only refs to files
+    # already in the session's images/ pass (an upload): never a path, so no
+    # client can make the worker read a file.
+    def self.check_refs(session_dir, raw)
+      return [] if raw.nil?
+      return "images must be a list" unless raw.is_a?(Array)
+      return "at most #{MAX_TURN_REFS} images" if raw.size > MAX_TURN_REFS
+
+      raw.map do |image|
+        return "each image must be {file:, name:}" unless image.is_a?(Hash)
+
+        ref = symbolize(image)
+        return "images are refs to uploaded files, not paths" if ref.key?(:path)
+        return "unknown image #{ref[:file].to_s[0, 80]}" unless valid_ref?(session_dir, ref)
+
+        { file: ref[:file].to_s, name: File.basename(ref[:name].to_s)[0, 120] }
+      end
+    end
+
     # Messages seeded into another session (a plugin's ctx.sessions.fork):
     # each image ref's file is copied from +from+ into +to+ (both session
     # dirs; no +from+ copies none). A ref whose file isn't there is dropped, and its message says

data/lib/samagotchi/kernel_loop.rb

@@ -141,8 +141,8 @@ module Samagotchi
     # Run the conversation loop and return the final model response plus
     # resumable conversation state when execution stops at max_iterations.
     #
-    # @param messages       [Array<Hash>, Result] conversation so far ({role:, content:})
-    #                                           or a previous Result to resume
+    # @param messages       [Array<Hash>]        conversation so far ({role:, content:});
+    #   a stopped run resumes from its Result#conversation
     # @param max_iterations [Integer]            safety cap on tool-call rounds
     # @param on_stream_event [Proc, nil]         optional callback for generation events
     # @param cancel_controller [CancellationController, nil] optional cancellation source
@@ -170,7 +170,6 @@ module Samagotchi
       empty_retries = 0
       empty_retry_limit = EmptyAnswerRetry.limit
       @retry_generation = false
-      stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
       # Qwen with thinking off: an empty thought after the cue, so the model
       # answers at once. Kept in the turn's model messages, so each tool-loop
       # prompt starts with what the server already has cached.
@@ -192,6 +191,9 @@ module Samagotchi
           conversation << line
           prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
         end
+        # Each generation splits its own stream: one that ended inside a
+        # thought or a tool call doesn't leave the next one "inside" it.
+        stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
         emit_stream_event(
           on_stream_event,
           type: :generation_started,
@@ -235,6 +237,7 @@ module Samagotchi
                   type: :generation_chunk,
                   iteration: iteration_index + 1,
                   content: chunk[:content],
+                  text: split[:text],
                   thinking: split[:thinking],
                   payload: chunk[:payload]
                 )
@@ -263,9 +266,8 @@ module Samagotchi
           ""
         end
         if cut
-          # The cut stream may have stopped mid-block, and its visible text
-          # goes with it: a fresh splitter, the buffer as it was before.
-          stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
+          # The cut stream's visible text goes with it: the buffer as it was
+          # before (the next generation gets a fresh splitter).
           partial_assistant_buffer.slice!(buffer_mark..)
           emit_stream_event(on_stream_event, type: :generation_completed, iteration: iteration_index + 1,
                                              content_length: 0, thinking_chars: streamed_thinking,
@@ -660,8 +662,8 @@ module Samagotchi
     private
 
     # The generation's thinking: what the stream split into the thinking
-    # lane (Qwen), else what the profile's thought blocks hold (Gemma's
-    # stream isn't split).
+    # lane, else what the profile's thought blocks hold (an empty thought, a
+    # bare Gemma <|think|> cue, a response that wasn't streamed).
     def thinking_chars(response, streamed)
       return streamed if streamed.positive?
 
@@ -687,14 +689,8 @@ module Samagotchi
       end
     end
 
-    def prepare_conversation(messages)
-      if messages.is_a?(Result)
-        duplicate_conversation(messages.conversation)
-      else
-        # Standard multi-turn compliance: never pass prior raw thought blocks.
-        sanitize_history(messages)
-      end
-    end
+    # Standard multi-turn compliance: never pass prior raw thought blocks.
+    def prepare_conversation(messages) = sanitize_history(messages)
 
     def duplicate_conversation(messages)
       messages.map(&:dup)

data/lib/samagotchi/live_versions.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "socket"
 require_relative "session"
 require_relative "version"
 require_relative "worker_sidecar"
@@ -12,7 +11,6 @@ module Samagotchi
   # older one names none) and a `chi web` on its port (/api/info). Read-only:
   # a dead worker's sidecar is left for the next client to clean up.
   module LiveVersions
-    PROBE_TIMEOUT = 0.2
     WEB_TIMEOUT = 0.5
 
     # version is nil for a sidecar written before sidecars carried one.
@@ -24,8 +22,8 @@ module Samagotchi
     def workers(state_dir: Session.default_state_dir)
       Dir[File.join(state_dir, "*", WorkerSidecar::FILE)].sort.filter_map do |path|
         session_dir = File.dirname(path)
-        sidecar = WorkerSidecar.read(session_dir)
-        next unless sidecar && listening?(sidecar.port)
+        sidecar = WorkerSidecar.live(session_dir, unlink: false)
+        next unless sidecar
 
         Worker.new(session_id: File.basename(session_dir), version: sidecar.version)
       end
@@ -48,14 +46,5 @@ module Samagotchi
       info = Web::InfoProbe.call(host, port, timeout: timeout)
       info.is_a?(Hash) ? info : nil
     end
-
-    def listening?(port, host: "127.0.0.1")
-      return false unless port.positive?
-
-      Socket.tcp(host, port, connect_timeout: PROBE_TIMEOUT).close
-      true
-    rescue StandardError
-      false
-    end
   end
 end