samagotchi 0.5.0 → 0.6.0

data/lib/samagotchi/guardrail_wiring.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "digest"
+require "yaml"
+
+require_relative "config"
+require_relative "log"
+require_relative "guardrails"
+require_relative "hooks"
+require_relative "edit_preview"
+require_relative "tool_activity"
+
+module Samagotchi
+  # An Engine's tool guardrails: who can approve (the interface), the YAML
+  # rules (config.yml's and installed bundles', reloaded on a file change),
+  # the load failures, the protected paths, the approvals store, the context
+  # a tool call is judged in, the approval question, and the Gate the kernel
+  # asks before every tool call.
+  #
+  # What it needs from the Engine comes through lookups, read at call time.
+  class GuardrailWiring
+    # @return [Guardrails::LoadFailures] what failed to load (hooks, rules)
+    attr_reader :failures
+
+    # @return [Guardrails::Approvals]
+    attr_reader :approvals
+
+    # @param scratch   [Boolean] a `chi scratch` session (writes into the memories are denied)
+    # @param hooks     [#call] → Hooks::Registry
+    # @param tools     [#call] → Tools::Registry
+    # @param session   [#call] → Session, nil
+    # @param model_key [#call] → String, the effective model's overlay key
+    # @param cancelled [#call] → Boolean, whether the running turn is cancelled
+    # @param ask       [#call] (fields) → the answer; the Engine's question flow
+    def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:)
+      @scratch = scratch
+      @hooks_lookup = hooks
+      @tools_lookup = tools
+      @session_lookup = session
+      @model_key_lookup = model_key
+      @cancelled_lookup = cancelled
+      @ask = ask
+      @failures = Guardrails::LoadFailures.new
+      @rules_mutex = Mutex.new
+      @git = Guardrails::GitInfo.new
+    end
+
+    # Who can answer an approval: :repl, :worker or :non_interactive (the
+    # default, so a bare Engine denies instead of waiting for nobody). Set
+    # by the host (TerminalUI, Worker).
+    def interface
+      @interface || :non_interactive
+    end
+
+    def interface=(value)
+      value = value.to_sym
+      raise ArgumentError, "unknown interface #{value}" unless Guardrails::Context::INTERFACES.include?(value)
+
+      @interface = value
+    end
+
+    # Where the approval store lives: beside Session's state dir
+    # ($XDG_STATE_HOME/samagotchi/guardrails/).
+    def state_dir=(state_dir)
+      @approvals = Guardrails::Approvals.new(dir: Guardrails::Approvals.dir_for(state_dir))
+      @protected = nil
+    end
+
+    # A turn starts: its origin, and the git facts read afresh.
+    def begin_turn(origin)
+      @origin = origin
+      @git = Guardrails::GitInfo.new
+    end
+
+    # The gate every tool call asks first.
+    # @return [Guardrails::Gate]
+    def gate
+      Guardrails::Gate.new(
+        -> { @hooks_lookup.call },
+        context_lookup: -> { context },
+        model_key_lookup: -> { @model_key_lookup.call },
+        approver: ->(verdict) { request_approval(verdict) },
+        approvals_lookup: -> { @approvals },
+        checks_lookup: -> { checks },
+        cancelled_lookup: -> { @cancelled_lookup.call },
+        tools_lookup: -> { @tools_lookup.call }
+      )
+    end
+
+    # The gate's core checks, in order.
+    def checks
+      rules = self.rules
+      [@failures, rules.hook_asks, protected_paths, (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch),
+       rules].compact
+    end
+
+    # The YAML rules: config.yml's `guardrails:` section (rules, disable) and
+    # installed bundles'. One that doesn't parse is a required load failure
+    # (every call is denied). Read again when one of those files changed
+    # (a stat of each per tool call), so a long-lived worker follows edits.
+    # @return [Guardrails::Rules]
+    def rules
+      @rules_mutex.synchronize do
+        stamp = rules_stamp
+        if @rules.nil? || stamp != @rules_stamp
+          @failures.drop(:rules)
+          @rules = load_rules
+          @rules_stamp = stamp
+        end
+        @rules
+      end
+    end
+
+    # Installed bundles' guardrails/*.yml, by bundle name then file name.
+    # A file that is missing, changed since install (sha256) or doesn't
+    # parse is a required load failure.
+    def bundle_rules
+      require_relative "memory_bundle/provenance"
+      rules = []
+      MemoryBundle::Provenance.each_installed_with_guardrails do |bundle_name, data|
+        if data[:error]
+          Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{data[:error]}", bundle: bundle_name)
+          @failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
+          next
+        end
+        dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
+        data[:guardrails].sort_by { |k, _| k.to_s }.each do |basename, meta|
+          what = "rules #{basename} (bundle #{bundle_name})"
+          path = File.join(dir, basename.to_s)
+          begin
+            raise Guardrails::Rules::ParseError, "the file is missing" unless File.file?(path)
+
+            expected = (meta.is_a?(Hash) ? meta[:sha256] : nil).to_s.sub(/\Asha256:/, "")
+            actual = Digest::SHA256.hexdigest(File.binread(path))
+            if expected != actual
+              raise Guardrails::Rules::ParseError, "its sha256 differs from the installed one (edited after install? reinstall the bundle)"
+            end
+
+            doc = YAML.safe_load(File.read(path))
+            raise Guardrails::Rules::ParseError, "expected a mapping with rules:" unless doc.is_a?(Hash)
+
+            rules.concat(Guardrails::Rules.parse(doc["rules"], source: "bundle #{bundle_name}"))
+          rescue Guardrails::Rules::ParseError, Psych::Exception => e
+            Log.warn(:guardrails, "rules_file_invalid", echo: "[samagotchi:guardrails] #{what}: #{e.message}", bundle: bundle_name, file: basename.to_s)
+            @failures.add(what, e.message, required: true, group: :rules)
+          end
+        end
+      end
+      rules
+    rescue StandardError => e
+      Log.error(:guardrails, "bundle_rules_failed", echo: "[samagotchi:guardrails] failed to read installed bundles' rules: #{e.class}: #{e.message}", error: e.class.name)
+      @failures.add("bundle rules", "#{e.class}: #{e.message}", required: true, group: :rules)
+      rules || []
+    end
+
+    def protected_paths
+      @protected ||= begin
+        require_relative "memory_bundle/provenance"
+        config = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
+        hooks_dir = config.is_a?(Hash) && config["hooks"].is_a?(Hash) ? config["hooks"]["hooks_dir"] : nil
+        Guardrails::ProtectedPaths.new(
+          store_dir: File.dirname(@approvals.path),
+          bundles_dir: MemoryBundle::Provenance.bundles_dir,
+          config_path: Samagotchi::ConfigFile.global_path,
+          hooks_dir: Hooks::Loader.expand_path(hooks_dir || Hooks::Loader.default_hooks_dir)
+        )
+      end
+    end
+
+    # The context the gate sees for a tool call now.
+    # @return [Guardrails::Context]
+    def context
+      Guardrails::Context.new(cwd: Dir.pwd, session_id: @session_lookup.call&.id, interface: interface,
+                              origin: @origin, git: @git)
+    end
+
+    # Ask the user to approve a call the gate voted `ask` on, through the
+    # question flow (REPL sync handler, attached TUI, web). Settles the
+    # verdict: allow with the picked scope, or deny with a note for the
+    # model. A --non-interactive run has no one to ask and denies at once.
+    # @param verdict [Guardrails::Verdict]
+    # @return [Guardrails::Verdict]
+    def request_approval(verdict)
+      if interface == :non_interactive
+        return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it (non-interactive run).")
+      end
+
+      # A plugin tool is asked about by its label, as its row shows it.
+      label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools_lookup.call)
+      # verdict.call is the call that will run (a hook may have replaced it).
+      payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call))
+      Guardrails::Approval.settle(verdict, @ask.call(payload), payload[:approval][:scopes])
+    end
+
+    private
+
+    # [path, mtime, size] of config.yml and every installed bundle's
+    # manifest.json and guardrails/ file.
+    def rules_stamp
+      require_relative "memory_bundle/provenance"
+      paths = [Samagotchi::ConfigFile.global_path] +
+              Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "{manifest.json,guardrails/*}")]
+      paths.compact.sort.map do |path|
+        stat = File.stat(path)
+        [path, stat.mtime.to_r, stat.size]
+      rescue SystemCallError
+        [path]
+      end
+    end
+
+    def load_rules
+      section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
+      section = section["guardrails"] if section.is_a?(Hash)
+      rules = []
+      disable = []
+      begin
+        raise Guardrails::Rules::ParseError, "guardrails must be a mapping" unless section.nil? || section.is_a?(Hash)
+
+        rules = Guardrails::Rules.parse(section && section["rules"], source: "config")
+        disable = Guardrails::Rules.parse_disable(section && section["disable"])
+      rescue Guardrails::Rules::ParseError => e
+        Log.warn(:guardrails, "config_rules_invalid", echo: "[samagotchi:guardrails] config.yml guardrails rules: #{e.message}")
+        @failures.add("rules in config.yml", e.message, required: true, group: :rules)
+      end
+      Guardrails::Rules.new(rules + bundle_rules, disable: disable,
+                            enabled: Samagotchi::Config.get("guardrails.enabled") != false)
+    end
+
+    # The dry-run diff of an edit/write call for its approval; a preview
+    # that fails only leaves the diff out, it never denies the call.
+    def approval_preview(call)
+      EditPreview.for(call)
+    rescue StandardError => e
+      Log.warn(:guardrails, "edit_preview_failed", error: "#{e.class}: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/samagotchi/hooks/registry.rb

@@ -22,8 +22,10 @@ module Samagotchi
     # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
-    # when queued). A registry without one gives hooks no-op helpers.
-    Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, keyword_init: true)
+    # when queued); +stop_generation+ takes (reason:, hook:) and cuts the
+    # streaming generation while the turn goes on (true when it did). A
+    # registry without one gives hooks no-op helpers.
+    Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, :stop_generation, keyword_init: true)
 
     # A thread-safe registry for named hook callbacks.
     #
