samagotchi 0.82.0 → 0.84.0

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -41,6 +41,9 @@ module Samagotchi
     #       cmd: '{ruby} {bundle_dir}/scripts/pr_context.rb {url}'
     #       why: GitHub PR      #   optional
     #       every_seconds: 300  #   optional
+    #   session_settings: [cap] # optional — the settings a session may set
+    #                          #   (chi --set cost-cap.cap=3), read by the
+    #                          #   plugin from ctx.settings at call time
     #   includes: [a, b]       # optional — a profile (meta bundle): the
     #                          #   shipped bundles it installs; its dir holds
     #                          #   only manifest.yml (MemoryBundle::Profile)
@@ -60,7 +63,7 @@ module Samagotchi
       # the description a mapping gave, for the files that have one; hooks:
       # name → BundleHook.
       attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
-                  :scripts, :context_providers
+                  :scripts, :context_providers, :session_settings
 
       def initialize(path:)
         @path = path
@@ -84,6 +87,7 @@ module Samagotchi
         @scripts = parse_scripts(raw["scripts"])
         @context_providers = parse_context_providers(raw["context_providers"])
         @includes = parse_includes(raw["includes"])
+        @session_settings = self.class.parse_session_settings(raw["session_settings"])
       end
 
       # A profile: it installs the bundles in includes instead of files.
@@ -136,7 +140,8 @@ module Samagotchi
       # Writes a fresh manifest.yml from computed checksums at `dir`.
       # +file_descriptions+ (name → text) writes those files as mappings.
       def self.write(dir:, name:, version:, files:, scope: nil, description: "", hooks: nil, trust_level: nil,
-                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], file_descriptions: {})
+                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], file_descriptions: {},
+                     session_settings: [])
         FileUtils.mkdir_p(dir)
         manifest = {
           "name" => name,
@@ -159,9 +164,26 @@ module Samagotchi
         manifest["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } unless needs.empty?
         manifest["scripts"] = scripts.transform_keys(&:to_s) unless scripts.empty?
         manifest["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
+        manifest["session_settings"] = Array(session_settings).map(&:to_s) unless Array(session_settings).empty?
         File.write(File.join(dir, "manifest.yml"), YAML.dump(manifest))
       end
 
+      # A setting key a session may set (BundleSessionSettings::KEY).
+      SESSION_SETTING = /\A[A-Za-z0-9_][A-Za-z0-9_-]*\z/
+
+      # session_settings: → the keys, [] when absent; anything but a list of
+      # plain key names is a ValidationError.
+      def self.parse_session_settings(raw)
+        return [] if raw.nil?
+
+        keys = raw.is_a?(Array) ? raw : nil
+        unless keys&.all? { |key| (key.is_a?(String) || key.is_a?(Symbol)) && key.to_s.match?(SESSION_SETTING) }
+          raise ValidationError, "session_settings: a list of setting names (#{raw.inspect})"
+        end
+
+        keys.map(&:to_s).uniq
+      end
+
       # needs: → [{command:, why:, hint:}] (why/hint a String or nil), [] when
       # absent. Takes the manifest's string-keyed YAML or the symbol-keyed
       # form provenance stores. Duplicates merge (the first one's why/hint

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -141,7 +141,7 @@ module Samagotchi
       # @param context_providers [Array<ContextProviders::Provider>]
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
                 guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
-                scripts_files: {}, context_providers: [], file_descriptions: {})
+                scripts_files: {}, context_providers: [], file_descriptions: {}, session_settings: [])
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -239,6 +239,7 @@ module Samagotchi
           end
         end
         manifest_data["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
+        manifest_data["session_settings"] = Array(session_settings).map(&:to_s) unless Array(session_settings).empty?
 
         write_manifest(manifest_data)
       end

data/lib/samagotchi/plugin/context.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../log"
 require_relative "../paths"
+require_relative "../session_metrics/cost"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "service"
@@ -51,10 +52,11 @@ module Samagotchi
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
     # plugin handler: +handler+) until the turn has ended.
+    # +cost+ returns the session's spend now (SessionMetrics::Cost).
     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,
-                      :cancel_controller, keyword_init: true)
+                      :cancel_controller, :cost, 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.
@@ -95,8 +97,24 @@ module Samagotchi
       # @return [String] the bundle the plugin came with
       attr_reader :bundle
 
-      # @return [Hash] config.yml `bundles: <bundle>:` (string keys), frozen
-      attr_reader :settings
+      # config.yml `bundles: <bundle>:` with the session's own values for
+      # the bundle laid over it (chi --set BUNDLE.KEY=VALUE, through the
+      # Host's setup: SessionSetup#bundle_settings), string keys, frozen.
+      # Plugin init and chi.ctx run before the session is bound: with no
+      # session id yet it is the config alone, and it is built again once
+      # per session id (the session's values never change after it starts).
+      # A plugin's initialize(settings) gets the config only: a value a
+      # session may set is read here, at call time.
+      # @return [Hash]
+      def settings
+        id = session_id
+        cached = @session_settings
+        return cached.last if cached && cached.first == id
+
+        merged = id ? overlay(@settings, session_values) : @settings
+        @session_settings = [id, merged].freeze
+        merged
+      end
 
       # @return [Logger]
       attr_reader :log
@@ -140,6 +158,11 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # @return [SessionMetrics::Cost] the session's spend so far, read now:
+      #   #total, #reported, #estimated, #side (Float USD) and #known?
+      #   (docs/plugins.md); zero and known with no session
+      def cost = @host.cost&.call || SessionMetrics::Cost.zero
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call
@@ -412,6 +435,20 @@ module Samagotchi
         nil
       end
 
+      # The session's own values for this bundle ({} without any, or when
+      # the Host can't tell them).
+      def session_values
+        values = @host.setup&.call&.bundle_settings
+        values.is_a?(Hash) ? values.fetch(@bundle, {}) : {}
+      rescue StandardError => e
+        @log.warn("session_settings_unread", error: "#{e.class}: #{e.message}")
+        {}
+      end
+
+      def overlay(config, values)
+        values.empty? ? config : deep_freeze(config.merge(values))
+      end
+
       def deep_freeze(value)
         case value
         when Hash then value.to_h { |k, v| [deep_freeze(k), deep_freeze(v)] }.freeze

data/lib/samagotchi/reply_wait.rb

@@ -181,8 +181,9 @@ module Samagotchi
            (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
            baseline && ended == baseline[:last_turn]
           file = newest_reply(id, state_dir: state_dir)
-          if file && reply_is_turns?(file, ended)
-            reply = Result.new(status: :done, text: File.read(File.join(reply_dir(id, state_dir: state_dir), file)), file: file)
+          path = File.join(reply_dir(id, state_dir: state_dir), file) if file
+          if file && reply_is_turns?(path, ended)
+            reply = Result.new(status: :done, text: File.read(path), file: file)
             reply.session = settled(session, id, state_dir: state_dir)
             return reply
           end
@@ -194,6 +195,9 @@ module Samagotchi
            !(session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == turn) &&
            (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
            baseline && ended == baseline[:last_turn]
+          # The turn-specific reply lookup above already found its file, if
+          # one exists. Without it, don't use the newest file as a fallback:
+          # it could belong to another turn.
           return no_reply(session, baseline, fresh: true)
         end
 
@@ -440,19 +444,13 @@ module Samagotchi
       cursor.nil? || file > cursor
     end
 
-    # Whether the reply file +file+ is the turn that ended at +ended_at+'s,
-    # not an earlier turn's: the worker records the ended_at, then writes
-    # the reply (SessionInbox.write_output: the name's timestamp is the
-    # write time, at least the ended_at); every earlier turn's file is
-    # older than the turn's end. The wait and the session run on one
-    # machine, so the name's local-time read is the writer's. A name that
-    # doesn't read as a time isn't the turn's.
-    def reply_is_turns?(file, ended_at)
-      name = file.to_s
-      return false if name.length < 23
-
-      Time.parse(ended_at.to_s) <= Time.strptime(name[0, 14], "%Y%m%d%H%M%S") + (name[14, 9].to_f / (10**9))
-    rescue ArgumentError
+    # Whether the reply file at +path+ is the turn that ended at +ended_at+'s,
+    # not an earlier turn's: the worker records ended_at before writing the
+    # reply, so its mtime is at least the turn's end and earlier replies'
+    # mtimes precede it. Unlike the filename, mtime is independent of TZ.
+    def reply_is_turns?(path, ended_at)
+      File.mtime(path) >= Time.parse(ended_at.to_s)
+    rescue ArgumentError, SystemCallError
       false
     end
 

data/lib/samagotchi/send_command.rb

@@ -7,6 +7,7 @@ require_relative "session"
 require_relative "session_commands"
 require_relative "session_inbox"
 require_relative "session_manager"
+require_relative "bundle_session_settings"
 require_relative "session_chain"
 require_relative "context_quote"
 require_relative "reply_wait"
@@ -39,7 +40,7 @@ module Samagotchi
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
-             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [--toolkit NAME] [-m TEXT] [--image PATH]...
+             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [--toolkit NAME] [--set BUNDLE.KEY=VALUE]... [-m TEXT] [--image PATH]...
              chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
@@ -65,8 +66,9 @@ module Samagotchi
                     (--new) start the next link of that session's chain:
                     in its folder, on its model (or --model's; one whose
                     host is gone falls back to the default, with a
-                    warning), LLM context, thinking level and toolkit,
-                    with a note carrying its recap; it is archived.
+                    warning), LLM context, thinking level, toolkit and
+                    bundle settings, with a note carrying its recap; it
+                    is archived.
                     last:ID names the chain's latest link.
                     Without -m the new session waits idle. Refused for a
                     session continued already (naming the next link) or
@@ -84,6 +86,12 @@ module Samagotchi
                     (full, lean, child, a config or bundle one; default
                     config's toolkit.default), and tools declared on top
                     of it or left out (repeatable, a comma list too)
+        --set BUNDLE.KEY=VALUE
+                    (--new) a bundle setting for this session, over
+                    config.yml's bundles: (repeatable; a key its bundle's
+                    manifest lists in session_settings:; 3, 2.5, true,
+                    false and off are typed, the rest is text:
+                    --set cost-cap.cap=3)
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
                     answer from you: the question, its options and the
@@ -141,6 +149,7 @@ module Samagotchi
       f.value "--toolkit"
       f.value "--tool", key: :tools, repeat: true
       f.value "--no-tool", key: :no_tools, repeat: true
+      f.value "--set", key: :sets, repeat: true
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.switch "--cut"
@@ -284,6 +293,7 @@ module Samagotchi
       %i[dir model continues thinking toolkit].each { |key| return usage_error("--#{key} needs --new") if options[key] }
       TOOLKIT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") unless Array(options[key]).empty? }
       LLM_CONTEXT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") if options[key] }
+      return usage_error("--set needs --new") unless Array(options[:sets]).empty?
       return usage_error("give session ids") if options[:ids].empty?
 
       options
@@ -302,10 +312,11 @@ module Samagotchi
       if options[:continues]
         taken = [("--dir" if options[:dir])] +
                 LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])] +
-                [("--toolkit" if options[:toolkit])] + TOOLKIT_FLAGS.filter_map { |key, flag| flag unless Array(options[key]).empty? }
+                [("--toolkit" if options[:toolkit])] + TOOLKIT_FLAGS.filter_map { |key, flag| flag unless Array(options[key]).empty? } +
+                [("--set" unless Array(options[:sets]).empty?)]
         unless taken.compact.empty?
-          return usage_error("--continues takes the previous session's folder, LLM context, thinking level and " \
-                             "toolkit; " \
+          return usage_error("--continues takes the previous session's folder, LLM context, thinking level, " \
+                             "toolkit and bundle settings; " \
                              "leave out #{taken.compact.join(", ")}")
         end
       end
@@ -327,6 +338,11 @@ module Samagotchi
       end
       toolkit = Toolkit.from_flags(name: options[:toolkit], add: options[:tools], remove: options[:no_tools])
       options[:toolkit_value] = toolkit if toolkit
+      begin
+        options[:bundle_settings] = BundleSessionSettings.from_flags(options[:sets]) unless Array(options[:sets]).empty?
+      rescue BundleSessionSettings::Error => e
+        return usage_error(e.message)
+      end
 
       if options[:dir]
         options[:dir] = File.expand_path(options[:dir])
@@ -376,7 +392,8 @@ module Samagotchi
                                                           model_name: options[:model],
                                                           setup: SessionSetup.new(llm_context: options[:llm_context],
                                                                                   thinking: options[:thinking],
-                                                                                  toolkit: options[:toolkit_value]),
+                                                                                  toolkit: options[:toolkit_value],
+                                                                                  bundle_settings: options[:bundle_settings] || {}),
                                                           state_dir: @state_dir)
                   end
       rescue SessionContinue::Refused, SessionManager::ArchiveRefused, SessionManager::OwnedByTUI => e

data/lib/samagotchi/session.rb

@@ -208,6 +208,18 @@ module Samagotchi
       @toolkit = value.is_a?(Toolkit) ? value : Toolkit.from_file(value)
     end
 
+    # The session's own bundle settings (chi --set BUNDLE.KEY=VALUE):
+    # {bundle => {key => value}}, frozen, {} for none and for a session from
+    # before them. Given when it was created and never changed; a respawn,
+    # a continue and a fork keep them (SessionSetup.of), a delegate child
+    # doesn't. Plugin::Context#settings lays them over config.yml's.
+    attr_reader :bundle_settings
+
+    # @param value [Hash, nil] the session file's form too
+    def bundle_settings=(value)
+      @bundle_settings = BundleSessionSettings.normalize(value)
+    end
+
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by
@@ -242,7 +254,7 @@ module Samagotchi
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, interrupted_turn: nil)
+                   toolkit: nil, bundle_settings: {}, interrupted_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -272,6 +284,7 @@ module Samagotchi
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
       self.toolkit = toolkit
+      self.bundle_settings = bundle_settings
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
@@ -369,6 +382,7 @@ module Samagotchi
         reasoning_history: setup.reasoning_history,
         appended_prompt_files: setup.appended_prompt_files,
         toolkit: setup.toolkit,
+        bundle_settings: setup.bundle_settings,
         continues: continues
       )
     end
@@ -434,6 +448,7 @@ module Samagotchi
       "reasoning_history" => nil,
       "appended_prompt_files" => [],
       "toolkit" => nil,
+      "bundle_settings" => {},
       "interrupted_turn" => nil
     }.freeze
 

data/lib/samagotchi/session_metrics/cost.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionMetrics
+    # The session's spend so far (SessionMetrics#cost, what a bundle's
+    # ctx.cost reads), in USD: +reported+ by providers (usage.cost) and
+    # +estimated+ from configured prices (ModelPrice.estimate: a generation
+    # is one or the other, never both), each the main loop's and the side
+    # requests' together; +side+ is the side requests' share of the total
+    # (recap, /btw, ask_model). +known+ is false while generations or side
+    # requests ran but none was reported or priced: a cap can't be enforced
+    # on such a session. A session with some priced and some unpriced
+    # generations reads known (the unpriced ones count 0).
+    # Bundles use its methods only, never this constant's name.
+    Cost = Data.define(:reported, :estimated, :side, :known) do
+      def self.zero = new(reported: 0.0, estimated: 0.0, side: 0.0, known: true)
+
+      # @param totals [Totals] the session's sums, the running turn folded in
+      # @param side [SideTotals]
+      # @return [Cost]
+      def self.of(totals, side)
+        side_reported = side.cost_sum.to_f
+        side_estimated = side.cost_estimate_sum.to_f
+        reported = totals.cost_sum.to_f + side_reported
+        estimated = totals.cost_estimate_sum.to_f + side_estimated
+        ran = (totals.prompt_sum + totals.completion_sum).positive? || side.requests.positive?
+        new(reported: reported, estimated: estimated, side: side_reported + side_estimated,
+            known: !ran || reported.positive? || estimated.positive?)
+      end
+
+      # @return [Float] reported + estimated, side requests included
+      def total = reported + estimated
+
+      def known? = known
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -12,6 +12,7 @@ require_relative "model_price"
 require_relative "session"
 require_relative "session_metrics/totals"
 require_relative "session_metrics/model_segment"
+require_relative "session_metrics/cost"
 require_relative "session_metrics/side_totals"
 require_relative "side_usage"
 
@@ -365,6 +366,14 @@ module Samagotchi
       end
     end
 
+    # The session's spend now (ctx.cost): its turns' sums with the running
+    # turn's finished generations folded in, and its side requests.
+    # Safe from any thread.
+    # @return [Cost]
+    def cost
+      @mutex.synchronize { Cost.of(@totals.with_running(@turn), @side) }
+    end
+
     # Event sink. Safe to call from any thread; errors are isolated by the
     # caller (SessionObserver / TerminalUI) but we still guard internally.
     # @param event [Hash]

data/lib/samagotchi/session_setup.rb

@@ -4,6 +4,7 @@ require_relative "llm_context_override"
 require_relative "reasoning_history"
 require_relative "thinking"
 require_relative "toolkit"
+require_relative "bundle_session_settings"
 
 module Samagotchi
   # A session's own settings that come before its model's, carried as one
@@ -15,20 +16,26 @@ module Samagotchi
   # +appended_prompt_files+ the absolute paths chi --append-system-prompt
   # named (their text goes into the system prompt; [] with none),
   # +toolkit+ a Toolkit or nil (SessionManager.spawn_session gives the
-  # session config's toolkit.default then).
+  # session config's toolkit.default then), +bundle_settings+ the bundle
+  # settings chi --set gave ({bundle => {key => value}}, frozen; {} with
+  # none), which Plugin::Context#settings lays over config.yml's.
   #
   # It doesn't save itself: the session keeps each setting in its own field
   # and file key, and resolves it on its own. A delegate child starts
   # without one (but the toolkit its delegate call named); a continue and a
   # fork copy their session's (.of).
-  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit) do
-    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil)
+  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit,
+                             :bundle_settings) do
+    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil,
+                   bundle_settings: {})
       super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
-            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit)
+            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit,
+            bundle_settings: BundleSessionSettings.normalize(bundle_settings))
     end
 
     def empty?
-      llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil?
+      llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil? &&
+        bundle_settings.empty?
     end
 
     # A session's own setup, for a session that starts from it. Its
@@ -40,7 +47,8 @@ module Samagotchi
       return new if session.nil?
 
       new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
-          appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit))
+          appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit),
+          bundle_settings: session.bundle_settings)
     end
   end
 end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -50,7 +50,9 @@ module Samagotchi
       #   session's toolkit (config's toolkit.default without); an existing
       #   session keeps its own
       # @param toolkit_flags [Array<String>] which of those were given, for
-      #   the line an existing session's run prints
+      #   the line an existing session's run prints (--set too)
+      # @param bundle_settings [Hash] --set's values (BundleSessionSettings):
+      #   a new session's setup carries them; an existing session keeps its own
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
       # @return [Symbol] :detached, :closed when the worker went away,
@@ -58,11 +60,12 @@ module Samagotchi
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
               memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-              toolkit_flags: [], state_dir: nil)
+              toolkit_flags: [], bundle_settings: {}, state_dir: nil)
         state_dir ||= Session.default_state_dir
         client = connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
                          memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
-                         appended_prompt_files: appended_prompt_files, toolkit: toolkit, toolkit_flags: toolkit_flags)
+                         appended_prompt_files: appended_prompt_files, toolkit: toolkit, toolkit_flags: toolkit_flags,
+                         bundle_settings: bundle_settings)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -131,7 +134,7 @@ module Samagotchi
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
                   memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-                  toolkit_flags: [], err: $stderr)
+                  toolkit_flags: [], bundle_settings: {}, err: $stderr)
         sd = state_dir || Session.default_state_dir
         if attach || resume
           warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files,
@@ -153,7 +156,7 @@ module Samagotchi
                                                  setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
                                                                          thinking: Thinking.session_level(thinking),
                                                                          appended_prompt_files: appended_prompt_files,
-                                                                         toolkit: toolkit))
+                                                                         toolkit: toolkit, bundle_settings: bundle_settings))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")

data/lib/samagotchi/terminal_ui.rb

@@ -100,12 +100,16 @@ module Samagotchi
     # @param toolkit [Toolkit, nil] --toolkit/--tool/--no-tool: a new
     #   session's toolkit (config's toolkit.default without); a resumed one
     #   keeps its own, with a line naming +toolkit_flags+ (the flags given)
+    # @param bundle_settings [Hash] --set's values (BundleSessionSettings):
+    #   a new session's own; a resumed one keeps its own (--set is in
+    #   +toolkit_flags+ then)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
                    spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil,
-                   appended_prompt_files: [], toolkit: nil, toolkit_flags: [])
+                   appended_prompt_files: [], toolkit: nil, toolkit_flags: [], bundle_settings: {})
       @scratch        = scratch
       @toolkit        = toolkit
       @toolkit_flags  = toolkit_flags
+      @bundle_settings = bundle_settings
       @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
@@ -274,7 +278,8 @@ module Samagotchi
         preloaded_memory_names: @requested_memories,
         muted_memory_names: @muted_memory_names,
         scratch: @scratch,
-        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured)
+        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured,
+                                bundle_settings: @bundle_settings)
       ))
       # --llm-context*: the session's own values, over a resumed one's.
       # Saved at once on a resumed one: leaving before a turn keeps them.

data/lib/samagotchi/testing/bundle.rb

@@ -11,6 +11,7 @@ require_relative "../peer_sources"
 require_relative "../toolkit"
 require_relative "../guardrails/gate"
 require_relative "../memory_bundle/manifest"
+require_relative "../session_setup"
 require_relative "sandbox"
 require_relative "recorder"
 require_relative "host"
@@ -74,11 +75,15 @@ module Samagotchi
         # @param dir [String] the bundle's folder (its manifest.yml)
         # @param settings [Hash] config.yml `bundles: <name>:`
         # @param host [Hash] session values (Recorder::DEFAULTS' keys)
+        # @param session_settings [Hash] the session's own values for the
+        #   bundle (chi --set), keys its manifest lists in session_settings:;
+        #   ctx.settings lays them over +settings+ (Plugin::Context#settings),
+        #   initialize(settings) doesn't see them
         # @param sandbox [Sandbox, nil] default Sandbox.current, else one of
         #   its own, left at #shutdown
         # @return [Bundle]
-        def load(dir, settings: {}, host: {}, sandbox: nil)
-          new(dir, settings: settings, host: host, sandbox: sandbox).tap(&:load!)
+        def load(dir, settings: {}, host: {}, session_settings: {}, sandbox: nil)
+          new(dir, settings: settings, host: host, session_settings: session_settings, sandbox: sandbox).tap(&:load!)
         end
 
         # A bundle chi ships (lib/samagotchi/bundles/<name>), as #load.
@@ -118,14 +123,16 @@ module Samagotchi
       # @return [Integer] how often chi was told the tools changed
       attr_reader :tools_changes
 
-      def initialize(dir, settings: {}, host: {}, sandbox: nil)
+      def initialize(dir, settings: {}, host: {}, session_settings: {}, sandbox: nil)
         @dir = File.expand_path(dir)
         @manifest = MemoryBundle::Manifest.read(dir: @dir)
         @name = @manifest.name
         @settings = stringify(settings || {})
+        @session_moves = 1
+        own = session_settings.nil? || session_settings.empty? ? {} : { setup: setup_with(session_settings, host[:setup]) }
         @own_sandbox = sandbox.nil? && Sandbox.current.nil?
         @sandbox = sandbox || Sandbox.current || Sandbox.enter
-        @recorder = Recorder.new(cwd: @sandbox.work_dir, **host)
+        @recorder = Recorder.new(cwd: @sandbox.work_dir, **host, **own)
         @sessions = Sessions.new
         @http = FakeHttp.new
         @inits = []
@@ -309,7 +316,16 @@ module Samagotchi
       end
 
       # Change the session's values (cwd:, messages:, running: …).
-      def set(**values)
+      # +session_settings+ changes the session's own values for the bundle
+      # (as Bundle.load's) and moves it to a new session id
+      # ("test-session-2", or the session_id: given beside it): chi never
+      # changes them within a session, and ctx.settings is built once per
+      # session id.
+      def set(session_settings: nil, **values)
+        unless session_settings.nil?
+          values[:setup] = setup_with(session_settings, @recorder[:setup])
+          values[:session_id] ||= "#{@recorder[:session_id] || "test-session"}-#{@session_moves += 1}"
+        end
         @recorder.set(**values)
         self
       end
@@ -363,6 +379,16 @@ module Samagotchi
         result
       end
 
+      # +setup+ (the recorder's, nil for none) with +session_settings+ as
+      # this bundle's own values, checked against the manifest's
+      # session_settings: as chi --set checks them.
+      # @raise [ArgumentError] a key the manifest doesn't list
+      def setup_with(session_settings, setup)
+        values = { @name => stringify(session_settings) }
+        BundleSessionSettings.check!(values, bundles: { @name => @manifest.session_settings }, flag: "session_settings")
+        (setup || SessionSetup.new).with(bundle_settings: values)
+      end
+
       def stringify(value)
         case value
         when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }