samagotchi 0.40.0 → 0.41.0

data/lib/samagotchi/bundles/system/self_map.md

@@ -77,6 +77,8 @@
 - Installed gem files and bundled memories (`identity`, `memory_guide`,
   `config_modification_protocol`, `self_map`, `delegated`) are managed: don't edit them
   (local edits conflict on upgrade).
-  Put notes in my own memories. A model-only note is an overlay on an existing
-  entry (`current_model_only: true`), and it needs that base entry to exist.
+  Put notes in my own memories. Guidance for some models only is a model note
+  (`model_notes_<name>`, first line `models: <glob>`; memory_guide); a model-only
+  addition to one memory is an overlay on it (`current_model_only: true`), and it
+  needs that base entry to exist.
 - Config edits: follow `config_modification_protocol`.

data/lib/samagotchi/config.rb

@@ -146,6 +146,9 @@ module Samagotchi
       Entry.new(key: "context.status",           yaml_path: %w[context status],           type: :bool,   default: true,             expose: %i[env config cli]),
       Entry.new(key: "context.window_tokens",    yaml_path: %w[context window_tokens],    type: :integer, default: nil,             expose: %i[env config cli]),
       Entry.new(key: "context.chars_per_token",  yaml_path: %w[context chars_per_token],  type: :float,   default: 4.0,             expose: %i[env config cli]),
+      # The tokens one scope's memory index (sent with every prompt) may hold before a write that crosses it gets a note
+      # (MemoryBundle::IndexSize); 0: no note. `memory:` is its own section, not the `memories:` preload list.
+      Entry.new(key: "memory.index_warn_tokens", yaml_path: %w[memory index_warn_tokens], type: :integer, default: 2500,            expose: %i[env config cli]),
       Entry.new(key: "context.status_thresholds", yaml_path: %w[context status_thresholds], type: :string, default: "20,40,60,80",    expose: %i[env config cli]),
       Entry.new(key: "context.status_cadence",   yaml_path: %w[context status_cadence],   type: :integer, default: 0,               expose: %i[env config cli]),
       # Attached context (ContextSources): how often a source's command runs when it names no --every (seconds; less

data/lib/samagotchi/engine.rb

@@ -53,6 +53,7 @@ require_relative "steer_cut"
 require_relative "engine_peers"
 require_relative "bundle_needs"
 require_relative "model_overlay"
+require_relative "model_notes"
 require_relative "served_model"
 require_relative "image_store"
 require_relative "vision_context"
@@ -256,7 +257,8 @@ module Samagotchi
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
-                                         thinking: -> { turn_thinking }, model: -> { model_identity }, memories: memories,
+                                         thinking: -> { turn_thinking }, model: -> { model_identity },
+                                         model_notes: -> { model_notes }, memories: memories,
                                          muted_memory_names: @muted_memory_names)
       @session = nil
       @session_observer = SessionObserver.new
@@ -468,6 +470,14 @@ module Samagotchi
                                       served: prompt_served_model(target), fallback_key: @fallback_model_key)
     end
 
+    # The model notes for the effective model (ModelNotes): matched on its
+    # bare id and key, the session's mutes left out.
+    # @return [Array<ModelNotes::Note>]
+    def model_notes
+      ModelNotes.for(name: guardrail_model_name, key: @model_key, fallback_key: @fallback_model_key,
+                     muted: @muted_memory_names)
+    end
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -911,7 +921,7 @@ module Samagotchi
       snapshot = @metrics.snapshot
       target = @host_registry.resolve(@effective_model_name)
       served, served_for = served_model_for(snapshot, target: target)
-      snapshot = snapshot.merge(served_model: served, served_model_for: served_for)
+      snapshot = snapshot.merge(served_model: served, served_model_for: served_for, llm_context: llm_context_summary)
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -940,6 +950,39 @@ module Samagotchi
                    .display_for(used_tokens: context[:used_tokens], window_tokens: context[:window_tokens])
     end
 
+    # #turn_llm_context with where each value came from
+    # (LLMContextStrategy.explain), nil when it can't be resolved.
+    # @return [LLMContextStrategy::Explained, nil]
+    def llm_context_explained
+      target = @host_registry.resolve(@effective_model_name)
+      LLMContextStrategy.explain(target, names: model_lookup_names(target), **llm_context_session_args)
+    rescue StandardError
+      nil
+    end
+
+    # #llm_context_explained's summary (Explained#summary), nil when it
+    # can't be resolved: /stats, the snapshot, the web's info bar.
+    # @return [Hash, nil]
+    def llm_context_summary
+      llm_context_explained&.summary(llm_context_override)
+    end
+
+    # The session's own llm_context values, nil when it has none.
+    # @return [LLMContextOverride, nil]
+    def llm_context_override = @session&.llm_context
+
+    # Set the session's own llm_context values (an empty override unsets
+    # them); the next turn's start resolves them, never a running one (its
+    # TurnSettings are fixed). The caller saves the session.
+    # @raise [ArgumentError] with no session yet
+    def llm_context_override=(override)
+      raise ArgumentError, "no session yet" unless @session
+
+      @session.llm_context = override
+      # The status a later client reads counts against the new budget.
+      @last_context_status = saved_context_status(@metrics.snapshot[:context]) || @last_context_status if @last_context_status
+    end
+
     # The effective model is on a chat host (api: openai), whose loop uses
     # no prompt profile.
     def chat_model? = @host_registry.resolve(@effective_model_name).entry.chat?
@@ -1010,6 +1053,7 @@ module Samagotchi
         served_model: served_pair[0],
         served_model_for: served_pair[1],
         context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
+        llm_context: llm_context_summary,
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1158,7 +1202,9 @@ module Samagotchi
     # cancel's reason and the hook that stopped it. Only what is known.
     def stop_facts(event)
       case event&.dig(:type)
-      when :turn_failed then { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable] }.compact
+      # kept_steps: the turn's work stayed (a parent must not send the task again).
+      when :turn_failed
+        { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable], "kept_steps" => event[:kept_steps] }.compact
       when :turn_canceled
         { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
       else {}
@@ -1413,14 +1459,17 @@ module Samagotchi
       target ||= @host_registry.resolve(@effective_model_name)
       chat = target.entry.chat?
       level = chat ? nil : thinking_level(target)
-      @prompt_builder.build(chat: chat, thinking: level, layers: llm_context_layers(target))
+      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: llm_context_layers(target))
+      # The memory indexes this prompt holds: /stats, the snapshot, analytics.json.
+      @metrics.memory_index = @prompt_builder.memory_index
+      prompt
     end
 
     # The LLM context layers +target+'s turns run under: the native prompt
     # declares the tools they add (forget_outputs under forget), so a
     # model switch may change the tool list. [] under none.
     def llm_context_layers(target)
-      LLMContextStrategy.resolve(target, names: model_lookup_names(target)).active_layers
+      LLMContextStrategy.resolve(target, names: model_lookup_names(target), **llm_context_session_args).active_layers
     rescue StandardError
       []
     end
@@ -1832,8 +1881,10 @@ module Samagotchi
       # The turn's settings, set once here. The chat loop dispatches tools
       # through the kernel without its #run: tag those dumps with this
       # turn's model, not the last native one.
+      explained = llm_context_explained
       @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting,
-                                                 llm_context: turn_llm_context)
+                                                 llm_context: explained&.resolved)
+      log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
       backend.complete(
@@ -1848,6 +1899,18 @@ module Samagotchi
     end
     private :generate
 
+    # The turn's LLM context strategy and where it came from, in the turn
+    # log: when it runs a layer, or the session set it (none too).
+    def log_llm_context(explained)
+      return unless explained
+      return if explained.resolved.active_layers.empty? && explained.strategy.source != :session
+
+      summary = explained.summary
+      Log.info(:turn, "llm_context", **summary.slice(:strategy, :strategy_source, :apply, :apply_source, :budget_tokens,
+                                                     :budget_source).compact)
+    end
+    private :log_llm_context
+
     def publish_used_memories(session, on_event)
       # Persist deduped used memories onto the session for Web + reload.
       begin
@@ -1948,20 +2011,30 @@ module Samagotchi
 
     # A failure keeps the loop's partial conversation (else the turn's
     # messages so far) with a failed note; nil when the turn never reached
-    # the model. The model reads why on its next turn (a UI that rolls the
-    # turn back leaves its own note, TurnFlow#prompt_turn_failed).
+    # the model. The model reads why on its next turn. A turn that got to
+    # tool results (LLM::FailedTurn.progress) says so in the note; on the
+    # error (kept_steps) too unless it failed in a way that rolls back
+    # (FailedTurn.keeps_work?: a context overflow). The UIs keep a marked
+    # turn (TurnFlow#prompt_turn_failed), and roll back the others, with a
+    # note of their own; -p --non-interactive keeps what this keeps.
     def failed_messages(turn, error)
       kept = error.respond_to?(:partial_conversation) && error.partial_conversation.is_a?(Array) ? error.partial_conversation : turn.messages
       return nil unless kept
 
+      steps = LLM::FailedTurn.progress(turn.session.messages, kept)
+      error.kept_steps = steps if steps && error.is_a?(LLM::FailedTurn) && LLM::FailedTurn.keeps_work?(error)
       summary = error.respond_to?(:summary) ? error.summary : error.message
-      TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: turn.continue))
+      TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: turn.continue, steps: steps))
     end
     private :failed_messages
 
+    # Called after #failed_messages, which marks the error's kept steps.
     def failed_event(error, seconds)
       failed = { type: :turn_failed, error_class: error.class.name, message: error.message,
                  duration_ms: (seconds * 1000).round }
+      # Its work stays: the UIs say so, as after a cancel.
+      steps = LLM::FailedTurn.kept_steps(error)
+      failed[:kept_steps] = steps if steps
       # A provider error says what kind it is, for one line per kind in the UIs.
       if error.is_a?(LLM::ProviderError)
         failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: error.summary)
@@ -2345,7 +2418,8 @@ module Samagotchi
         model_name: -> { effective_model_ref },
         model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
-        scratch: -> { @scratch }
+        scratch: -> { @scratch },
+        llm_context: -> { @session&.llm_context }
       )
     end
 
@@ -2529,16 +2603,17 @@ module Samagotchi
       nil
     end
 
-    # The effective model's LLM context strategy (models:/hosts:
-    # llm_context_strategy, else llm_context.strategy), read per turn as
+    # The LLM context strategy the next turn runs under: the session's own
+    # (Session#llm_context), else the effective model's (models:/hosts:
+    # llm_context_strategy), else llm_context.strategy; read per turn as
     # the window is.
     def turn_llm_context
-      target = @host_registry.resolve(@effective_model_name)
-      LLMContextStrategy.resolve(target, names: model_lookup_names(target))
-    rescue StandardError
-      nil
+      llm_context_explained&.resolved
     end
 
+    def llm_context_session_args = @session&.llm_context&.resolve_args || {}
+    private :llm_context_session_args
+
     # See #served_model. A report for another name (before a /model switch)
     # doesn't count. Without a target, no probe. A remote chat host has no
     # /props: nil until a turn.

data/lib/samagotchi/events.rb

@@ -9,7 +9,8 @@ module Samagotchi
     # A turn is over: it completed, was canceled, or failed.
     TURN_END = %i[turn_completed turn_canceled turn_failed].freeze
     # Turn ends that leave the turn in the conversation: a failed turn's
-    # prompt goes back to the composer instead.
+    # prompt goes back to the composer instead, unless its work stayed
+    # (#kept_turn?).
     TURN_KEPT = %i[turn_completed turn_canceled].freeze
     # The kinds of a running turn's parts (Bridge::TurnAccumulator), which a
     # joining UI replays as live events.
@@ -19,5 +20,11 @@ module Samagotchi
     # turn, turn_events.js snapshotEvents).
     STREAM_FRAMES = %i[snapshot reset stream_closed].freeze
     SYNTHETIC = %i[merged_input].freeze
+
+    # Whether +event+ ends a turn that stays in the conversation: completed,
+    # canceled, or failed with its work kept (turn_failed's kept_steps).
+    def self.kept_turn?(event)
+      TURN_KEPT.include?(event[:type]) || (event[:type] == :turn_failed && !event[:kept_steps].nil?)
+    end
   end
 end

data/lib/samagotchi/guardrails/model_size.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../config"
+require_relative "../model_match"
 
 module Samagotchi
   module Guardrails
@@ -15,7 +16,6 @@ module Samagotchi
       SETTING = "guardrails.small_models"
       # The largest auto-small size, in billions of parameters.
       MAX_SMALL = 32
-      GLOB_FLAGS = File::FNM_CASEFOLD | File::FNM_EXTGLOB
 
       # A size starts at the name's start or after a separator, and ends at
       # a separator or the name's end (so 4bit and v4.1 aren't sizes).
@@ -53,12 +53,11 @@ module Samagotchi
       def small?(name, key, setting = self.setting)
         return false if name.nil? || name.to_s.strip.empty?
 
-        entries = (setting.nil? ? "auto" : setting.to_s).split("|").map(&:strip).reject(&:empty?)
-        entries.any? do |entry|
+        ModelMatch.parse(setting.nil? ? "auto" : setting.to_s).any? do |entry|
           if entry.casecmp?("auto")
             (size = billions(name)) ? size <= MAX_SMALL : false
           else
-            [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate.to_s, GLOB_FLAGS) }
+            ModelMatch.glob?(entry, name: name, key: key)
           end
         end
       end

data/lib/samagotchi/guardrails/rules.rb

@@ -3,6 +3,7 @@
 require_relative "verdict"
 require_relative "targets"
 require_relative "model_size"
+require_relative "../model_match"
 
 module Samagotchi
   module Guardrails
@@ -20,8 +21,9 @@ module Samagotchi
     #            subcommand outside the session's repo (ShellGitDirs)
     #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
     #            or a glob on the bare model name or the model key, or a
-    #            list of them: the rule only votes for a model that matches
-    #            (no model matches none; missing = every model)
+    #            list of them ("|"-separated or a YAML list; ModelMatch):
+    #            the rule only votes for a model that matches (no model
+    #            matches none; missing = every model)
     #   touches: "chi_dirs": a command names a path in chi's config, hooks,
     #            approvals or bundles dir or a .git/hooks dir (resolved;
     #            a word that can't be resolved falls back to text)
@@ -30,7 +32,12 @@ module Samagotchi
     #   modes:   "strict", "auto" or a list of them: the rule only votes
     #            in those guardrails.mode values (missing = every mode;
     #            a rule from config.yml without it votes in every mode)
-    #   memory:  "remove": a memory_write call with remove: true
+    #   memory:  "remove": a memory_write call with remove: true;
+    #            "overlay": one that writes a model overlay
+    #            (current_model_only: true); "prompt": a memory_write,
+    #            write or edit of a memory file that reaches the system
+    #            prompt (identity, model notes, their overlays;
+    #            Targets#prompt_memory?)
     #   skip_read_only: true: a shell command that only reads
     #            (ReadOnlyShell) doesn't match
     # verdict ask|deny, reason, scopes (for an ask; default all).
@@ -59,12 +66,20 @@ module Samagotchi
           return false if git && !targets.git_outside_repo?
           return false if touches && !targets.touches_chi?
           return false if rm && !targets.rm_outside_tmp?
-          return false if memory && !targets.memory_remove?
+          return false if memory && !memory_matches?(targets)
           return false if skip_read_only && targets.read_only?
 
           true
         end
 
+        def memory_matches?(targets)
+          case memory
+          when "overlay" then targets.memory_overlay?
+          when "prompt" then targets.prompt_memory?
+          else targets.memory_remove?
+          end
+        end
+
         # Whether the rule votes in guardrails.mode +mode+.
         def for_mode?(mode) = modes.nil? || modes.include?(mode.to_s)
 
@@ -76,15 +91,8 @@ module Samagotchi
         # for every model). +small+ says whether the model is a small one.
         def for_model?(name, key, small = -> { ModelSize.small?(name, key) })
           return true unless models
-          return false if name.nil? || name.empty?
-
-          models.any? do |entry|
-            if entry == "small"
-              small.call
-            else
-              [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate, ModelSize::GLOB_FLAGS) }
-            end
-          end
+
+          ModelMatch.match?(models, name: name, key: key, small: small)
         end
 
         def path_matches?(targets)
@@ -190,10 +198,11 @@ module Samagotchi
         value
       end
 
-      # Only "remove" for now.
+      MEMORY_KINDS = %w[remove overlay prompt].freeze
+
       def self.memory_of(value, label)
         return nil if value.nil?
-        raise ParseError, "#{label}: memory must be remove" unless value == "remove"
+        raise ParseError, "#{label}: memory must be remove, overlay or prompt" unless MEMORY_KINDS.include?(value)
 
         value
       end
@@ -217,15 +226,16 @@ module Samagotchi
         value
       end
 
+      # ModelMatch's grammar: a string ("|"-separated) or a list of names.
       def self.models_of(value, label)
         return nil if value.nil?
 
         names = Array(value)
-        unless !names.empty? && names.all? { |n| n.is_a?(String) && !n.strip.empty? }
+        unless !names.empty? && names.all? { |n| n.is_a?(String) && !n.strip.empty? } && !ModelMatch.parse(value).empty?
           raise ParseError, "#{label}: models must be small, a glob or a list of them"
         end
 
-        names.map(&:strip)
+        ModelMatch.parse(value)
       end
 
       def self.scopes_of(value, label)

data/lib/samagotchi/guardrails/targets.rb

@@ -10,6 +10,8 @@ require_relative "shell_git_dirs"
 require_relative "read_only_shell"
 require_relative "shell_paths"
 require_relative "rm_targets"
+require_relative "protected_paths"
+require_relative "../memory_paths"
 
 module Samagotchi
   module Guardrails
@@ -65,6 +67,11 @@ module Samagotchi
       attr_reader :memory_remove
       alias memory_remove? memory_remove
 
+      # @return [Boolean] a memory_write call that writes a model overlay
+      #   (current_model_only: true), for a rule's memory: overlay
+      attr_reader :memory_overlay
+      alias memory_overlay? memory_overlay
+
       # @param call [Hash] the parsed tool call
       # @param context [Context]
       # @param model_key [String, nil] for a memory_write model overlay, and
@@ -104,8 +111,10 @@ module Samagotchi
           label = given[:label]
         end
         memory_remove = tool == "memory_write" && call[:remove].to_s.strip.downcase == "true"
+        memory_overlay = tool == "memory_write" && !memory_remove && call[:current_model_only].to_s.strip.downcase == "true"
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd),
             repo: context.repo(cwd), args: args, acts_as: acts_as, label: label, memory_remove: memory_remove,
+            memory_overlay: memory_overlay,
             model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base,
             chi_dirs: -> { chi_dirs(context, base) })
       end
@@ -209,10 +218,12 @@ module Samagotchi
 
       # @param chi_dirs [#call, nil] → the dirs touches_chi? looks for
       def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, acts_as: nil, label: nil,
-                     model_name: nil, model_key: nil, session_root: nil, chi_dirs: nil, memory_remove: false)
+                     model_name: nil, model_key: nil, session_root: nil, chi_dirs: nil, memory_remove: false,
+                     memory_overlay: false)
         @acts_as = acts_as
         @label = label
         @memory_remove = memory_remove
+        @memory_overlay = memory_overlay
         @repo = repo
         @chi_dirs = chi_dirs
         @session_root = session_root || repo_root || cwd
@@ -267,6 +278,34 @@ module Samagotchi
         @read_only = !@command.nil? && ReadOnlyShell.read_only?(@command)
       end
 
+      # A memory file that reaches the system prompt: the identity memory and
+      # the model notes (`model_notes_*`), with their overlays.
+      PROMPT_MEMORY = /\A(?:identity(?:\..+)?|model_notes_.+)\.md\z/
+
+      # Whether a path is a prompt-reaching memory file (.prompt_memory_path?),
+      # for a rule's memory: prompt.
+      def prompt_memory?
+        return @prompt_memory if defined?(@prompt_memory)
+
+        @prompt_memory = @paths.any? { |path| self.class.prompt_memory_path?(path) }
+      end
+
+      # Whether +path+, resolved (symlinks, .., the case the disk has),
+      # lies right in a memories dir (the system scope or a project's) and
+      # its name, in any case, is a PROMPT_MEMORY one: on a case-insensitive
+      # disk MODEL_NOTES_x.md in Samagotchi/Memories is the same file chi
+      # loads.
+      def self.prompt_memory_path?(path)
+        real = ProtectedPaths.real(path)
+        return false unless File.basename(real).downcase.match?(PROMPT_MEMORY)
+
+        dir = File.dirname(real)
+        dir.casecmp?(ProtectedPaths.real(MemoryPaths.system_dir)) ||
+          File.dirname(dir).casecmp?(ProtectedPaths.real(MemoryPaths.projects_dir))
+      rescue StandardError
+        false
+      end
+
       # Whether the command names a path in chi's own dirs (ShellPaths:
       # resolved paths; the text CHI_SHELL_TEXT for a word that can't be
       # resolved); false without a command.

data/lib/samagotchi/guardrails/verdict.rb

@@ -14,9 +14,12 @@ module Samagotchi
       # Rules that ask about chi's own config and hooks: the core
       # ProtectedPaths asks and the guardrails bundle's shell rule; and a
       # command source for attached context (it runs later, ungated); chi
-      # broadcast, which is the user's. Only the user may allow them
-      # (ParentApprovals).
-      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast].freeze
+      # broadcast, which is the user's; the bundle's asks before a memory
+      # that reaches the system prompt, or a model overlay, is written (a
+      # parent model would be writing a model's prompt). Only the user may
+      # allow them (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
+                           model-overlay-write].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 

data/lib/samagotchi/llm/errors.rb

@@ -429,7 +429,12 @@ module Samagotchi
     # streamed reply is not kept), so the caller can keep it, as a cancel's
     # salvage does.
     module FailedTurn
-      attr_accessor :partial_conversation
+      # +kept_steps+: set by the Engine when the turn's work stays
+      # (Engine#failed_messages): the tool results it got to; nil when it
+      # got to none, or failed in a way that rolls it back (#keeps_work?).
+      attr_accessor :partial_conversation, :kept_steps
+
+      TOOL_ROLES = %w[tool_response tool].freeze
 
       # The innermost loop's conversation wins.
       # @return [Exception] +error+
@@ -438,6 +443,33 @@ module Samagotchi
         error.partial_conversation ||= conversation
         error
       end
+
+      # What a failed turn got to: +after+ (the conversation it leaves)
+      # against +before+ (the session's before it). A turn that added tool
+      # results did work worth keeping: its tool calls ran (files may have
+      # changed), and dropping them would leave the model blind to that. A
+      # model message alone isn't (a recovery nudge's, an unfinished
+      # call's). Counted by role, so notes that came meanwhile, the system
+      # head and reminders don't count.
+      # @return [Integer, nil] the tool results it added, or nil for none
+      def self.progress(before, after)
+        steps = count(after, TOOL_ROLES) - count(before, TOOL_ROLES)
+        steps.positive? ? steps : nil
+      end
+
+      # Whether a turn +error+ ended may keep its work. Not a context
+      # overflow: kept, the conversation would stay over the window, every
+      # later prompt failing the same way; it is rolled back, its prompt
+      # handed back, as before.
+      def self.keeps_work?(error) = !(error.respond_to?(:context_overflow?) && error.context_overflow?)
+
+      # The steps the session kept of the turn +error+ ended, or nil.
+      def self.kept_steps(error) = error.is_a?(self) && keeps_work?(error) ? error.kept_steps : nil
+
+      def self.count(messages, roles)
+        Array(messages).count { |m| roles.include?((m[:role] || m["role"]).to_s) }
+      end
+      private_class_method :count
     end
   end
 end