samagotchi 0.50.0 → 0.52.0

data/lib/samagotchi/engine_peers.rb

@@ -17,6 +17,7 @@ module Samagotchi
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
       def relay = engine.relay_peer
       def model_ref = engine.effective_model_ref
+      def thinking = engine.thinking_override
     end
 
     # What the approval relay needs from the parent's Engine (Peers#relay):

data/lib/samagotchi/host_config.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "config"
+require_relative "host_model"
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
+  # holds them by lowercased name; HostRegistry builds its HostEntry from
+  # one). A worker gets its parent's hosts back through
+  # SAMAGOTCHI_HOSTS_JSON: #to_env_h writes every field, and .parse reads
+  # it back to an equal HostConfig.
+  #
+  # name: the lowercased entry name; host, port, scheme: where it is (from
+  # url: when given); url: the configured url, nil when host/port; transport,
+  # api: symbols, nil when unset; the rest as HostRegistry::HostEntry
+  # describes them, nil when unset; models: {downcased id => HostModel}.
+  HostConfig = Data.define(:name, :host, :port, :scheme, :url, :transport, :api, :api_key_env, :profile,
+                           :first_token_timeout, :vision, :sampling, :thinking, :remote, :window_tokens,
+                           :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens, :models) do
+    # Every field but name may be left out: nil, models {}.
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
+    end
+
+    # A hosts: entry as written (YAML, or a worker's SAMAGOTCHI_HOSTS_JSON),
+    # or nil when it is disabled (enabled: false) or invalid. An invalid
+    # one warns once, naming the entry, the way each reader of a setting
+    # does for a bad value (that value is then unset).
+    # @param raw_name [String, Symbol]
+    # @param raw [Hash] string or symbol keys
+    # @return [HostConfig, nil]
+    def self.parse(raw_name, raw)
+      name = raw_name.to_s.strip
+      return nil if name.empty?
+      return invalid(name, "must match /[a-z0-9][a-z0-9._-]*/i") unless name.match?(ConfigFile::HOST_NAME_RE)
+      return invalid(name, "expected mapping") unless raw.is_a?(Hash)
+      return nil if disabled?(raw)
+
+      value = ->(key) { raw.key?(key.to_s) ? raw[key.to_s] : raw[key.to_sym] }
+      where = "hosts entry '#{name}'"
+      fields = {
+        api_key_env: value.call(:api_key_env).to_s.strip.then { |v| v.empty? ? nil : v },
+        # Kept as written; ModelProfile.resolve warns about an unknown one.
+        profile: value.call(:profile).to_s.strip.downcase.then { |v| v.empty? ? nil : v },
+        first_token_timeout: value.call(:first_token_timeout),
+        vision: ConfigFile.vision_flag(value.call(:vision), where),
+        remote: ConfigFile.bool_flag(value.call(:remote), where, "remote"),
+        window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
+        sampling: ConfigFile.sampling_map(value.call(:sampling), where),
+        thinking: Thinking.level(value.call(:thinking), where),
+        llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
+        llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),
+        models: HostModel.parse_map(value.call(:models), name),
+        llm_context_budget_tokens: LLMContextStrategy.parse_budget(value.call(LLMContextStrategy::BUDGET_KEY), where)
+      }
+      timeout = fields[:first_token_timeout]
+      unless timeout.nil? || (timeout.is_a?(Numeric) && !timeout.negative?)
+        ConfigFile.warn_once "Warning: #{where}: first_token_timeout must be seconds (0 = off); using the default"
+        fields[:first_token_timeout] = nil
+      end
+      api_key_env = fields[:api_key_env]
+      unless api_key_env.nil? || api_key_env.match?(ConfigFile::ENV_NAME_RE)
+        return invalid(name, "api_key_env must be an environment variable name")
+      end
+
+      location = parse_location(name, value) or return nil
+      kinds = parse_kinds(name, value.call(:transport), value.call(:api)) or return nil
+      new(name: name.downcase, **location, **kinds, **fields)
+    rescue StandardError => e
+      # One entry that trips a reader is dropped on its own, and said so;
+      # the other hosts stay (the worker's copy too).
+      invalid(name || raw_name, "#{e.class}: #{e.message}")
+    end
+
+    # A literal Hash of fields (specs and in-memory callers building a
+    # HostRegistry) as a HostConfig, unchecked; a HostConfig as it is.
+    # @param name [String] the entry's name
+    # @param cfg [HostConfig, Hash] symbol keys, as #to_h gives them
+    def self.coerce(name, cfg)
+      return cfg if cfg.is_a?(HostConfig)
+
+      new(**cfg.to_h.slice(*members), name: name.to_s.downcase)
+    end
+
+    # enabled: false (or "false", any case) in a hosts entry as written.
+    def self.disabled?(raw)
+      enabled = if raw.key?("enabled")
+                  raw["enabled"]
+                else
+                  (raw.key?(:enabled) ? raw[:enabled] : true)
+                end
+      enabled == false || enabled.to_s.strip.downcase == "false"
+    end
+
+    # host/port/scheme/url from url:, or from host: and port:; nil (warned)
+    # when they are wrong.
+    def self.parse_location(name, value)
+      host = value.call(:host)
+      port = value.call(:port)
+      url = value.call(:url).to_s.strip
+      scheme = "http"
+      unless url.empty?
+        return invalid(name, "give url or host/port, not both") unless host.to_s.strip.empty? && port.to_s.strip.empty?
+
+        uri = begin
+          URI.parse(url)
+        rescue URI::InvalidURIError
+          nil
+        end
+        return invalid(name, "url must be an http(s) URL") unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+        host = uri.host
+        port = uri.port
+        scheme = uri.scheme
+        url = url.chomp("/")
+      end
+      host = host.to_s.strip
+      return invalid(name, "host is required") if host.empty?
+
+      port = port.to_s.strip.empty? ? 8080 : port.to_i
+      return invalid(name, "invalid port") if port <= 0 || port > 65_535
+
+      { host: host, port: port, scheme: scheme, url: url.empty? ? nil : url }
+    end
+    private_class_method :parse_location
+
+    # transport: and api: as symbols; a raw-prompt api is also the
+    # transport. nil (warned) when unknown or contradicting each other.
+    def self.parse_kinds(name, transport, api)
+      transport = transport.to_s.strip.downcase
+      if transport.empty?
+        transport = nil
+      elsif !ConfigFile::VALID_TRANSPORTS_FOR_CONFIG.include?(transport)
+        return invalid(name, "unknown transport '#{transport}'")
+      end
+      api = api.to_s.strip.downcase
+      if api.empty?
+        api = nil
+      elsif !ConfigFile::VALID_APIS_FOR_CONFIG.include?(api)
+        return invalid(name, "unknown api '#{api}'")
+      elsif ConfigFile::VALID_TRANSPORTS_FOR_CONFIG.include?(api)
+        # A raw-prompt api is the transport; a different transport contradicts it.
+        return invalid(name, "api '#{api}' conflicts with transport '#{transport}'") if transport && transport != api
+
+        transport = api
+      end
+      { transport: transport&.to_sym, api: api&.to_sym }
+    end
+    private_class_method :parse_kinds
+
+    def self.invalid(name, reason)
+      ConfigFile.warn_once "Warning: ignoring hosts entry '#{name}': #{reason}"
+      nil
+    end
+    private_class_method :invalid
+
+    # The entry as a worker's SAMAGOTCHI_HOSTS_JSON carries it (string keys,
+    # unset fields left out); .parse(name, to_env_h) gives it back. A url
+    # entry travels as its url (host/port come from it); the API key stays
+    # in the environment, which workers inherit.
+    # @return [Hash{String => Object}]
+    def to_env_h
+      location = url ? { "url" => url } : { "host" => host, "port" => port }
+      location.merge("transport" => transport&.to_s, "api" => api&.to_s, "api_key_env" => api_key_env,
+                     "profile" => profile, "first_token_timeout" => first_token_timeout,
+                     "vision" => vision, "sampling" => sampling, "thinking" => thinking&.to_s,
+                     "remote" => remote, "window_tokens" => window_tokens,
+                     "llm_context_strategy" => llm_context_strategy&.map(&:to_s),
+                     "llm_context_apply" => llm_context_apply&.to_s,
+                     "llm_context_budget_tokens" => llm_context_budget_tokens,
+                     "models" => models_config).compact
+    end
+
+    private
+
+    # hosts.<name>.models as written back (HostModel#to_config), nil when none.
+    def models_config
+      models.values.to_h { |m| [m.id, m.to_config] } unless models.nil? || models.empty?
+    end
+  end
+end

data/lib/samagotchi/host_registry.rb

@@ -98,16 +98,11 @@ module Samagotchi
       raw = hosts_config || ConfigFile.hosts_config(env: env)
       @entries = {}
       raw.each do |key, cfg|
-        # cfg: {name:, host:, port:, transport:, original_name:}
-        transport = cfg[:transport]
-        entry = HostEntry.new(name: key.to_s.downcase, host: cfg[:host], port: cfg[:port].to_i, transport: transport,
-                              api: cfg[:api]&.to_sym, scheme: cfg[:scheme], url: cfg[:url], api_key_env: cfg[:api_key_env],
-                              profile: cfg[:profile], first_token_timeout: cfg[:first_token_timeout],
-                              vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking],
-                              remote: cfg[:remote], window_tokens: cfg[:window_tokens],
-                              llm_context_strategy: cfg[:llm_context_strategy], llm_context_apply: cfg[:llm_context_apply],
-                              llm_context_budget_tokens: cfg[:llm_context_budget_tokens], models: cfg[:models] || {})
-        entry.client = Client.new(host: cfg[:host], port: cfg[:port], transport: transport, scheme: cfg[:scheme],
+        cfg = HostConfig.coerce(key, cfg)
+        # Every HostConfig field is a HostEntry member (a new one must be added there too).
+        fields = cfg.to_h.merge(name: key.to_s.downcase, port: cfg.port.to_i, api: cfg.api&.to_sym, models: cfg.models || {})
+        entry = HostEntry.new(**fields)
+        entry.client = Client.new(host: cfg.host, port: cfg.port, transport: cfg.transport, scheme: cfg.scheme,
                                   first_token_timeout: entry.first_token_limit, name: entry.name,
                                   api_key_env: entry.api_key_env, env: env)
         @entries[entry.name] = entry
@@ -200,9 +195,11 @@ module Samagotchi
     # id it is sent as (ModelRef: one alias pass). A ref that names a host
     # goes there. A bare id goes to the hosts whose cached list has it or
     # that declare it (hosts.<name>.models, known before any /models): the
-    # default host when it is one of them, else the first in hosts: order,
-    # else the default host (before /models nothing is listed: no
-    # discovery here, the latency budget). Never by a substring.
+    # default host when it is one of them, else the first in hosts: order.
+    # When none does, the hosts whose saved list (ModelListStore, another
+    # process's listing: a worker spawned with --model never lists) has
+    # it, the same way; else the default host (no discovery here, the
+    # latency budget). Never by a substring.
     def host_for_model(raw_model)
       ref = model_ref(raw_model)
       # ModelRef names a host only when it is one of ours
@@ -211,6 +208,7 @@ module Samagotchi
       down = ref.id.to_s.strip.downcase
       listed = @mutex.synchronize { @model_index }&.fetch(down, nil) || []
       candidates = @entries.values.select { |e| listed.include?(e.name) || e.models&.key?(down) }.map(&:name)
+      candidates = saved_hosts_for(down) if candidates.empty?
       default = default_entry
       name = candidates.include?(default.name) ? default.name : candidates.first
       [(name && find_entry(name)) || default, ref.id]
@@ -386,6 +384,16 @@ module Samagotchi
       ModelListStore.save(name, Array(models).map(&:id), env: @env)
     end
 
+    # The configured hosts, in hosts: order, whose fresh saved list
+    # (ModelListStore) has +down+ (a downcased id). The store never raises.
+    def saved_hosts_for(down)
+      saved = ModelListStore.read(env: @env)
+      @entries.each_key.select do |name|
+        list = saved[name]
+        list && !list.stale? && list.known?(down)
+      end
+    end
+
     def fresh_list(name, entry)
       @mutex.synchronize do
         cached = @host_lists[name]

data/lib/samagotchi/kernel_loop.rb

@@ -952,11 +952,30 @@ module Samagotchi
 
     private
 
+    # Shell-like names (the harness's is `execute`). The unknown-tool error
+    # never echoes the name the model used — a model that sees its own wrong
+    # name again calls it again (a steer that named `bash` raised one model's
+    # bash rate from 9% to 30%); the activity event and the logs keep it.
+    SHELL_LIKE_TOOL_NAMES = %w[
+      bash sh zsh shell terminal cmd command run run_command run_shell exec execute_command
+    ].freeze
+
+    # The error an unknown tool name gets back. A shell-like name with
+    # `execute` offered this turn points at `execute`; every other unknown
+    # name lists what is offered. Neither echoes the wrong name.
+    def unknown_tool_error(name, layers)
+      names = @tools.names(layers: layers)
+      if SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
+        "Error: no such tool. Shell commands run with `execute` (same arguments)."
+      else
+        "Error: no such tool. Available: #{names.join(", ")}"
+      end
+    end
+
     def dispatch(call)
       entry = @tools.offered(call[:name], layers: llm_context_layers)
       unless entry
-        available = @tools.names(layers: llm_context_layers).join(", ")
-        result = "Error: unknown tool '#{call[:name]}'. Available: #{available}"
+        result = unknown_tool_error(call[:name], llm_context_layers)
         return {
           output: result,
           activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)
@@ -965,6 +984,13 @@ module Samagotchi
 
       dump_log("tool_call", call[:content], tool: call[:name], path: call[:path], scope: call[:scope])
 
+      if call[:called_as]
+        # The model's spelling for a tool an alias ran (bash → execute); its
+        # rate is what the alias exists for, so it goes in the log. Tag :turn
+        # like the other per-call tool logs (there is no :tool tag).
+        Log.info(:turn, "tool_alias", name: call[:called_as], as: call[:name])
+      end
+
       result = entry.handler.call(call, tool_context)
 
       dump_log("tool_result", result, tool: call[:name])

data/lib/samagotchi/last_turn.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # How a session's last turn ended (Session#last_turn), saved as
+  # session.json's "last_turn" and sent in the web's session summary.
+  # Engine#record_last_turn writes it at every turn's end, ContinueOffer
+  # when a Stop answered the step-limit question (no turn ran).
+  #
+  # outcome: "completed", "failed", "canceled" or "not_continued";
+  # ended_at: iso8601; seconds: Float; origin: "client", "reminder",
+  # "delegate", "delegate_report" (a turn a parent ran for its delegate
+  # children's reports) or "context" (one an attached context source's
+  # change started); exhausted/limit: the turn ran out of iterations at
+  # limit. The rest are its stop facts (LastTurn::STOP_FACTS), only what is
+  # known. A field may be nil (unset; left out of the file).
+  LastTurn = Data.define(:outcome, :ended_at, :seconds, :origin, :exhausted, :limit,
+                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by) do
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A saved record (string keys; symbol keys read too, a key we don't
+    # know dropped), a LastTurn as it is; nil for anything else.
+    # @return [LastTurn, nil]
+    def self.from_file(raw)
+      return raw if raw.is_a?(LastTurn)
+      return nil unless raw.is_a?(Hash)
+
+      new(**members.to_h { |m| [m, raw.key?(m.to_s) ? raw[m.to_s] : raw[m]] })
+    end
+
+    # The session file's record: string keys, in member order, unset
+    # fields left out.
+    # @return [Hash{String => Object}]
+    def to_file = to_h.compact.transform_keys(&:to_s)
+
+    # The stop facts this turn has (LastTurn::STOP_FACTS), symbol keys.
+    # @return [Hash{Symbol => Object}]
+    def stop_facts = to_h.slice(*self.class::STOP_FACTS).compact
+  end
+
+  # Why a turn stopped, for a parent agent's wait (ReplyWait::Result takes
+  # them by these names): a failed turn's provider error kind, whether a
+  # retry may help and whether its work stayed (kept_steps: a parent must
+  # not send the task again); a canceled one's reason and the hook that
+  # stopped it.
+  LastTurn::STOP_FACTS = %i[error_kind retryable kept_steps cancel_reason stopped_by].freeze
+end

data/lib/samagotchi/live_versions.rb

@@ -36,12 +36,6 @@ module Samagotchi
       workers(state_dir: state_dir).reject { |w| w.version == version }
     end
 
-    # The version a chi web on host:port runs, or nil when nothing (or not
-    # chi web) answers.
-    def web_version(host, port, timeout: WEB_TIMEOUT)
-      web_info(host, port, timeout: timeout)&.fetch("version", nil).to_s.then { |v| v.empty? ? nil : v }
-    end
-
     # The /api/info of a chi web on host:port, or nil when nothing (or not
     # chi web) answers.
     def web_info(host, port, timeout: WEB_TIMEOUT)

data/lib/samagotchi/llm/native_tool_normalizer.rb

@@ -11,8 +11,8 @@ module Samagotchi
     # the call, as it does for the Gemma and Qwen parsers.
     #
     # Unknown tool names pass through with their arguments on args:, so
-    # `dispatch` renders its standard "unknown tool … available: …" error —
-    # the loop feeds that back like any tool result.
+    # `dispatch` renders its standard "no such tool …" error (which never
+    # echoes the name) — the loop feeds that back like any tool result.
     class NativeToolNormalizer
       class << self
         # Map a single native tool call (LLM::ToolCall) to the internal call hash.
@@ -26,11 +26,6 @@ module Samagotchi
           Tools::BuiltinCalls.build(call.name.to_s, args_for(call))
         end
 
-        # Map an Array of tool calls to internal call hashes (nils dropped).
-        def normalize_all(calls)
-          Array(calls).map { |call| normalize(call) }.compact
-        end
-
         private
 
         # args_for: arguments is normally a Hash. Defensively handle nil /

data/lib/samagotchi/llm_context_override.rb

@@ -48,7 +48,6 @@ module Samagotchi
     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.
@@ -111,7 +110,7 @@ module Samagotchi
     end
 
     def self.file_budget(raw)
-      raw.is_a?(Integer) ? check_budget(raw) : nil
+      raw.is_a?(Integer) ? LLMContextStrategy.check_budget(raw) : nil
     end
 
     # +current+ with +words+ (field => what the user typed) applied: each
@@ -153,27 +152,9 @@ module Samagotchi
       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).
+    # "64000", "64k" or "off" (0): LLMContextStrategy.budget_tokens.
     # @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
+    def self.parse_budget_tokens(text) = LLMContextStrategy.budget_tokens(text)
 
     private_class_method :file_value, :file_strategy, :file_budget
   end

data/lib/samagotchi/llm_context_strategy.rb

@@ -23,7 +23,7 @@ module Samagotchi
   # (false: edit-driven stale stubs are opt-in, experimental) are global only.
   #
   # A soft context budget, llm_context.budget_tokens, and per model or host
-  # the flat key llm_context_budget_tokens (a positive number of tokens),
+  # the flat key llm_context_budget_tokens (tokens or k, 4k to 10M, or off),
   # resolved as the apply rule is, each on its own: off (nil) by default.
   # When set, ContextStatus counts its bands against it instead of the
   # window (the smaller of the two), so the forget layer's offers come
@@ -103,21 +103,52 @@ module Samagotchi
       DEFAULT_APPLY
     end
 
-    # +raw+ as written, a context budget in tokens; nil for unset or 0
-    # (off). Anything but a number of tokens warns, naming +where+, and is
-    # unset.
+    # +raw+ as written in config (llm_context.budget_tokens, a models: or
+    # hosts: entry's llm_context_budget_tokens), read as /llm-context
+    # budget reads it (.budget_tokens); nil for unset, 0 or off. Anything
+    # else warns, naming +where+, and is unset.
     # @return [Integer, nil]
     def parse_budget(raw, where)
       return nil if raw.nil? || raw.to_s.strip.empty?
 
-      tokens = Integer(raw.to_s.strip, exception: false)
-      return nil if tokens&.zero?
-      return tokens if tokens&.positive?
-
-      warn_once "Warning: #{where}: llm_context budget_tokens must be a positive number of tokens; ignored"
+      tokens = budget_tokens(raw)
+      tokens.zero? ? nil : tokens
+    rescue ArgumentError => e
+      warn_once "Warning: #{where}: #{e.message}; ignored"
       nil
     end
 
+    # The smallest and largest budget a session or the config may set.
+    MIN_BUDGET = 4_000
+    MAX_BUDGET = 10_000_000
+    BUDGET_OFF_WORDS = %w[off 0].freeze
+
+    # A budget in tokens: an Integer, "64000", "64_000", "64k", or "off"
+    # (0); the one grammar for /llm-context budget, chi
+    # --llm-context-budget and the config.
+    # @return [Integer] 0 for off
+    # @raise [ArgumentError] not a budget, or one out of MIN_BUDGET..MAX_BUDGET
+    def budget_tokens(raw)
+      return check_budget(raw) if raw.is_a?(Integer)
+
+      text = raw.to_s.strip
+      return 0 if BUDGET_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.
+    # @return [Integer]
+    # @raise [ArgumentError]
+    def 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
+
     # Where one value came from: :session, :model_setting, :host_setting
     # or :config, and the place as a warning names it ("the session",
     # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
@@ -143,7 +174,7 @@ module Samagotchi
     # The strategy for +target+'s turn.
     # @param target [HostRegistry::ModelTarget, nil]
     # @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)
     # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
     # @param session_apply [Symbol, nil] the session's own apply rule
     # @param session_budget [Integer, nil] the session's own budget (0: off)
@@ -210,8 +241,9 @@ module Samagotchi
     def budget_for(target, names, models, session_budget)
       return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
 
-      key, budget = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)
-      return [budget, Origin.new(source: :model_setting, where: "models: #{key}")] if budget
+      if (setting = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       budget = target&.entry&.llm_context_budget_tokens
       return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
@@ -222,8 +254,9 @@ module Samagotchi
     def layers_for(target, names, models, session)
       return [session, :session, SESSION_ORIGIN.where] if session
 
-      key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
-      return [layers, :model_setting, "models: #{key}"] if layers
+      if (setting = ConfigFile.model_setting(names, :llm_context_strategy, models: models))
+        return [setting.value, :model_setting, "models: #{setting.key}"]
+      end
 
       layers = target&.entry&.llm_context_strategy
       return [layers, :host_setting, "hosts entry '#{target.entry.name}'"] if layers
@@ -235,8 +268,9 @@ module Samagotchi
     def apply_for(target, names, models, session_apply)
       return [session_apply, SESSION_ORIGIN] if session_apply
 
-      key, apply = ConfigFile.model_setting(names, :llm_context_apply, models: models)
-      return [apply, Origin.new(source: :model_setting, where: "models: #{key}")] if apply
+      if (setting = ConfigFile.model_setting(names, :llm_context_apply, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       apply = target&.entry&.llm_context_apply
       return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply

data/lib/samagotchi/memory_bundle/placeholder.rb

@@ -18,11 +18,6 @@ module Samagotchi
         new(content: content).placeholders
       end
 
-      # Returns a sorted list of unique placeholder names found.
-      def unique_names
-        @placeholders.map(&:strip).uniq.sort
-      end
-
       def any?
         !@placeholders.empty?
       end

data/lib/samagotchi/model_profile.rb

@@ -227,7 +227,7 @@ module Samagotchi
       host = parsed.host_name
       return nil unless host
       # Declared under hosts.<name>.models: served whatever the host lists.
-      return nil if hosts[host.to_s.strip.downcase]&.dig(:models)&.key?(parsed.id.to_s.strip.downcase)
+      return nil if hosts[host.to_s.strip.downcase]&.models&.key?(parsed.id.to_s.strip.downcase)
 
       list = lists.read(env: env)[host.to_s.strip.downcase]
       return nil if list.nil? || list.stale? || list.known?(parsed.id)
@@ -433,10 +433,10 @@ module Samagotchi
       end
 
       names.map(&:downcase).uniq.each do |key|
-        setting = models[key]
-        next unless setting && setting[:profile]
+        configured_profile = models[key]&.profile
+        next unless configured_profile
 
-        profile = configured(setting[:profile], "models: #{key}")
+        profile = configured(configured_profile, "models: #{key}")
         return Resolution.new(profile: profile, source: :config, detail: "models: #{key}", retry: false) if profile
       end
 

data/lib/samagotchi/model_settings.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # One config.yml models: entry (per-model settings keyed by model id or
+  # alias), parsed and checked; ConfigFile.model_settings holds them by
+  # downcased key. Each field is nil when unset: profile kept as written
+  # (downcased; ModelProfile.resolve validates it), vision true/false,
+  # sampling a request-field map, thinking a level, window_tokens, and the
+  # LLM context strategy, apply rule and budget (LLMContextStrategy). The
+  # same per-model fields a hosts: entry carries (HostConfig).
+  ModelSettings = Data.define(:profile, :vision, :sampling, :thinking, :window_tokens,
+                              :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens) do
+    # Every field may be left out (nil).
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A models: entry as written, or nil when it is not a map (or the key is
+    # blank). A bad value warns, naming the entry, and is left unset.
+    # @param key [String] the downcased model id or alias
+    # @param raw [Hash] string or symbol keys
+    # @return [ModelSettings, nil]
+    def self.parse(key, raw)
+      return nil if key.to_s.empty? || !raw.is_a?(Hash)
+
+      value = ->(name) { raw.key?(name.to_s) ? raw[name.to_s] : raw[name.to_sym] }
+      where = "models: #{key}"
+      profile = value.call(:profile).to_s.strip.downcase
+      new(profile: profile.empty? ? nil : profile,
+          vision: ConfigFile.vision_flag(value.call(:vision), where),
+          sampling: ConfigFile.sampling_map(value.call(:sampling), where),
+          thinking: Thinking.level(value.call(:thinking), where),
+          window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
+          llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
+          llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),
+          llm_context_budget_tokens: LLMContextStrategy.parse_budget(value.call(LLMContextStrategy::BUDGET_KEY), where))
+    end
+  end
+
+  # One field ConfigFile.model_setting found: the models: key that set it
+  # and its value.
+  ModelSetting = Data.define(:key, :value)
+end

data/lib/samagotchi/plugin/context.rb

@@ -20,15 +20,15 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ (the session's resolved model ref, live after /model) and
-    # +state_dir+ are what ctx.sessions forks with, and +llm_context+ (the
-    # session's own LLMContextOverride, nil without one), which a fork copies; +model_key+ is the
+    # +state_dir+ are what ctx.sessions forks with, and +setup+ (the
+    # session's own SessionSetup), which a fork copies; +model_key+ is the
     # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     # +frontend+ returns the Engine's interface (:repl, :worker,
     # :non_interactive), which ctx.frontend names for plugins.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :llm_context, :steer, :stop_turn, :stop_generation,
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :steer, :stop_turn, :stop_generation,
                       :frontend, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or