samagotchi 0.141.0 → 0.142.0

data/lib/samagotchi/llm/chat_loop.rb

@@ -11,6 +11,7 @@ require_relative "anthropic_wire"
 require_relative "native_tool_normalizer"
 require_relative "refusal_memo"
 require_relative "stream_drops"
+require_relative "stray_tool_call"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
 require_relative "../answer_refs"
@@ -374,7 +375,7 @@ module Samagotchi
       def strip_model_thought(text) = @kernel.strip_model_thought(text)
 
       def tool_runner
-        @tool_runner ||= ToolRunner.new(@kernel)
+        @tool_runner ||= ToolRunner.new(@kernel, window: -> { context_window(@kernel.turn_settings&.model_name) })
       end
 
       # The window for +model+: the kernel's client probes the server it
@@ -584,6 +585,10 @@ module Samagotchi
           @reasoning_start = ReasoningHistory.run_start(conversation, start || conversation.length)
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
+          # A reply that was only a tool call the host could not read is asked
+          # for once, whatever retry.empty_answer says (a bug fix, not a
+          # preference), at the same retry temperature.
+          @stray_retry = EmptyAnswerRetry.new(limit: 1)
           # The empty generations, never saved: the UIs draw the turn's
           # steps from them (ModelResult#empty_steps).
           @empty_steps = []
@@ -629,6 +634,10 @@ module Samagotchi
             # tool calls that came with it are not run.
             @refusal = refusal_of(response, last_text)
             stopped = @refusal || response.finish_reason.to_s == FILTERED
+            # The budget is for two in a row: a real tool call in between means
+            # the model recovered, and a slip later in a long turn gets its own retry.
+            @stray_retry = EmptyAnswerRetry.new(limit: 1) unless response.tool_calls.empty?
+
             if response.tool_calls.empty? || stopped
               # A refusal is no answer, never asked again; text it streamed
               # before is not kept as one. A filtered answer's text stays,
@@ -637,24 +646,56 @@ module Samagotchi
               last_text = "#{last_text}\n#{FILTERED_MARK}" if !@refusal && response.finish_reason.to_s == FILTERED
               # Only whitespace is no answer either (as in the native loop).
               empty = last_text.strip.empty?
+              # A reply that is nothing but a tool call the host could not
+              # read (LLM::StrayToolCall) is no answer either. Checked here,
+              # before the append, so the bad text never enters the history:
+              # the retry's prompt is the same conversation plus one note, and
+              # nothing is guessed from the block. (:generation_completed and
+              # :after_generation have already seen the text, as they do for
+              # every step; the UIs lose the streamed text with the
+              # :generation_retrying below.)
+              stray = empty || stopped ? nil : LLM::StrayToolCall.shape(last_text)
+              retry_stray = stray && @stray_retry.left? && !@cancel_controller&.cancelled?
+              if stray
+                Log.warn(:model, "generation_malformed", iteration: iteration, shape: stray,
+                                                    finish_reason: response.finish_reason,
+                                                    served_model: response.model,
+                                                    retried: retry_stray,
+                                                    payload: LLM::StrayToolCall.tail(last_text))
+                unless retry_stray
+                  # The second one in a row is no answer and runs no tool: the
+                  # turn fails, and its earlier steps stay (FailedTurn's
+                  # partial conversation, as for any provider error here).
+                  @stray_retry.drop_nudge!(@conversation)
+                  host = host_label
+                  raise LLM::MalformedGeneration.new("#{host}: the reply came back as a #{stray} block the host " \
+                                                    "could not read, twice in a row; nothing was run", host: host)
+                end
+              end
               # Kept before a merge too: the model answers the merged line
               # knowing what it just said.
-              @conversation << with_thinking({ role: "model", content: last_text }, response) unless empty
+              @conversation << with_thinking({ role: "model", content: last_text }, response) unless empty || stray
               retry_empty = empty && !stopped &&
                             @empty_retry.retry_empty?(iteration: iteration, cancelled: @cancel_controller&.cancelled?,
                                                       finish_reason: response.finish_reason,
                                                       used_tokens: response.usage&.total_tokens, window_tokens: @window&.tokens)