@@ -35,7 +37,8 @@ module Samagotchi
     # 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
+    # +event[:ask_user]+, +event[:stop_turn]+, +event[:steer]+ and
+    # +event[:stop_generation]+ (see #fire). Keys the fire
     # site put on the event are never overwritten.
     #
     # Thread safety is achieved via Monitor.
@@ -274,6 +277,11 @@ module Samagotchi
 
           @runtime&.steer&.call(text: text.to_s, hook: event[:hook]) ? true : false
         }
+        event[:stop_generation] ||= lambda { |reason|
+          next false if TURN_OVER_EVENTS.include?(event[:type])
+
+          @runtime&.stop_generation&.call(reason: reason.to_s, hook: event[:hook]) ? true : false
+        }
       end
     end
   end

data/lib/samagotchi/hooks/stream_watch.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+
+module Samagotchi
+  module Hooks
+    # Fires the :generation_progress hook while a turn's model response
+    # streams (docs/hooks.md), batched so it can't slow the stream: when
+    # EVERY_CHARS new chars (thinking + text) are pending, or EVERY_SECONDS
+    # passed since the last fire with anything pending. Checked on each
+    # chunk: there is no timer thread, and the hook runs on the turn's
+    # thread, inside the HTTP read.
+    #
+    # The Engine builds one per turn, only when a hook listens, and feeds it
+    # each chunk after the UIs got it. Nothing fires once the turn or the
+    # generation is cancelled (lines already read still come after the
+    # socket closed), and there is no end-of-generation flush:
+    # :after_generation sees the whole response.
+    class StreamWatch
+      EVENT = :generation_progress
+      EVERY_CHARS = 2000
+      EVERY_SECONDS = 1.0
+      # A hook slower than this is logged (stream_hook_slow), once per turn.
+      SLOW_SECONDS = 0.1
+
+      # @param hooks [Registry]
+      # @param cancel_controller [CancellationController] the turn's
+      # @param clock [#call] monotonic seconds
+      def initialize(hooks:, cancel_controller:, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @hooks = hooks
+        @cancel_controller = cancel_controller
+        @clock = clock
+        @slow_logged = false
+        @iteration = nil
+      end
+
+      # A new generation (:generation_started).
+      def started(iteration)
+        @iteration = iteration
+        @started_at = @last_fire_at = @clock.call
+        @thinking = +""
+        @text = +""
+        @thinking_chars = 0
+        @text_chars = 0
+      end
+
+      # One chunk's new thinking and visible text.
+      def feed(thinking:, text:)
+        return unless @iteration
+        return if @cancel_controller.cancelled? || @cancel_controller.generation_cancelled?
+
+        thinking = thinking.to_s
+        text = text.to_s
+        @thinking << thinking
+        @text << text
+        @thinking_chars += thinking.length
+        @text_chars += text.length
+        pending = @thinking.length + @text.length
+        return if pending.zero?
+
+        now = @clock.call
+        fire(now) if pending >= EVERY_CHARS || now - @last_fire_at >= EVERY_SECONDS
+      end
+
+      private
+
+      def fire(now)
+        event = { type: EVENT, iteration: @iteration, thinking: @thinking.freeze, text: @text.freeze,
+                  thinking_chars: @thinking_chars, text_chars: @text_chars,
+                  elapsed_ms: ((now - @started_at) * 1000).round,
+                  # A question would hold the HTTP read for minutes.
+                  ask_user: ->(**) {} }
+        @thinking = +""
+        @text = +""
+        @last_fire_at = now
+        hook_started = @clock.call
+        @hooks.fire_each(EVENT, event) do |fired|
+          done = @clock.call
+          slow(fired[:hook], done - hook_started)
+          hook_started = done
+        end
+        @last_fire_at = @clock.call
+      end
+
+      def slow(hook, seconds)
+        return if @slow_logged || seconds <= SLOW_SECONDS
+
+        @slow_logged = true
+        Log.warn(:turn, "stream_hook_slow", hook: hook.to_s, iteration: @iteration, ms: (seconds * 1000).round)
+      end
+    end
+  end
+end

data/lib/samagotchi/hooks.rb

@@ -3,6 +3,7 @@
 require_relative "hooks/registry"
 require_relative "hooks/loader"
 require_relative "hooks/bundle_loader"
+require_relative "hooks/stream_watch"
 
 module Samagotchi
   # Thin wrapper that exposes the Hooks::Registry, Hooks::Loader and
@@ -18,6 +19,8 @@ module Samagotchi
   #   :after_turn         — after the turn completes (success or cancel)
   #   :before_generation  — before calling the LLM API
   #   :after_generation   — after LLM returns, before tool parse
+  #   :generation_progress — while a response streams, batched (StreamWatch);
+  #                         event[:stop_generation] cuts it, the turn goes on
   #   :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)

data/lib/samagotchi/kernel_loop.rb

@@ -255,9 +255,14 @@ module Samagotchi
         # Fire :before_generation hook
         gen_event = { type: :before_generation, iteration: iteration_index + 1 }
         fire_hook(:before_generation, gen_event) if @hooks
-        response = @client.complete(
-          prompt,
-          **complete_kwargs(
+        # The request runs under the generation's own controller: a plugin's
+        # stop_generation cuts it alone, and the turn goes on (a cut).
+        buffer_mark = partial_assistant_buffer.length
+        cut = nil
+        response = with_generation(cancel_controller) do |generation_controller|
+          request_generation(
+            prompt,
+            generation_controller: generation_controller,
             cancel_controller: cancel_controller,
             model_name: resolved_model_name,
             on_chunk: lambda { |chunk|
@@ -295,7 +300,43 @@ module Samagotchi
             },
             images: images
           )
-        )
+        rescue Client::RequestCancelled
+          raise unless cut?(generation_controller, cancel_controller)
+
+          cut = generation_controller.detail || {}
+          ""
+        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)
+          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,
+                                             served_model: served_model, requested_model: resolved_model_name,
+                                             finish_reason: "stopped", stopped_by: cut[:by], stop_reason: cut[:reason])
+          # A Stop that came right after the cut is a plain cancel.
+          raise Client::RequestCancelled.new(cancel_controller.reason) if cancel_controller.cancelled?
+
+          if empty_retries < empty_retry_limit
+            # Queued input (the user's line, a plugin's steer) goes in place of the nudge.
+            next if inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller)
+
+            empty_retries += 1
+            @retry_generation = true
+            emit_stream_event(on_stream_event, type: :empty_answer_retry, iteration: iteration_index + 1,
+                                               attempt: empty_retries, of: empty_retry_limit,
+                                               thinking_chars: streamed_thinking, stopped_by: cut[:by])
+            conversation << TurnNote.cut_retry(cut[:by], cut[:reason])
+            next
+          end
+          # No retry left: the turn ends as cancelled (hook), with nothing
+          # salvaged and without the spent nudge.
+          drop_last_empty_retry!(conversation)
+          cancel_controller.cancel!(:hook)
+          emit_stream_event(on_stream_event, type: :generation_cancelled, iteration: iteration_index + 1, reason: :hook)
+          return cancelled_result(conversation, tool_activity: tool_activity, reason: :hook, partial_assistant_text: "")
+        end
         # What the server's prompt count covers, so the next estimate adds
         # only what the turn appended since (answer, tool results).
         context_state[:counted] = { chars: prompt.length, image_tokens: image_tokens } if generation_usage
@@ -538,6 +579,25 @@ module Samagotchi
       self.class.resolve_output_char_cap(override)
     end
 
+    # One request, cancelled by +generation_controller+ (the turn's child)
+    # when there is one.
+    def request_generation(prompt, generation_controller:, cancel_controller:, **options)
+      @client.complete(prompt, **complete_kwargs(cancel_controller: generation_controller || cancel_controller, **options))
+    end
+
+    # Yields the turn controller's child for one generation (nil without a
+    # controller).
+    def with_generation(cancel_controller, &block)
+      return yield(nil) unless cancel_controller
+
+      cancel_controller.generation(&block)
+    end
+
+    # The generation was cut (stop_generation) and the turn goes on.
+    def cut?(generation_controller, cancel_controller)
+      generation_controller&.cancelled? && !cancel_controller.cancelled?
+    end
+
     def complete_kwargs(cancel_controller:, model_name: nil, on_chunk: nil, on_retry: nil, images: [])
       kwargs = {}
       # Only a request with images names them: a text-only call is unchanged.
@@ -903,8 +963,7 @@ module Samagotchi
     end
 
     def drop_last_empty_retry!(conversation)
-      nudge = TurnNote.empty_retry
-      index = conversation.rindex { |entry| entry[:kind] == nudge[:kind] && entry[:content] == nudge[:content] }
+      index = conversation.rindex { |entry| TurnNote.retry_nudge?(entry) }
       conversation.delete_at(index) if index
     end
 

data/lib/samagotchi/llm/chat_loop.rb

@@ -221,6 +221,7 @@ module Samagotchi
           message[:tool_params] = entry[:tool_params] if entry[:tool_params]
           message[:tool_labels] = entry[:tool_labels] if entry[:tool_labels]
           message[:tool_diffs] = entry[:tool_diffs] if entry[:tool_diffs]
+          message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
@@ -336,6 +337,13 @@ module Samagotchi
             response, partial = generate(iteration)
             return canceled(iteration, response, partial) if partial
 
+            if response.cut
+              outcome = after_cut(iteration, response)
+              next if outcome == :retry
+
+              return outcome
+            end
+
             last_text = @loop.strip_model_thought(response.text)
             if response.tool_calls.empty?
               # Kept before a merge too: the model answers the merged line
@@ -393,6 +401,32 @@ module Samagotchi
           true
         end
 
+        # A generation a plugin cut (stop_generation) is an empty answer made
+        # early: asked again with its own nudge while the retry budget lasts
+        # (queued input goes in place of the nudge), else the turn ends as
+        # cancelled (hook), with nothing salvaged and without a spent nudge.
+        # A Stop that came right after the cut is a plain cancel. Returns
+        # :retry, or the turn's result.
+        def after_cut(iteration, response)
+          return canceled(iteration, @cancel_controller.reason) if @cancel_controller.cancelled?
+
+          if @empty_retries < @empty_retry_limit
+            return :retry if inject_pending_input(iteration)
+
+            @empty_retries += 1
+            @retry_generation = true
+            emit(type: :empty_answer_retry, iteration: iteration, attempt: @empty_retries, of: @empty_retry_limit,
+                 finish_reason: response.finish_reason, thinking_chars: response.reasoning.to_s.length,
+                 stopped_by: response.cut[:by])
+            @conversation << TurnNote.cut_retry(response.cut[:by], response.cut[:reason])
+            return :retry
+          end
+          index = @conversation.rindex { |entry| TurnNote.retry_nudge?(entry) }
+          @conversation.delete_at(index) if index
+          @cancel_controller.cancel!(:hook)
+          canceled(iteration, :hook)
+        end
+
         # The host's reasoning, kept on the model message as +thinking+ for
         # the web turn view's reload (the whole of it, as the live view
         # shows). Only saved: #assistant_message builds the wire message from
@@ -412,15 +446,22 @@ module Samagotchi
                context_window_source: window&.source)
           @loop.fire_hook(:before_generation, { type: :before_generation, iteration: iteration })
           streamed = +""
-          response = begin
-            request(iteration, retry_generation, streamed)
-          rescue BadRequest => e
-            raise unless thinking_refused?(e)
-
-            # Once per model: asked again without the thinking fields.
-            @loop.thinking_refused!(@model_name)
-            emit(type: :thinking_refused, iteration: iteration, model: @model_name, level: @loop.thinking, detail: e.detail)
-            request(iteration, retry_generation, streamed)
+          thought = +""
+          response = with_generation do |generation_controller|
+            begin
+              request(iteration, retry_generation, streamed, thought, generation_controller)
+            rescue BadRequest => e
+              raise unless thinking_refused?(e)
+
+              # Once per model: asked again without the thinking fields.
+              @loop.thinking_refused!(@model_name)
+              emit(type: :thinking_refused, iteration: iteration, model: @model_name, level: @loop.thinking, detail: e.detail)
+              request(iteration, retry_generation, streamed, thought, generation_controller)
+            end
+          rescue RequestCancelled
+            raise unless generation_controller&.cancelled? && !@cancel_controller.cancelled?
+
+            return cut_response(iteration, thought, generation_controller.detail || {})
           end
           record_context_status(response.usage, window)
           emit(type: :generation_completed, iteration: iteration, content_length: response.text.length,
@@ -434,13 +475,34 @@ module Samagotchi
           [e.reason, streamed]
         end
 
-        def request(iteration, retry_generation, streamed)
+        # The request runs under the generation's own controller (the turn
+        # controller's child), so a plugin's stop_generation cuts it alone.
+        def with_generation(&block)
+          return yield(nil) unless @cancel_controller
+
+          @cancel_controller.generation(&block)
+        end
+
+        # The empty response of a cut generation: its spinners close as any
+        # generation's (finish_reason stopped, stopped_by the bundle); no
+        # after_generation (there is no answer to see), and no usage (the
+        # stream never sent its last chunk).
+        def cut_response(iteration, thought, cut)
+          emit(type: :generation_completed, iteration: iteration, content_length: 0, thinking_chars: thought.length,
+               requested_model: @model_name, finish_reason: "stopped", stopped_by: cut[:by], stop_reason: cut[:reason])
+          response = ChatResponse.new(text: "", reasoning: thought, tool_calls: [], usage: nil, finish_reason: "stopped",
+                                      cut: cut)
+          [response, nil]
+        end
+
+        def request(iteration, retry_generation, streamed, thought, generation_controller)
           @loop.adapter.chat(
             messages: @loop.wire_messages(@conversation), tools: @loop.tool_definitions, model: @model_name,
-            cancel_controller: @cancel_controller, session_id: @loop.session_id,
+            cancel_controller: generation_controller || @cancel_controller, session_id: @loop.session_id,
             options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
             on_delta: lambda { |content:, reasoning:, payload:|
               streamed << content
+              thought << reasoning
               emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
                    thinking: reasoning, payload: payload)
             },

data/lib/samagotchi/llm/openai_chat.rb

@@ -34,8 +34,10 @@ module Samagotchi
     # ([] when none), usage (never nil) and the finish reason.
     # +model+ is the model the server says answered (the body's `model`),
     # which can differ from the one asked for; nil when it says nothing.
-    ChatResponse = Data.define(:text, :reasoning, :tool_calls, :usage, :finish_reason, :model) do
-      def initialize(model: nil, **fields) = super
+    # +cut+ is set on the empty response the chat loop makes for a
+    # generation a plugin cut (stop_generation): {by:, reason:}.
+    ChatResponse = Data.define(:text, :reasoning, :tool_calls, :usage, :finish_reason, :model, :cut) do
+      def initialize(model: nil, cut: nil, **fields) = super
     end
 
     # The OpenAI Chat Completions API (llama.cpp's /v1, and any compatible
@@ -218,7 +220,8 @@ module Samagotchi
         SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
       end
 
-      # A String stays a String; an Array of parts passes as given.
+      # A String stays a String; an Array of parts passes as given, its text
+      # parts scrubbed like a String.
       def wire_message(message)
         wire = message.to_h.transform_keys(&:to_sym)
         wire[:content] = format_content(wire[:content]) if wire.key?(:content)
@@ -226,11 +229,20 @@ module Samagotchi
       end
 
       def format_content(content)
-        return content if content.is_a?(Array) || content.nil?
+        return content if content.nil?
+        return content.map { |part| scrub_part(part) } if content.is_a?(Array)
 
         scrub(content.to_s)
       end
 
+      def scrub_part(part)
+        return part unless part.is_a?(Hash)
+
+        part.to_h do |key, value|
+          [key, key.to_s == "text" && value.is_a?(String) ? scrub(value) : value]
+        end
+      end
+
       # Invalid UTF-8 (a tool's garbled output) would make to_json raise.
       def scrub(text)
         text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text