samagotchi 0.40.0 → 0.42.0

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

data/lib/samagotchi/llm_context_command.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_override"
+require_relative "llm_context_strategy"
+require_relative "llm_context_edit"
+require_relative "llm_context_stale"
+
+module Samagotchi
+  # /llm-context, the session's own LLM context values
+  # (LLMContextOverride): with no arguments, the strategy, apply rule and
+  # budget the next turn runs under and where each came from (the session,
+  # models: <key>, a hosts entry, llm_context.*); with
+  # `strategy <layers|none>`, `apply <rule>` and `budget <N|off>` (any of
+  # them, in one line; `default` unsets one) it sets the session's own, and
+  # `reset` unsets them all. A change takes effect at the next turn's
+  # start (the REPL and the worker run it between turns), and the reply
+  # says what it costs: forget on or off changes the tool list and the
+  # system prompt (a full cache break); stale turned on stages the reads
+  # already superseded as one batch under the apply rule; a layer turned
+  # off sends its stubs whole again (the originals stay in the session, so
+  # turning it back on brings them back).
+  class LLMContextCommand
+    NAME = LLMContextOverride::COMMAND
+    USAGE = "usage: #{NAME} [strategy <none|stale,forget|default>] [apply <payoff|next_request|turn_end|default>] " \
+            "[budget <tokens|64k|off|default>] | #{NAME} reset".freeze
+    RESET = "reset"
+    FIELDS = LLMContextOverride::COMMAND_WORDS.invert.freeze
+
+    # @param engine [Engine] #llm_context_explained, #llm_context_override(=), #session
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /llm-context
+    # @return [Array(String, Boolean)] the reply and whether the values changed
+    # @raise [ArgumentError] a line that isn't one (its message and USAGE)
+    def run(args)
+      args = args.to_s.strip
+      return [listing(@engine.llm_context_explained), false] if args.empty?
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = @engine.llm_context_explained
+      updated = args.casecmp?(RESET) ? LLMContextOverride.new : LLMContextOverride.update(@engine.llm_context_override, words(args))
+      @engine.llm_context_override = updated
+      @save.call(session)
+      after = @engine.llm_context_explained
+      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true]
+    end
+
+    # The values, where each came from, and what the session sets itself.
+    def listing(explained)
+      return "llm context: can't be resolved for this model" unless explained
+
+      resolved = explained.resolved
+      own = @engine.llm_context_override
+      set = own ? LLMContextOverride::FIELDS.filter_map { |field| own_word(own, field) }.join("; ") : nil
+      [
+        "llm context: #{strategy_word(resolved)} (#{explained.strategy.where})",
+        "  apply:  #{resolved.apply} (#{explained.apply.where})",
+        "  budget: #{resolved.budget_tokens ? "#{resolved.budget_tokens} tokens" : "off"} (#{explained.budget_tokens.where})",
+        "  this session's own: #{set.to_s.empty? ? "none (follows the model, its host, then llm_context.*)" : set}"
+      ].join("\n")
+    end
+
+    private
+
+    # "strategy stale stale forget apply turn_end budget 64k" as fields
+    # and their words; a strategy takes the words up to the next field.
+    def words(args)
+      fields = {}
+      field = nil
+      args.split.each do |token|
+        if FIELDS.key?(token.downcase) && (field.nil? || fields[field])
+          field = FIELDS[token.downcase]
+          raise ArgumentError, "#{token} is given twice\n#{USAGE}" if fields.key?(field)
+
+          fields[field] = nil
+        elsif field.nil?
+          raise ArgumentError, "unknown #{NAME} word #{token}\n#{USAGE}"
+        elsif fields[field].nil? || field == :strategy
+          fields[field] = [fields[field], token].compact.join(" ")
+        else
+          raise ArgumentError, "#{FIELDS.key(field)} takes one value, not #{fields[field]} #{token}\n#{USAGE}"
+        end
+      end
+      missing = fields.find { |_field, word| word.nil? }
+      raise ArgumentError, "#{FIELDS.key(missing.first)} needs a value\n#{USAGE}" if missing
+
+      fields
+    end
+
+    def own_word(own, field)
+      word = LLMContextOverride.word(field, own.public_send(field))
+      word && "#{LLMContextOverride::COMMAND_WORDS[field]} #{word}"
+    end
+
+    def strategy_word(resolved) = resolved.active_layers.empty? ? "none" : resolved.active_layers.join(", ")
+
+    # What the change does from the next turn on.
+    def notes(session, before, after)
+      return [] unless before && after
+      return ["(no change to what the next turn runs under)"] if before.with(source: nil) == after.with(source: nil)
+
+      was = before.active_layers
+      now = after.active_layers
+      notes = ["From the next turn's start (a running turn keeps its own)."]
+      notes << forget_note(now.include?(:forget)) if was.include?(:forget) != now.include?(:forget)
+      notes << stale_note(session, after) if now.include?(:stale) && !was.include?(:stale)
+      (was - now).each do |layer|
+        count = applied_count(session.messages, layer)
+        next if count.zero?
+
+        notes << "#{layer}'s #{count} stub#{"s" if count != 1} go#{"es" if count == 1} out whole again (a cache break " \
+                 "from the first; the originals stay in the session, and turning #{layer} back on brings the stubs back)."
+      end
+      notes
+    end
+
+    def forget_note(on)
+      verb = on ? "joins" : "leaves"
+      note = "forget_outputs #{verb} the tool list and the system prompt#{" (and outputs show their ids)" if on}: " \
+             "the next request re-reads the whole prompt (a full cache break)."
+      on ? note : "#{note} Its past forget_outputs calls and their results stay in the history."
+    end
+
+    # How many past reads are already superseded, and when they go in.
+    def stale_note(session, resolved)
+      found = LLMContextStale.found(session.messages, root: session.working_directory.to_s,
+                                                      changes: resolved.stale_edits).size
+      return "stale: no past read is superseded yet." if found.zero?
+
+      when_in = case resolved.apply
+                when :next_request then "at the next request"
+                when :turn_end then "at the end of the next turn"
+                else "at the next request if what it frees pays for the re-read tail, else at the end of the next turn"
+                end
+      "stale: #{found} past read#{"s" if found != 1} already superseded go#{"es" if found == 1} in as one batch " \
+        "under apply #{resolved.apply}: #{when_in}."
+    end
+
+    def applied_count(messages, layer)
+      Array(messages).sum do |entry|
+        next 0 unless entry[:role].to_s == "tool_response"
+
+        LLMContextEdit.on(entry).values.count { |edit| edit.applied? && edit.kind == layer }
+      end
+    end
+  end
+end

data/lib/samagotchi/llm_context_override.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # A session's own llm_context values (Session#llm_context), which come
+  # before the model's, the host's and the global ones
+  # (LLMContextStrategy.resolve): the layers ([] is none, set on purpose),
+  # the apply rule and the budget in tokens (0 is off, set on purpose).
+  # nil in a field is unset: that value follows the model, the host, then
+  # llm_context.*, as with no override at all.
+  #
+  # Set by chi --llm-context, --llm-context-apply and --llm-context-budget
+  # at start (or --resume), /llm-context in the session and the web's info
+  # bar (which sends /llm-context). Saved in the session file, so a
+  # --resume and a respawned worker keep it; a plugin's fork copies it,
+  # a delegate child starts without one.
+  LLMContextOverride = Data.define(:strategy, :apply, :budget_tokens) do
+    def initialize(strategy: nil, apply: nil, budget_tokens: nil) = super
+
+    def empty? = strategy.nil? && apply.nil? && budget_tokens.nil?
+
+    # What the session file keeps: the set fields, nil when none is.
+    # @return [Hash, nil]
+    def to_file
+      return nil if empty?
+
+      { "strategy" => strategy&.map(&:to_s), "apply" => apply&.to_s, "budget_tokens" => budget_tokens }.compact
+    end
+
+    # LLMContextStrategy.resolve's session arguments.
+    def resolve_args = { session: strategy, session_apply: apply, session_budget: budget_tokens }
+
+    # How a field reads: "stale, forget", "none", "turn_end", "64000",
+    # "off"; nil when unset.
+    def self.word(field, value)
+      return nil if value.nil?
+
+      case field
+      when :strategy then value.empty? ? "none" : value.join(", ")
+      when :budget_tokens then value.positive? ? value.to_s : "off"
+      else value.to_s
+      end
+    end
+  end
+
+  class LLMContextOverride
+    FIELDS = %i[strategy apply budget_tokens].freeze
+    # A field's word for "unset: follow the model" (/llm-context strategy default).
+    DEFAULT_WORD = "default"
+    OFF_WORDS = %w[off 0].freeze
+    # The start flags (chi, chi send --new), by field.
+    FLAGS = { strategy: "--llm-context", apply: "--llm-context-apply", budget_tokens: "--llm-context-budget" }.freeze
+    # The session command, and its words by field.
+    COMMAND = "/llm-context"
+    COMMAND_WORDS = { strategy: "strategy", apply: "apply", budget_tokens: "budget" }.freeze
+
+    # The /llm-context line that sets +words+ (field => value as typed,
+    # checked by .update first): what a flag on an existing session runs.
+    # @return [String]
+    def self.command_line(words)
+      parts = words.map do |field, word|
+        word = word.to_s.strip
+        word = parse_strategy(word).then { |layers| layers.empty? ? "none" : layers.join(",") } if field == :strategy && !word.casecmp?(DEFAULT_WORD)
+        "#{COMMAND_WORDS.fetch(field)} #{word}"
+      end
+      [COMMAND, *parts].join(" ")
+    end
+
+    # A session file's "llm_context" (or an override already): nil when
+    # absent or empty. A field that doesn't read (an unknown layer, an
+    # out-of-range budget: a newer chi's, or a hand edit) is left unset,
+    # without a warning: that value follows the model (.unread keeps it).
+    # @return [LLMContextOverride, nil]
+    def self.from_file(data)
+      return data.empty? ? nil : data if data.is_a?(self)
+      return nil unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      override = new(strategy: file_value { file_strategy(data["strategy"]) },
+                     apply: file_value { parse_apply(data["apply"].to_s) unless data["apply"].nil? },
+                     budget_tokens: file_value { file_budget(data["budget_tokens"]) })
+      override.empty? ? nil : override
+    end
+
+    # The fields of a session file's "llm_context" that .from_file couldn't
+    # read, as written (String keys): saved back as they were.
+    # @return [Hash]
+    def self.unread(data)
+      return {} unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      read = from_file(data)
+      FIELDS.each_with_object({}) do |field, unread|
+        key = field.to_s
+        unread[key] = data[key] if !data[key].nil? && read&.public_send(field).nil?
+      end
+    end
+
+    def self.file_value
+      yield
+    rescue ArgumentError
+      nil
+    end
+
+    def self.file_strategy(raw)
+      return nil unless raw.is_a?(Array) || raw.is_a?(String)
+      return [] if raw == []
+
+      parse_strategy(Array(raw).join(","))
+    end
+
+    def self.file_budget(raw)
+      raw.is_a?(Integer) ? check_budget(raw) : nil
+    end
+
+    # +current+ with +words+ (field => what the user typed) applied: each
+    # word is a value, or "default" (unset). The flags and /llm-context
+    # both go through here.
+    # @param current [LLMContextOverride, nil]
+    # @param words [Hash{Symbol => String}]
+    # @return [LLMContextOverride]
+    # @raise [ArgumentError] a word that isn't a value, saying which
+    def self.update(current, words)
+      fields = words.to_h do |field, word|
+        raise ArgumentError, "unknown llm_context field #{field}" unless FIELDS.include?(field)
+
+        text = word.to_s.strip
+        [field, text.casecmp?(DEFAULT_WORD) ? nil : send(:"parse_#{field}", text)]
+      end
+      (current || new).with(**fields)
+    end
+
+    # "stale,forget", "stale forget", "stale|forget" or "none".
+    # @return [Array<Symbol>] [] for none
+    def self.parse_strategy(text)
+      names = text.downcase.split(/[\s,|]+/).reject(&:empty?)
+      raise ArgumentError, "a strategy is none or a list of #{LLMContextStrategy::LAYERS.join(", ")}" if names.empty?
+      return [] if names == [LLMContextStrategy::NONE.to_s]
+
+      unknown = names - LLMContextStrategy::LAYERS.map(&:to_s)
+      unless unknown.empty?
+        raise ArgumentError, "unknown llm_context strategy #{unknown.join(", ")} (none, or a list of " \
+                             "#{LLMContextStrategy::LAYERS.join(", ")})"
+      end
+      LLMContextStrategy::LAYERS.select { |layer| names.include?(layer.to_s) }
+    end
+
+    # payoff, next_request or turn_end.
+    # @return [Symbol]
+    def self.parse_apply(text)
+      rule = LLMContextStrategy::APPLIES.find { |name| name.to_s.casecmp?(text) }
+      rule || raise(ArgumentError, "unknown llm_context apply #{text} (#{LLMContextStrategy::APPLIES.join(", ")})")
+    end
+
+    # The smallest and largest budget a session may set.
+    MIN_BUDGET = 4_000
+    MAX_BUDGET = 10_000_000
+
+    # "64000", "64k" or "off" (0).
+    # @return [Integer] 0 for off
+    def self.parse_budget_tokens(text)
+      return 0 if OFF_WORDS.include?(text.downcase)
+
+      match = /\A(\d[\d_]*)(k)?\z/i.match(text)
+      raise ArgumentError, "a budget is a number of tokens (64000 or 64k) or off" unless match
+
+      check_budget(match[1].delete("_").to_i * (match[2] ? 1000 : 1))
+    end
+
+    # +tokens+, when 0 (off) or between MIN_BUDGET and MAX_BUDGET.
+    def self.check_budget(tokens)
+      return tokens if tokens.zero? || tokens.between?(MIN_BUDGET, MAX_BUDGET)
+
+      raise ArgumentError, "a budget of #{tokens} tokens is out of range: #{MIN_BUDGET} (4k) to #{MAX_BUDGET} (10000k), or off"
+    end
+
+    private_class_method :file_value, :file_strategy, :file_budget
+  end
+end