-              # An empty answer that will be retried is no answer site: a
-              # plugin's steer joins the retry instead of being dropped, and
-              # queued input (a user's line, a steer) goes in place of the nudge.
-              next if inject_pending_input(iteration, answer: retry_empty ? nil : last_text)
+              # An empty answer or a stray call that will be retried is no
+              # answer site: a plugin's steer joins the retry instead of being
+              # dropped, and queued input (a user's line, a steer) goes in
+              # place of the nudge.
+              next if inject_pending_input(iteration, answer: retry_empty || retry_stray ? nil : last_text)
 
               # An empty answer (content "" + stop, seen from a remote host)
-              # ends the turn with no text: the UIs show their notice.
-              @empty_steps << with_thinking({ role: "model", content: "" }, response) if empty
+              # ends the turn with no text: the UIs show their notice. A stray
+              # reply's text goes to the steps too, so a reload of the turn
+              # can show what the model wrote and did not get run.
+              @empty_steps << with_thinking({ role: "model", content: empty ? "" : last_text }, response) if empty || retry_stray
+              # Nothing of this reply is the turn's answer: a run that runs
+              # out of steps at the retry reports no answer, not the block.
+              last_text = "" if empty || retry_stray
               next if retry_empty && nudge_empty_answer(iteration, response)
+              next if retry_stray && nudge_stray_call(iteration, response, stray)
 
-              last_text = "" if empty
               exhausted = false
               break
             end
@@ -692,6 +733,27 @@ module Samagotchi
                               thinking_chars: response.reasoning.to_s.length)
         end
 
+        # The hidden nudge before the retry of a reply that was only a tool
+        # call (LLM::StrayToolCall). The step's streamed text is void, so the
+        # stream events say so first (:generation_retrying with restarted,
+        # what TurnAccumulator and the web already honour), then the note goes
+        # on the tail (:empty_answer_retry with malformed, the "malformed
+        # answer" line the UIs know) and the next request runs at the retry
+        # sampling. Returns true.
+        def nudge_stray_call(iteration, response, shape)
+          emit(type: :generation_retrying, iteration: iteration, restarted: true, shape: shape)
+          @stray_retry.nudge!(@conversation, TurnNote.malformed_retry,
+                              emit: method(:emit), iteration: iteration, malformed: true, shape: shape,
+                              finish_reason: response.finish_reason, thinking_chars: response.reasoning.to_s.length)
+        end
+
+        # The host a failure is blamed on: the adapter's own name, the model
+        # when the adapter has none.
+        def host_label
+          name = @loop.adapter.host_name if @loop.adapter.respond_to?(:host_name)
+          name.to_s.strip.empty? ? @model_name.to_s : name.to_s
+        end
+
         # A cut generation (CutPolicy): a Stop after it ends the turn as
         # any cancel, the turn going on is :retry, the hook ending is the
         # turn's result.
@@ -737,7 +799,9 @@ module Samagotchi
           @loop.fire_hook(:before_generation, { type: :before_generation, iteration: iteration })
           return [@cancel_controller.reason, "", ""] if @cancel_controller&.cancelled?
 
-          retry_generation = @empty_retry.take_sampling!
+          # The retry of an empty answer, or of a reply that was only a tool
+          # call, runs at the retry temperature.
+          retry_generation = @empty_retry.take_sampling! || @stray_retry.take_sampling!
           emit(type: :generation_started, iteration: iteration, context_window_tokens: window&.tokens,
                context_window_source: window&.source, price: @loop.price&.to_h)
           streamed = +""

data/lib/samagotchi/llm/errors.rb

@@ -244,11 +244,13 @@ module Samagotchi
       def summary = "unexpected response from host #{host}: #{detail}"
     end
 
-    # A native generation that came out corrupt twice (KernelLoop: a tool
-    # call never closed, or a fresh thought header after the answer), the
-    # second time without the server's prompt cache. A poisoned llama.cpp
-    # prompt cache does this (ggml-org/llama.cpp#27148); the text is not
-    # an answer.
+    # A generation that came out corrupt twice, and is no answer. KernelLoop:
+    # a native generation with a tool call never closed, or a fresh thought
+    # header after the answer, the second time asked without the server's
+    # prompt cache (a poisoned llama.cpp prompt cache does this,
+    # ggml-org/llama.cpp#27148). ChatLoop: a reply that is nothing but a
+    # tool-call block the host could not read (LLM::StrayToolCall), asked for
+    # once more with a nudge.
     class MalformedGeneration < ProtocolError
       def summary = "malformed generation from host #{host}: #{detail}"
     end

data/lib/samagotchi/llm/stray_tool_call.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # A reply that is nothing but a tool call written as text. The host's
+    # parser could not read the block, so it came back as plain content with
+    # no tool calls: a Qwen flavour that writes `<parameter=execute>` where
+    # `<function=execute>` belongs, seen twice in 14 days of chat-loop
+    # sessions (docs/internals/engine.md, "A reply that is only a tool call").
+    # It is not an answer, and nothing is guessed from it: ChatLoop asks for
+    # the reply once more, and a second one fails the turn.
+    #
+    # The rule is the narrow one the data supports, and it needs no model
+    # profile (ChatLoop has no ToolCallParser): the whole reply is one closed
+    # block that opens with the call. A reply opening with prose, a fence or
+    # a quote is an answer, and so is one that mentions, quotes or fences the
+    # syntax. KernelLoop has its own path for a corrupt generation
+    # (ToolCallParser#malformed, per profile); this predicate is ChatLoop's.
+    module StrayToolCall
+      # A stray call can only open with the block itself.
+      OPENS = ["<tool_call>", "<function=", "<parameter="].freeze
+      # ... and end with the close of that block: nothing else in the reply.
+      CLOSES = ["</function>", "</parameter>", "</tool_call>"].freeze
+      # A block carries its own tags; an answer that merely starts with a
+      # "<" is not one.
+      INNER_TAG = /<[a-z_]+=/i
+      # How much of the reply the warning keeps (KernelLoop's own cap).
+      TAIL_CHARS = 400
+
+      module_function
+
+      # @return [String, nil] the shape of the reply ("tool_call", "function"
+      # or "parameter") when all of it is one closed tool-call block, nil
+      # when it reads as an answer.
+      # +text+ is the reply with its thought already stripped (ChatLoop's
+      # strip_model_thought).
+      def shape(text)
+        body = text.to_s.strip
+        # The cheap gate: a whole block has to open with the block. This is
+        # the whole cost of the check on a normal answer.
+        return nil unless body.start_with?("<")
+
+        opener = OPENS.find { |open| body.start_with?(open) }
+        return nil if opener.nil?
+        return nil unless CLOSES.any? { |close| body.end_with?(close) }
+
+        # The tags inside it: a lone opening tag in a sentence is not a call
+        # the host tried to read.
+        return nil unless body[1..-2].match?(INNER_TAG)
+
+        opener[/[a-z_]+/]
+      end
+
+      # The tail of a stray reply the log keeps, to see what the host sent.
+      def tail(text)
+        text = text.to_s
+        text.length > TAIL_CHARS ? text[-TAIL_CHARS..] : text
+      end
+    end
+  end
+end

data/lib/samagotchi/log_line.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # (debug dumps) are indented by four spaces and belong to the record above.
   module LogLine
     LEVELS = %w[DEBUG INFO WARN ERROR].freeze
-    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast toolkit].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast toolkit system_one].freeze
     INDENT = "    "
 
     Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)

data/lib/samagotchi/memory_bundle/entry_size.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "index_size"
+require_relative "index_sync"
+require_relative "index_updater"
+require_relative "../model_overlay"
+require_relative "../tools/memory"
+
+module Samagotchi
+  module MemoryBundle
+    # The size of one memory's text, which each memory_read of it pays
+    # (memory_read is not cut by max_tool_output_chars). memory_write and
+    # write/edit on a memory compare the size before and after a write
+    # against memory.entry_warn_tokens (#crossing_note); `chi self` lists
+    # the memories over it (SelfReport). tokens is the estimate IndexSize
+    # uses (characters / context.chars_per_token, rounded up).
+    #
+    # A memory that didn't exist before a write counts as 0 tokens. Not
+    # counted: the index, a model overlay, a model_notes_* memory (it has its
+    # own warning).
+    EntrySize = Data.define(:name, :scope, :tokens) do
+      # @param text [String, nil] the memory's text
+      # @return [EntrySize]
+      def self.of_text(name, scope, text, chars_per_token: IndexSize.chars_per_token)
+        new(name: name.to_s, scope: scope.to_s, tokens: (text.to_s.length / chars_per_token).ceil)
+      end
+
+      # Whether a memory of this name is sized at all (not the index, not a
+      # model note).
+      def self.counted?(name)
+        name = name.to_s
+        !name.casecmp?(IndexUpdater::MEMORY_INDEX) && !name.start_with?(Tools::MODEL_NOTES_PREFIX)
+      end
+
+      # The memory file at +path+ as it is now (0 tokens when it isn't
+      # there), nil when it isn't a counted memory of a scope or
+      # memory.entry_warn_tokens is off, or when it can't be measured (a
+      # write's measure must never fail the write).
+      # @return [EntrySize, nil]
+      def self.measure_file(path)
+        return nil unless warn_limit.positive?
+
+        path = File.expand_path(path.to_s)
+        scope = IndexSync.memory_scope(path)
+        name = File.basename(path, ".md")
+        return nil unless scope && counted?(name) && !ModelOverlay.overlay_file?(path)
+
+        of_text(name, scope, File.file?(path) ? File.read(path, encoding: "UTF-8") : "")
+      rescue StandardError
+        nil
+      end
+
+      # The memories of +scope+ over +limit+ tokens, largest first: each
+      # top-level *.md of its dir but the index, the overlays and the
+      # model notes (hidden files, .bundles/ and archived/ are not in a
+      # top-level glob). Nothing for a limit that isn't positive.
+      # @param env [Hash] the XDG env the memories dir resolves from
+      # @return [Array<EntrySize>]
+      def self.over_limit(scope, limit: warn_limit, env: ENV)
+        return [] unless limit.to_i.positive?
+
+        Dir.glob(File.join(Tools::MemoryRead.memories_dir(scope, env: env), "*.md")).filter_map do |path|
+          name = File.basename(path, ".md")
+          next unless counted?(name) && File.file?(path) && !ModelOverlay.overlay_file?(path)
+
+          size = of_text(name, scope, File.read(path, encoding: "UTF-8"))
+          size if size.over?(limit)
+        end.sort_by { |size| [-size.tokens, size.name] }
+      end
+
+      # memory.entry_warn_tokens: the tokens one memory may hold before a
+      # write that crosses it gets a note; 0 turns the note off.
+      def self.warn_limit
+        Config.get("memory.entry_warn_tokens").to_i
+      rescue StandardError
+        0
+      end
+
+      # The note a write gets when it took the memory from at or under
+      # +limit+ to over it, nil otherwise: once per crossing, as the
+      # index's. Independent of memory.index_warn_tokens.
+      # @param before [EntrySize, nil]
+      # @param after [EntrySize, nil]
+      # @return [String, nil]
+      def self.crossing_note(before, after, limit = warn_limit)
+        return nil unless before && after && after.over?(limit) && !before.over?(limit)
+
+        "Note: memory '#{after.name}' is now ~#{after.tokens} tokens (over memory.entry_warn_tokens #{limit}), paid " \
+          "on each read. When you next have a moment, tighten it; split out only parts that are read separately, " \
+          "since each new memory adds an index line to every prompt. Don't remove or merge memories unless the " \
+          "user asks."
+      end
+
+      # Whether the memory holds more than +limit+ tokens; a limit that
+      # isn't positive is off.
+      def over?(limit) = limit.to_i.positive? && tokens > limit.to_i
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -4,6 +4,7 @@ require_relative "../toolkit"
 require_relative "../log"
 require_relative "../hooks/registry"
 require_relative "../commands/registry"
+require_relative "../system_one/judgments"
 require_relative "service"
 require_relative "tool_result"
 require_relative "tool_spec"
@@ -48,7 +49,8 @@ module Samagotchi
         "ctx.sessions.review" => "0.107.0", "ctx.sessions.send(delivery:)" => "0.64.0",
         "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0",
         "chi.prompt_section" => "0.132.0", "chi.prompt_changed" => "0.132.0", "ctx.cache_confirm" => "0.132.0",
-        "ctx.model_names" => "0.132.0"
+        "ctx.model_names" => "0.132.0", "chi.judgment" => "0.142.0", "ctx.judge" => "0.142.0",
+        "ctx.judge_later" => "0.142.0", "ctx.judgments" => "0.142.0"
         # Unreleased: "ctx.context.propose", "ctx.context.candidates", "ctx.context.withdraw", "ctx.review".
       }.freeze
 
@@ -71,6 +73,7 @@ module Samagotchi
         @toolkits = []
         @prompt_sections = []
         @peer_sources = []
+        @judgments = []
         @tool_source = nil
         @committed = false
       end
@@ -399,6 +402,33 @@ module Samagotchi
         nil
       end
 
+      # A cheap question this bundle asks System 1 (docs/plugins.md,
+      # Judgments): ctx.judge and ctx.judge_later ask it, and each ask saves a
+      # run. Off until the user sets its mode in config.yml's
+      # system_one.judgments, under its full name "<bundle>.<name>".
+      # @param name [String] dot-separated words of a-z, 0-9, _ and -
+      # @param questions [Hash, #call] id => {type:, instructions:, criteria:}
+      #   ("noul", "choice" or "score"), checked now; or a callable given the
+      #   ctx, returning that at each ask, where they vary per session
+      # @param positive [String, Array<String>, nil] the label values that
+      #   say the answer was right, for a later comparison
+      # @param negative [String, Array<String>, nil] and wrong
+      # @param shared_host [Symbol] what to do while a turn runs on the same
+      #   local server, where an ask evicts its cached prompt: :skip saves
+      #   the run unasked (asked: false), :ask asks anyway
+      def judgment(name, questions:, positive: nil, negative: nil, shared_host: :skip)
+        raise ArgumentError, "this chi has no judgments (plugins: false)" unless @registries.judgments
+
+        declaration = SystemOne::Judgments::Declaration.build(bundle: @bundle, name: name, questions: questions, positive: positive,
+                                                              negative: negative, shared_host: shared_host)
+        if @judgments.any? { |item| item.name == declaration.name } || @registries.judgments.declared?(declaration.name)
+          raise ArgumentError, "judgment #{declaration.name} is declared twice"
+        end
+
+        @judgments << declaration
+        nil
+      end
+
       # Register what was staged. Called by Loader after #register. What
       # can only be checked now (an annotation's command) is checked before
       # anything is registered: a raise here leaves the registries as they were.
@@ -439,6 +469,7 @@ module Samagotchi
         end
         @registries.tool_index.add(@tool_source) if @tool_source
         @peer_sources.each { |item| @registries.peer_sources.declare(item[:name], label: item[:label], bundle: @bundle) }
+        @judgments.each { |declaration| @registries.judgments.declare(declaration) }
         @committed = true
       end
 
@@ -446,7 +477,7 @@ module Samagotchi
       def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
                      services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
                      prompt_sections: @prompt_sections.size,
-                     tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size }
+                     tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size, judgments: @judgments.size }
 
       # Each annotation's command is one #command staged.
       def check_annotations!

data/lib/samagotchi/plugin/context.rb

@@ -28,6 +28,7 @@ module Samagotchi
     autoload :Http, File.expand_path("http", __dir__)
     autoload :HttpError, File.expand_path("http", __dir__)
     autoload :HttpCancelled, File.expand_path("http", __dir__)
+    autoload :Judgments, File.expand_path("judgments", __dir__)
 
     # The Engine's side of a Context: callables, so the Engine itself is
     # never handed out. +messages+ returns the conversation, +notify+ takes
@@ -65,11 +66,13 @@ module Samagotchi
     # session's model is looked up under (EffectiveModel#names).
     # +candidate_proposed+ takes (candidate): a late proposal no owner
     # prompt mentions, for the candidate judge (Engine#judge_late_candidates).
+    # +judgments+ returns the SystemOne::Judgments ctx.judge, ctx.judge_later
+    # and ctx.judgments ask and label through.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
                       :cancel_controller, :cost, :usage, :turn_author, :cache_confirm, :model_names,
-                      :candidate_proposed, keyword_init: true)
+                      :candidate_proposed, :judgments, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -407,6 +410,45 @@ module Samagotchi
       # ctx.ask_model's answer limit when none is given.
       ASK_MAX_TOKENS = 1024
 
+      # Ask System 1 this bundle's judgment (chi.judgment, docs/plugins.md,
+      # Judgments) and wait, at most system_one.timeout_ms. A Stop of the
+      # turn cuts an ask made for it. Off, no host, a failed backend or a
+      # skip is a Result with no answers, never a raise.
+      # @param name [String] as declared, without the bundle
+      # @param state [String, Hash, Array] what the question is about; it
+      #   goes to the System 1 host and is saved in the run as sent
+      # @return [SystemOne::Judgments::Result] #answers, #p(id), #run_id,
+      #   #audit?, #no_judgment?, #reason
+      # @raise [ArgumentError] a judgment this bundle didn't declare, a bad
+      #   state, or called in a :generation_progress handler, whose stream it
+      #   would hold (use #judge_later)
+      def judge(name, state:)
+        event = Thread.current[CURRENT_EVENTS]&.[](self)
+        if event.is_a?(Hash) && event[:type] == :generation_progress
+          raise ArgumentError, "ctx.judge would hold the stream in a :generation_progress handler; use ctx.judge_later"
+        end
+
+        judgment_layer.judge(judgment_name(name), state: state, context: self, cancel_controller: http_cancel_controller)
+      end
+
+      # #judge off this thread: the run's id comes back at once and the block
+      # gets the Result later, on another thread, always once. So its ctx.*
+      # act on the session as it is then, not this handler's event. While
+      # this judgment's last judge_later still runs, nothing is asked: a
+      # skipped run, and the block gets a Result with no answers.
+      # @return [String, nil] the run's id; nil when no run will be saved (off,
+      #   no host, runs off, a scratch session, a participant's turn)
+      # @raise [ArgumentError] a judgment this bundle didn't declare, a bad state
+      def judge_later(name, state:, &)
+        judgment_layer.later(judgment_name(name), state: state, context: self, &)
+      end
+
+      # What came of this bundle's judgments' runs: #label, #acted.
+      # @return [Judgments]
+      def judgments
+        @judgments ||= Judgments.new(-> { judgment_layer }, bundle: @bundle)
+      end
+
       # Other sessions: fork one from a conversation, send one a message,
       # read one (Sessions).
       # @return [Sessions]
@@ -493,6 +535,12 @@ module Samagotchi
 
       private
 
+      def judgment_layer
+        @host.judgments&.call or raise ArgumentError, "this chi has no judgments (plugins: false)"
+      end
+
+      def judgment_name(name) = "#{@bundle}.#{name}"
+
       # Whether this plugin's handler runs on this thread (#with_event).
       def in_handler? = !!Thread.current[CURRENT_EVENTS]&.key?(self)
 

data/lib/samagotchi/plugin/judgments.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../system_one/runs"
+
+module Samagotchi
+  module Plugin
+    # ctx.judgments: what came of a bundle's own runs (docs/plugins.md,
+    # Judgments), saved as later lines on them. A bundle's lines say it is
+    # theirs (+by+ is its name), and it reaches no one else's runs.
+    class Judgments
+      MAX_TEXT = 200
+      STRENGTHS = %w[strong weak].freeze
+
+      # @param layer [#call] → the SystemOne::Judgments to save through
+      # @param bundle [String]
+      def initialize(layer, bundle:)
+        @layer = layer
+        @bundle = bundle
+      end
+
+      # The bundle's own word for its run: a raw value now, mapped at analysis.
+      # @param run_id [String, nil] ctx.judge's Result#run_id, or what
+      #   ctx.judge_later returned; nil (no run was saved) saves nothing
+      # @param value [String] up to 200 characters
+      # @param by [String, nil] what said it, after the bundle's name ("card":
+      #   "check-in:card")
+      # @param strength [String, nil] "strong" or "weak"
+      # @param question [String, nil] the question it answers
+      # @return [Boolean] whether it was saved
+      # @raise [ArgumentError] a run of another bundle's, a bad value
+      def label(run_id, value, by: nil, strength: nil, question: nil)
+        value = text("label", value)
+        raise ArgumentError, "strength: is #{STRENGTHS.join(" or ")}, not #{strength.inspect}" unless strength.nil? || STRENGTHS.include?(strength.to_s)
+        return false unless own?(run_id)
+
+        @layer.call.label(run_id, value, by: by.to_s.strip.empty? ? @bundle : "#{@bundle}:#{text("by", by)}",
+                                         strength: strength&.to_s, question: question && text("question", question.to_s))
+      end
+
+      # What the bundle did with the answer: never known when the run is saved.
+      # @param what [String] up to 200 characters
+      # @return [Boolean] whether it was saved
+      # @raise [ArgumentError] a run of another bundle's, a bad value
+      def acted(run_id, what)
+        what = text("acted", what)
+        return false unless own?(run_id)
+
+        @layer.call.acted(run_id, what)
+      end
+
+      private
+
+      # False for nil; a run of anything but a judgment this bundle declared
+      # raises (a name it can't declare has no run of its).
+      def own?(run_id)
+        return false if run_id.nil?
+
+        judgment = SystemOne::Runs.judgment_of(run_id)
+        return true if judgment&.start_with?("#{@bundle}.") && @layer.call.declared?(judgment)
+
+        raise ArgumentError, "#{run_id.inspect} is not a run of bundle #{@bundle}'s"
+      end
+
+      def text(what, value)
+        word = value.to_s.strip
+        return word if value.is_a?(String) && word.length.between?(1, MAX_TEXT)
+
+        raise ArgumentError, "#{what} takes a String of 1 to #{MAX_TEXT} characters, not #{value.inspect[0, 40]}"
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/loader.rb

@@ -22,9 +22,10 @@ module Samagotchi
     # +tool_index+ the Engine's Tools::ToolIndex (chi.tool_source);
     # +peer_sources+ the Engine's PeerSources (chi.peer_source);
     # +prompt_sections+ the Engine's PromptSections (chi.prompt_section),
-    # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!).
+    # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!),
+    # +judgments+ the Engine's SystemOne::Judgments (chi.judgment).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
-                            :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed,
+                            :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed, :judgments,
                             keyword_init: true)
 
     # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})

data/lib/samagotchi/run_options.rb

@@ -207,6 +207,7 @@ module Samagotchi
                  chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
                  chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
                  chi guardrails replay [--dry-run] [--threshold T] [--model M]   seed System 1's record from answered approvals
+                 chi judgments ls | report NAME  System 1's saved asks on this machine
                  chi toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host

data/lib/samagotchi/self_report.rb

@@ -21,6 +21,7 @@ require_relative "memory_bundle/provenance"
 require_relative "memory_bundle/manifest"
 require_relative "memory_bundle/system_bundle"
 require_relative "memory_bundle/index_size"
+require_relative "memory_bundle/entry_size"
 require_relative "desktop"
 require_relative "live_versions"
 require_relative "web/lan"
@@ -60,6 +61,7 @@ module Samagotchi
         ["memories", Tools::MemoryRead.memories_dir("system", env: env)],
         ["project memories", Tools::MemoryRead.memories_dir("project", env: env)],
         ["memory index", memory_index_summary(env)],
+        ["big memories", big_memories_summary(env)],
         ["sessions", Session.default_state_dir(env: env)],
         ["log", log_path(env)],
         ["model", model ? model_label(model, default, env) : "(not configured)"],
@@ -122,6 +124,40 @@ module Samagotchi
       "(unreadable: #{e.message})"
     end
 
+    # How many big memories "big memories" names before "+N more".
+    BIG_MEMORIES_SHOWN = 5
+
+    # The memories over memory.entry_warn_tokens in both scopes, largest
+    # first, "name ~5.6k tokens (system, from samagotchi-system)": each
+    # memory_read of one pays its size, and a memory already over gets no
+    # crossing note. A bundle's memory says whose it is (upstream's to
+    # tighten). "none" when there are none, "off" with the limit 0. A scope
+    # that can't be read is named instead.
+    def big_memories_summary(env)
+      limit = MemoryBundle::EntrySize.warn_limit
+      return "off (memory.entry_warn_tokens 0)" unless limit.positive?
+
+      big = []
+      unreadable = []
+      %w[system project].each do |scope|
+        big.concat(MemoryBundle::EntrySize.over_limit(scope, limit: limit, env: env))
+      rescue StandardError => e
+        unreadable << "#{scope} memories unreadable: #{e.message}"
+      end
+      shown = big.sort_by { |size| [-size.tokens, size.scope, size.name] }.first(BIG_MEMORIES_SHOWN).map { |size| big_memory(size, env) }
+      shown << "+#{big.size - BIG_MEMORIES_SHOWN} more" if big.size > BIG_MEMORIES_SHOWN
+      parts = shown + unreadable.map { |text| "(#{text})" }
+      parts.empty? ? "none" : parts.join(", ")
+    end
+
+    def big_memory(size, env)
+      owner = MemoryBundle::Provenance.claimants("#{size.name}.md", scope: size.scope, dir: MemoryPaths.bundles_dir(env: env)).first
+      where = [size.scope, ("from #{owner}" if owner)].compact.join(", ")
+      "#{size.name} ~#{MemoryBundle::IndexSize.count_text(size.tokens)} tokens (#{where})"
+    rescue StandardError
+      "#{size.name} ~#{MemoryBundle::IndexSize.count_text(size.tokens)} tokens (#{size.scope})"
+    end
+
     def with_presence(path)
       File.exist?(path) ? path : "#{path} (missing)"
     end

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote home].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit judgments remote home].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists