samagotchi 0.50.0 → 0.52.0

data/lib/samagotchi/config.rb

@@ -15,6 +15,11 @@ require_relative "host_model"
 module Samagotchi
   # Parses the thinking: levels of host and model entries (it needs Config).
   autoload :Thinking, File.expand_path("thinking", __dir__)
+  # One hosts: entry; it needs ConfigFile's readers.
+  autoload :HostConfig, File.expand_path("host_config", __dir__)
+  # One models: entry, and one field found in them; they need ConfigFile's readers.
+  autoload :ModelSettings, File.expand_path("model_settings", __dir__)
+  autoload :ModelSetting, File.expand_path("model_settings", __dir__)
 
   # Unified configuration registry implementing the implicit convention:
   #   ENV    SAMAGOTCHI_ATTR            (UPPER + prefix + _ = nesting)
@@ -170,10 +175,10 @@ module Samagotchi
       Entry.new(key: "llm_context.stale_edits",  yaml_path: %w[llm_context stale_edits],  type: :bool,   default: false,            expose: %i[env config]),
       # The steps (tool batches) back whose edited files' reads stale never stubs.
       Entry.new(key: "llm_context.protect_steps", yaml_path: %w[llm_context protect_steps], type: :integer, default: 3,             expose: %i[env config]),
-      # A soft context budget in tokens: the context status bands (and the forget layer's offers) count against it
-      # instead of the window; unset or 0: off. models.<key>.llm_context_budget_tokens and
-      # hosts.<name>.llm_context_budget_tokens come first.
-      Entry.new(key: "llm_context.budget_tokens", yaml_path: %w[llm_context budget_tokens], type: :integer, default: nil,          expose: %i[env config]),
+      # A soft context budget in tokens (64000, 64k; 4k to 10M): the context status bands (and the forget layer's
+      # offers) count against it instead of the window; unset, 0 or off: off. models.<key>.llm_context_budget_tokens
+      # and hosts.<name>.llm_context_budget_tokens come first. Kept as written: LLMContextStrategy.parse_budget reads it.
+      Entry.new(key: "llm_context.budget_tokens", yaml_path: %w[llm_context budget_tokens], type: :string, default: nil,           expose: %i[env config]),
       # The policy sentence forget_outputs' description carries (the forget layer); blank: none.
       Entry.new(key: "llm_context.policy",       yaml_path: %w[llm_context policy],       type: :string, default: LLMContextStrategy::DEFAULT_POLICY, expose: %i[env config]),
 
@@ -841,6 +846,10 @@ module Samagotchi
     HOST_NAME_RE = /\A[a-z0-9][a-z0-9._-]*\z/i
     ENV_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
 
+    # config.yml's hosts: (or a worker's SAMAGOTCHI_HOSTS_JSON) by lowercased
+    # name; an entry that is disabled or invalid (warned) is left out. No
+    # entry left: "default", from server.host/port/transport.
+    # @return [Hash{String => HostConfig}]
     def hosts_config(env: ENV, path: global_path(env: env))
       data = read_yaml(env: env, path: path)
       raw_hosts = hosts_source(data, env)
@@ -848,143 +857,38 @@ module Samagotchi
       normalized = {}
       if raw_hosts.is_a?(Hash)
         raw_hosts.each do |raw_name, raw_cfg|
-          name = raw_name.to_s.strip
-          next if name.empty?
-
-          unless name.match?(HOST_NAME_RE)
-            warn_once "Warning: ignoring hosts entry '#{name}': must match /[a-z0-9][a-z0-9._-]*/i"
-            next
-          end
-          lowered = name.downcase
-          unless raw_cfg.is_a?(Hash)
-            warn_once "Warning: ignoring hosts entry '#{name}': expected mapping"
-            next
-          end
-          host = raw_cfg["host"] || raw_cfg[:host]
-          port = raw_cfg["port"] || raw_cfg[:port]
-          transport = raw_cfg["transport"] || raw_cfg[:transport]
-          api = raw_cfg["api"] || raw_cfg[:api]
-          next if host_disabled?(raw_cfg)
-
-          url = (raw_cfg["url"] || raw_cfg[:url]).to_s.strip
-          api_key_env = (raw_cfg["api_key_env"] || raw_cfg[:api_key_env]).to_s.strip
-          # Kept as written; ModelProfile.resolve warns about an unknown one.
-          profile = (raw_cfg["profile"] || raw_cfg[:profile]).to_s.strip.downcase
-          first_token_timeout = raw_cfg.key?("first_token_timeout") ? raw_cfg["first_token_timeout"] : raw_cfg[:first_token_timeout]
-          vision = ConfigFile.vision_flag(raw_cfg.key?("vision") ? raw_cfg["vision"] : raw_cfg[:vision], "hosts entry '#{name}'")
-          remote = ConfigFile.bool_flag(raw_cfg.key?("remote") ? raw_cfg["remote"] : raw_cfg[:remote], "hosts entry '#{name}'",
-                                        "remote")
-          window = ConfigFile.window_tokens(raw_cfg.key?("window_tokens") ? raw_cfg["window_tokens"] : raw_cfg[:window_tokens],
-                                            "hosts entry '#{name}'")
-          sampling = ConfigFile.sampling_map(raw_cfg.key?("sampling") ? raw_cfg["sampling"] : raw_cfg[:sampling], "hosts entry '#{name}'")
-          thinking = Thinking.level(raw_cfg.key?("thinking") ? raw_cfg["thinking"] : raw_cfg[:thinking], "hosts entry '#{name}'")
-          llm_context = LLMContextStrategy.parse(raw_cfg.key?(LLMContextStrategy::KEY) ? raw_cfg[LLMContextStrategy::KEY] : raw_cfg[:llm_context_strategy],
-                                                 "hosts entry '#{name}'")
-          llm_context_apply = LLMContextStrategy.parse_apply(raw_cfg.key?(LLMContextStrategy::APPLY_KEY) ? raw_cfg[LLMContextStrategy::APPLY_KEY] : raw_cfg[:llm_context_apply],
-                                                             "hosts entry '#{name}'")
-          models = HostModel.parse_map(raw_cfg.key?("models") ? raw_cfg["models"] : raw_cfg[:models], name)
-          llm_context_budget = LLMContextStrategy.parse_budget(raw_cfg.key?(LLMContextStrategy::BUDGET_KEY) ? raw_cfg[LLMContextStrategy::BUDGET_KEY] : raw_cfg[:llm_context_budget_tokens],
-                                                               "hosts entry '#{name}'")
-          unless first_token_timeout.nil? || (first_token_timeout.is_a?(Numeric) && !first_token_timeout.negative?)
-            warn_once "Warning: hosts entry '#{name}': first_token_timeout must be seconds (0 = off); using the default"
-            first_token_timeout = nil
-          end
-          unless api_key_env.empty? || api_key_env.match?(ENV_NAME_RE)
-            warn_once "Warning: ignoring hosts entry '#{name}': api_key_env must be an environment variable name"
-            next
-          end
-          scheme = "http"
-          unless url.empty?
-            unless host.to_s.strip.empty? && port.to_s.strip.empty?
-              warn_once "Warning: ignoring hosts entry '#{name}': give url or host/port, not both"
-              next
-            end
-            uri = begin
-              URI.parse(url)
-            rescue URI::InvalidURIError
-              nil
-            end
-            unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
-              warn_once "Warning: ignoring hosts entry '#{name}': url must be an http(s) URL"
-              next
-            end
-            host = uri.host
-            port = uri.port
-            scheme = uri.scheme
-            url = url.chomp("/")
-          end
-          host = host.to_s.strip
-          if host.empty?
-            warn_once "Warning: ignoring hosts entry '#{name}': host is required"
-            next
-          end
-          port_val = port.to_s.strip.empty? ? 8080 : port.to_i
-          if port_val <= 0 || port_val > 65_535
-            warn_once "Warning: ignoring hosts entry '#{name}': invalid port"
-            next
-          end
-          transport_val = transport.to_s.strip.downcase
-          if transport_val.empty?
-            transport_val = nil
-          elsif !VALID_TRANSPORTS_FOR_CONFIG.include?(transport_val)
-            warn_once "Warning: ignoring hosts entry '#{name}': unknown transport '#{transport_val}'"
-            next
-          end
-          api_val = api.to_s.strip.downcase
-          if api_val.empty?
-            api_val = nil
-          elsif !VALID_APIS_FOR_CONFIG.include?(api_val)
-            warn_once "Warning: ignoring hosts entry '#{name}': unknown api '#{api_val}'"
-            next
-          elsif VALID_TRANSPORTS_FOR_CONFIG.include?(api_val)
-            # A raw-prompt api is the transport; a different transport contradicts it.
-            if transport_val && transport_val != api_val
-              warn_once "Warning: ignoring hosts entry '#{name}': api '#{api_val}' conflicts with transport '#{transport_val}'"
-              next
-            end
-            transport_val = api_val
-          end
-          normalized[lowered] = { name: lowered, host: host, port: port_val, transport: transport_val ? transport_val.to_sym : nil,
-                                  api: api_val&.to_sym, original_name: name, scheme: scheme,
-                                  url: url.empty? ? nil : url, api_key_env: api_key_env.empty? ? nil : api_key_env,
-                                  profile: profile.empty? ? nil : profile, first_token_timeout: first_token_timeout,
-                                  vision: vision, sampling: sampling, thinking: thinking, remote: remote,
-                                  window_tokens: window, llm_context_strategy: llm_context,
-                                  llm_context_apply: llm_context_apply, llm_context_budget_tokens: llm_context_budget,
-                                  models: models }
+          host = HostConfig.parse(raw_name, raw_cfg)
+          normalized[host.name] = host if host
         end
         warn_duplicate_host_models(normalized)
       end
-
-      # If no hosts defined, synthesize "default" from server.host/port/transport.
-      if normalized.empty?
-        opts = { file_data: data, env: env, cli_overrides: Samagotchi::Config.cli_overrides }
-        default_host = Samagotchi::Config.resolve("server.host", **opts).to_s.strip
-        default_host = "localhost" if default_host.empty?
-        default_port = Samagotchi::Config.resolve("server.port", **opts).to_i
-        default_port = 8080 if default_port <= 0 || default_port > 65_535
-        transport_sym = Samagotchi::Config.resolve_with_origin("server.transport", **opts).then do |value, origin|
-          origin == :default ? nil : value.to_sym
-        end
-        normalized["default"] = { name: "default", host: default_host, port: default_port, transport: transport_sym, original_name: "default" }
-      end
+      normalized["default"] = default_host_config(data, env) if normalized.empty?
       normalized
-    rescue StandardError
+    rescue StandardError => e
+      Log.error(:config, "hosts_config_failed", error: e.class.name, message: e.message)
       {}
     end
 
-    # hosts.<name>.models as written back (HostModel#to_config), nil when none.
-    def host_models_config(models)
-      models.values.to_h { |m| [m.id, m.to_config] } unless models.nil? || models.empty?
+    # The host chi uses when hosts: names none: server.host/port/transport.
+    def default_host_config(data, env)
+      opts = { file_data: data, env: env, cli_overrides: Samagotchi::Config.cli_overrides }
+      host = Samagotchi::Config.resolve("server.host", **opts).to_s.strip
+      host = "localhost" if host.empty?
+      port = Samagotchi::Config.resolve("server.port", **opts).to_i
+      port = 8080 if port <= 0 || port > 65_535
+      transport = Samagotchi::Config.resolve_with_origin("server.transport", **opts).then do |value, origin|
+        origin == :default ? nil : value.to_sym
+      end
+      HostConfig.new(name: "default", host: host, port: port, transport: transport)
     end
-    private_class_method :host_models_config
+    private_class_method :default_host_config
 
     # Two hosts declaring one id under hosts.<name>.models: a bare id goes
     # where HostRegistry#host_for_model sends it (the default host when it
     # declares the id, else the first in hosts: order); say so once.
     def warn_duplicate_host_models(hosts)
       declared = Hash.new { |h, k| h[k] = [] }
-      hosts.each { |name, cfg| cfg[:models].each { |down, model| declared[down] << [name, model.id] } }
+      hosts.each { |name, cfg| cfg.models.each { |down, model| declared[down] << [name, model.id] } }
       declared.each_value do |owners|
         next if owners.size < 2
 
@@ -1005,7 +909,7 @@ module Samagotchi
       raw = hosts_source(read_yaml(env: env, path: path), env)
       return [] unless raw.is_a?(Hash)
 
-      raw.filter_map { |name, cfg| name.to_s.strip.downcase if cfg.is_a?(Hash) && host_disabled?(cfg) }
+      raw.filter_map { |name, cfg| name.to_s.strip.downcase if cfg.is_a?(Hash) && HostConfig.disabled?(cfg) }
     rescue StandardError
       []
     end
@@ -1026,17 +930,6 @@ module Samagotchi
     end
     private_class_method :hosts_source
 
-    # enabled: false (or "false", any case) in a hosts entry.
-    def host_disabled?(cfg)
-      enabled = if cfg.key?("enabled")
-                  cfg["enabled"]
-                else
-                  (cfg.key?(:enabled) ? cfg[:enabled] : true)
-                end
-      enabled == false || enabled.to_s.strip.downcase == "false"
-    end
-    private_class_method :host_disabled?
-
     # Resolve the `recap:` section through the Config registry so scalar
     # recap settings share the single precedence path (CLI > ENV > file >
     # default). Returns false when explicitly disabled (file `recap: false`
@@ -1115,25 +1008,14 @@ module Samagotchi
       # include when hosts file exists with hosts: section or when workers need propagation
       return nil if hosts.nil? || hosts.empty?
 
-      # Serialize to JSON with string keys
-      simple = hosts.transform_values do |v|
-        # A url entry travels as its url (host/port come from it); the API
-        # key stays in the environment, which workers inherit.
-        location = v[:url] ? { "url" => v[:url] } : { "host" => v[:host], "port" => v[:port] }
-        location.merge("transport" => v[:transport]&.to_s, "api" => v[:api]&.to_s, "api_key_env" => v[:api_key_env],
-                       "profile" => v[:profile], "first_token_timeout" => v[:first_token_timeout],
-                       "vision" => v[:vision], "sampling" => v[:sampling], "thinking" => v[:thinking]&.to_s,
-                       "remote" => v[:remote], "window_tokens" => v[:window_tokens],
-                       "llm_context_strategy" => v[:llm_context_strategy]&.map(&:to_s),
-                       "llm_context_apply" => v[:llm_context_apply]&.to_s,
-                       "llm_context_budget_tokens" => v[:llm_context_budget_tokens],
-                       "models" => host_models_config(v[:models])).compact
-      end
+      # Every field travels (HostConfig#to_env_h); the worker parses it back.
+      simple = hosts.transform_values(&:to_env_h)
       # Disabled hosts travel as just that, so a worker refuses "box:x"
       # the way its parent does instead of sending it to the default host.
       disabled_host_names(env: env, path: path).grep(HOST_NAME_RE).each { |name| simple[name] ||= { "enabled" => false } }
       JSON.generate(simple)
-    rescue StandardError
+    rescue StandardError => e
+      Log.error(:config, "hosts_json_failed", error: e.class.name, message: e.message)
       nil
     end
 
@@ -1197,9 +1079,9 @@ module Samagotchi
     end
 
     # The top-level `models:` map: per-model settings keyed by model id or
-    # alias (downcased), e.g. `models: {my-alias: {profile: qwen36}}`. Values are
-    # kept as written (profile downcased; ModelProfile.resolve validates it);
-    # an entry that is not a map is skipped.
+    # alias (downcased), e.g. `models: {my-alias: {profile: qwen36}}`, each a
+    # ModelSettings; an entry that is not a map is skipped.
+    # @return [Hash{String => ModelSettings}]
     def model_settings(env: ENV, path: global_path(env: env))
       data = read_yaml(env: env, path: path)
       raw = data[MODELS_KEY] if data.is_a?(Hash)
@@ -1207,40 +1089,26 @@ module Samagotchi
 
       raw.each_with_object({}) do |(k, v), result|
         key = k.to_s.strip.downcase
-        next if key.empty? || !v.is_a?(Hash)
-
-        profile = (v["profile"] || v[:profile]).to_s.strip.downcase
-        vision = vision_flag(v.key?("vision") ? v["vision"] : v[:vision], "models: #{key}")
-        result[key] = { profile: profile.empty? ? nil : profile }
-        result[key][:vision] = vision unless vision.nil?
-        sampling = sampling_map(v.key?("sampling") ? v["sampling"] : v[:sampling], "models: #{key}")
-        result[key][:sampling] = sampling if sampling
-        thinking = Thinking.level(v.key?("thinking") ? v["thinking"] : v[:thinking], "models: #{key}")
-        result[key][:thinking] = thinking if thinking
-        window = window_tokens(v.key?("window_tokens") ? v["window_tokens"] : v[:window_tokens], "models: #{key}")
-        result[key][:window_tokens] = window if window
-        layers = LLMContextStrategy.parse(v.key?(LLMContextStrategy::KEY) ? v[LLMContextStrategy::KEY] : v[:llm_context_strategy],
-                                          "models: #{key}")
-        result[key][:llm_context_strategy] = layers if layers
-        apply = LLMContextStrategy.parse_apply(v.key?(LLMContextStrategy::APPLY_KEY) ? v[LLMContextStrategy::APPLY_KEY] : v[:llm_context_apply],
-                                               "models: #{key}")
-        result[key][:llm_context_apply] = apply if apply
-        budget = LLMContextStrategy.parse_budget(v.key?(LLMContextStrategy::BUDGET_KEY) ? v[LLMContextStrategy::BUDGET_KEY] : v[:llm_context_budget_tokens],
-                                                 "models: #{key}")
-        result[key][:llm_context_budget_tokens] = budget if budget
+        settings = ModelSettings.parse(key, v)
+        result[key] = settings if settings
       end
     rescue StandardError
       {}
     end
 
     # The first +names+ (model as typed, alias-resolved, bare, …) whose
-    # models: entry sets +field+: [key, value], or nil. VisionSupport and
-    # SamplingSettings look a model up the same way.
+    # models: entry sets +field+ (a ModelSettings member; another name
+    # raises ArgumentError): a ModelSetting (key, value), or nil.
+    # VisionSupport and SamplingSettings look a model up the same way.
+    # @param models [Hash{String => ModelSettings}, nil] model_settings by default
+    # @return [ModelSetting, nil]
     def model_setting(names, field, models: nil)
+      raise ArgumentError, "unknown models: field #{field.inspect}" unless ModelSettings.members.include?(field)
+
       models ||= model_settings
       Array(names).map { |name| name.to_s.strip.downcase }.reject(&:empty?).uniq.each do |key|
-        value = models.dig(key, field)
-        return [key, value] unless value.nil?
+        value = models[key]&.public_send(field)
+        return ModelSetting.new(key: key, value: value) unless value.nil?
       end
       nil
     end

data/lib/samagotchi/config_text_edit.rb

@@ -3,6 +3,7 @@
 require "json"
 require "yaml"
 require "psych"
+require_relative "yaml_lines"
 
 module Samagotchi
   # Sets one section.key in config.yml text, line by line, so the user's
@@ -15,7 +16,9 @@ module Samagotchi
   # section, anchors, a duplicate section), the whole file is dumped from
   # +expected+ instead.
   module ConfigTextEdit
-    DEFAULT_INDENT = 2
+    extend YAMLLines
+
+    DEFAULT_INDENT = YAMLLines::DEFAULT_INDENT
 
     module_function
 
@@ -42,9 +45,7 @@ module Samagotchi
       section_data = original[section]
       has_key = section_data.is_a?(Hash) && section_data.keys.any? { |k| k.to_s.downcase == key.downcase }
 
-      eol = text.include?("\r\n") ? "\r\n" : "\n"
-      lines = text.split(/(?<=\n)/)
-      lines[-1] = "#{lines[-1]}#{eol}" if lines.any? && !lines[-1].end_with?("\n")
+      lines, eol = lines_of(text)
       header = /\A#{Regexp.escape(section)}:[ \t]*(#.*)?\z/
       starts = lines.each_index.select { |i| lines[i].chomp.match?(header) }
       return nil if starts.length > 1
@@ -57,9 +58,8 @@ module Samagotchi
       end
 
       at = starts.first
-      stop = at + 1
-      stop += 1 while stop < lines.length && inside_block?(lines[stop])
-      children = lines[(at + 1)...stop].reject { |line| line.strip.empty? || comment?(line) }
+      stop = block_stop(lines, at)
+      children = lines[(at + 1)...stop].reject { |line| blank_or_comment?(line) }
       child = children.first ? indent(children.first) : DEFAULT_INDENT
       new_line = "#{" " * child}#{key}: #{scalar(value)}#{eol}"
       found = ((at + 1)...stop).find { |i| indent(lines[i]) == child && key_of(lines[i])&.downcase == key.downcase }
@@ -68,8 +68,7 @@ module Samagotchi
       else
         return nil if has_key
 
-        stop -= 1 while stop > at + 1 && (lines[stop - 1].strip.empty? || (comment?(lines[stop - 1]) && indent(lines[stop - 1]) < child))
-        lines.insert(stop, new_line)
+        lines.insert(insert_at(lines, at, stop, child), new_line)
       end
       lines.join
     end
@@ -78,30 +77,7 @@ module Samagotchi
       line[/\A\s*(["']?)([^"':#\s][^"':#]*?)\1:(?:\s|\z)/, 2]
     end
 
-    def inside_block?(line)
-      return true if line.strip.empty?
-      return false if line.start_with?("---", "...")
-
-      line.start_with?(" ", "\t") || comment?(line)
-    end
-
-    def comment?(line) = line.lstrip.start_with?("#")
-    def indent(line) = line[/\A */].length
-
     # JSON's quoting is valid YAML: model ids hold "/" and ":".
     def scalar(value) = JSON.generate(value.to_s)
-
-    def parse(text) = YAML.safe_load(text, permitted_classes: [], aliases: false)
-
-    def anchors?(text)
-      stack = [Psych.parse_stream(text)]
-      until stack.empty?
-        node = stack.pop
-        return true if node.is_a?(Psych::Nodes::Alias) || (node.respond_to?(:anchor) && node.anchor)
-
-        stack.concat(Array(node.children)) if node.respond_to?(:children)
-      end
-      false
-    end
   end
 end

data/lib/samagotchi/context_sources.rb

@@ -220,13 +220,6 @@ module Samagotchi
         data ? Snapshot.from_h(data) : Snapshot.empty
       end
 
-      # @return [Time, nil] the snapshot file's mtime: the worker's cheap "anything new?"
-      def snapshot_mtime(name)
-        File.mtime(snapshot_path(name))
-      rescue SystemCallError
-        nil
-      end
-
       def write_snapshot(name, snapshot)
         FileUtils.mkdir_p(dir)
         AtomicFile.write(snapshot_path(name), JSON.generate(snapshot.to_h))

data/lib/samagotchi/context_window.rb

@@ -50,11 +50,11 @@ module Samagotchi
     # and vision look a model up), else hosts.<name>.window_tokens.
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] HostRegistry#lookup_names
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
     # @return [Resolved, nil]
     def setting(target, names:, models: nil)
       models ||= ConfigFile.model_settings
-      _key, tokens = ConfigFile.model_setting(names, :window_tokens, models: models)
+      tokens = ConfigFile.model_setting(names, :window_tokens, models: models)&.value
       return Resolved.new(tokens: tokens, source: :model_setting) if positive_integer?(tokens)
 
       tokens = target&.entry&.window_tokens

data/lib/samagotchi/continue_offer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "last_turn"
 require_relative "log"
 
 module Samagotchi
@@ -85,11 +86,11 @@ module Samagotchi
     # Stop runs no turn: last_turn says so (not_continued), so a wait on
     # it ends (chi answer --option Stop).
     def announce_resolved(result, command)
-      @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command[:client_id])
+      @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command.client_id)
       return if result.resume
 
       session = @engine.session
-      session.last_turn = { "outcome" => NOT_CONTINUED, "ended_at" => Time.now.iso8601(3) } if session
+      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3)) if session
     end
 
     # After a command's command_ran and save: a /continue that answered the
@@ -128,7 +129,7 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
+        @run_turn.call(nil, continue: true, origin: { client_id: command.client_id }.compact,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
             announce_offer(offer)
@@ -183,7 +184,7 @@ module Samagotchi
     # The limit the offer's turn ran out at (Engine's last_turn marker).
     def limit_of_last_turn
       last = @engine.session&.last_turn
-      last.is_a?(Hash) && last["exhausted"] ? last["limit"] : nil
+      last&.exhausted ? last.limit : nil
     end
 
     # The question's answer as the /continue line a typed answer would be:

data/lib/samagotchi/cut_policy.rb

@@ -22,7 +22,6 @@ module Samagotchi
     Outcome = Data.define(:kind) do
       def stopped? = kind == :stopped
       def again? = kind == :again
-      def hook? = kind == :hook
     end
 
     STOPPED = Outcome.new(kind: :stopped)

data/lib/samagotchi/delivery.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # What a message sent to a running turn does when it arrives: wait for the
+  # turn's next step boundary and go in there (the default), cut the running
+  # generation short to go in now, or wait for the turn to end and run as a
+  # turn of its own (see docs/configuration.md). The field travels as the
+  # wire value name; a sender that names nothing gets the default.
+  module Delivery
+    NEXT_STEP = "next_step"
+    CUT = "cut"
+    QUEUE = "queue"
+    VALUES = [NEXT_STEP, CUT, QUEUE].freeze
+
+    # A body's delivery field as one of VALUES. Missing, empty or unknown:
+    # NEXT_STEP (an older client, a hand-written request).
+    # @param raw [Object] the wire value
+    # @return [String] one of VALUES
+    def self.parse(raw)
+      raw.is_a?(String) && VALUES.include?(raw) ? raw : NEXT_STEP
+    end
+
+    # Why a request body's delivery field can't be taken, as {error:,
+    # detail:} for a 400, or nil when it can. The Bridge and the web's
+    # POST /turn both ask this, so they refuse the same values. A missing
+    # or unknown string is not refused: it is the default (#parse). QUEUE
+    # is refused until a worker runs it (no worker reads it yet, so it
+    # would merge at the next step while the ack said queue).
+    # @param raw [Object] the wire value
+    # @return [Hash, nil]
+    def self.refusal(raw)
+      return nil if raw.nil?
+      return { error: "bad_delivery", detail: "delivery must be a string" } unless raw.is_a?(String)
+      return QUEUE_UNAVAILABLE if raw == QUEUE
+
+      nil
+    end
+
+    QUEUE_UNAVAILABLE = {
+      error: "delivery_unavailable",
+      detail: "delivery queue isn't available yet; without it the message goes in at the running turn's next step " \
+              "(or runs as a turn when none runs)"
+    }.freeze
+    private_constant :QUEUE_UNAVAILABLE
+
+    # Whether it is the one every sender defaulting to a step boundary uses.
+    def self.next_step?(value) = parse(value) == NEXT_STEP
+
+    # Whether the running turn should be cut for it (only when the message
+    # asks: nothing else cuts).
+    def self.cut?(value) = parse(value) == CUT
+
+    # Whether it waits for the turn to end and runs as a turn of its own.
+    def self.queue?(value) = parse(value) == QUEUE
+  end
+end

data/lib/samagotchi/engine.rb

@@ -954,7 +954,7 @@ module Samagotchi
       served, served_for = served_model_for(snapshot, target: target)
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
                                 served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
-                                prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
+                                thinking: thinking_explained&.summary, prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -1029,16 +1029,46 @@ module Samagotchi
       nil
     end
 
-    # "off (models: qwen)" for /model: the effective model's thinking level
-    # and where it came from, nil when none is set.
+    # "off (models: qwen)", "low (session)" for /model: the effective
+    # model's thinking level and where it came from, nil when none is set.
     def thinking_summary
+      explained = thinking_explained
+      explained&.source ? explained.label : nil
+    end
+
+    # The effective model's thinking level with where it came from and the
+    # session's own (Thinking::Explained), as the next turn resolves it;
+    # nil when it can't be resolved.
+    # @return [Thinking::Explained, nil]
+    def thinking_explained
       target = @host_registry.resolve(@effective_model_name)
-      level, source = Thinking.resolve(target, names: model_lookup_names(target))
-      source ? "#{level} (#{source})" : nil
+      Thinking.explain(target, names: model_lookup_names(target), session: thinking_override)
     rescue StandardError
       nil
     end
 
+    # The session's own thinking level, nil when it has none.
+    # @return [Symbol, nil]
+    def thinking_override = @session&.thinking
+
+    # What a thinking level change costs the effective model's prompt
+    # cache (Thinking.cache_cost): :full, :provider or :tail.
+    # @return [Symbol]
+    def thinking_cache_cost
+      target = @host_registry.resolve(@effective_model_name)
+      Thinking.cache_cost(target, profile: target.entry&.chat? ? nil : profile&.name)
+    end
+
+    # Set the session's own thinking level (nil unsets it); the next turn's
+    # start resolves it, never a running one (its TurnSettings are fixed).
+    # The caller saves the session.
+    # @raise [ArgumentError] with no session yet
+    def thinking_override=(level)
+      raise ArgumentError, "no session yet" unless @session
+
+      @session.thinking = level
+    end
+
     # The model the server serves for the current model, and the name asked
     # for: what the last generation of that name reported, else llama.cpp's
     # model_alias (/props, one short cached probe; not with probe: false),
@@ -1105,6 +1135,7 @@ module Samagotchi
         served_expected_by: served_expected_by(served_pair[0]),
         context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
         llm_context: llm_context_summary,
+        thinking: thinking_explained&.summary,
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1242,22 +1273,22 @@ module Samagotchi
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
-      session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
-                            "seconds" => seconds.round(1), "origin" => source }
-      session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
-      session.last_turn.merge!(stop_facts(event))
+      session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
+                                       origin: source, exhausted: limit ? true : nil, limit: limit,
+                                       **stop_facts(event))
     end
 
-    # Why a turn stopped, from its end event, for a parent agent's wait
-    # (ReplyWait): a provider error's kind and whether a retry may help, a
-    # cancel's reason and the hook that stopped it. Only what is known.
+    # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
+    # parent agent's wait (ReplyWait): a provider error's kind and whether
+    # a retry may help, a cancel's reason and the hook that stopped it.
+    # Only what is known.
     def stop_facts(event)
       case event&.dig(:type)
       # 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
+        { error_kind: event[:error_kind]&.to_s, retryable: event[:retryable], kept_steps: event[:kept_steps] }
       when :turn_canceled
-        { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
+        { cancel_reason: event[:cancellation_reason]&.to_s, stopped_by: event[:cancelled_by]&.to_s }
       else {}
       end
     end
@@ -2237,9 +2268,9 @@ module Samagotchi
       hook_notify(text, level, "thinking")
     end
 
-    # +target+'s thinking level (Thinking.resolve).
+    # +target+'s thinking level (Thinking.resolve), the session's own first.
     def thinking_level(target)
-      Thinking.resolve(target, names: model_lookup_names(target)).first
+      Thinking.resolve(target, names: model_lookup_names(target), session: thinking_override).first
     rescue StandardError
       Thinking::DEFAULT
     end
@@ -2470,7 +2501,7 @@ module Samagotchi
         model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
-        llm_context: -> { @session&.llm_context },
+        setup: -> { SessionSetup.of(@session) },
         frontend: -> { interface }
       )
     end