samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/config.rb

@@ -8,6 +8,9 @@ require "set"
 require_relative "log"
 
 module Samagotchi
+  # Parses the thinking: levels of host and model entries (it needs Config).
+  autoload :Thinking, File.expand_path("thinking", __dir__)
+
   # Unified configuration registry implementing the implicit convention:
   #   ENV    SAMAGOTCHI_ATTR            (UPPER + prefix + _ = nesting)
   #   YAML   attr: / nested: {param:}   (lower snake, dot = nesting, Option A leaf keeps _)
@@ -22,7 +25,7 @@ module Samagotchi
   # handled by ConfigFile (same file, below), which reads the *same* parsed YAML
   # through ConfigFile.read_yaml so the file is parsed once per change.
   module Config
-    Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :aliases, :yaml_aliases, keyword_init: true) do
+    Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :yaml_aliases, keyword_init: true) do
       def env_key
         "SAMAGOTCHI_" + yaml_path.map { |p| p.upcase }.join("_")
       end
@@ -116,9 +119,13 @@ module Samagotchi
       Entry.new(key: "context.status_cadence",   yaml_path: %w[context status_cadence],   type: :integer, default: 0,               expose: %i[env config cli]),
 
       Entry.new(key: "thinking.ui",              yaml_path: %w[thinking ui],              type: :string, default: nil,              expose: %i[env config cli]),
-      Entry.new(key: "thinking.preview_lines",   yaml_path: %w[thinking preview_lines],   type: :integer, default: 1,               expose: %i[env config cli]),
       Entry.new(key: "thinking.render_interval", yaml_path: %w[thinking render_interval], type: :float,   default: 0.08,            expose: %i[env config cli]),
       Entry.new(key: "thinking.turn_preamble",   yaml_path: %w[thinking turn_preamble],   type: :bool,   default: true,             expose: %i[env config cli]),
+      # How much models think: off|low|medium|high|default, parsed by Thinking
+      # (a :string, since YAML reads an unquoted off as false). The CLI flag
+      # is bin/chi's own --thinking; models: and hosts: entries rank below
+      # the flag and the env, above config.yml's value.
+      Entry.new(key: "thinking.level",           yaml_path: %w[thinking level],           type: :string, default: "default",       expose: %i[env config]),
 
       Entry.new(key: "default.n_predict",        yaml_path: %w[default n_predict],        type: :integer, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli]),
@@ -126,6 +133,13 @@ module Samagotchi
       Entry.new(key: "retry.max",                yaml_path: %w[retry max],                type: :integer, default: 5,               expose: %i[env config cli]),
       Entry.new(key: "retry.base_delay",         yaml_path: %w[retry base_delay],         type: :float,   default: 0.5,             expose: %i[env config cli]),
       Entry.new(key: "retry.max_delay",          yaml_path: %w[retry max_delay],          type: :float,   default: 8.0,             expose: %i[env config cli]),
+      # Asks again in the same turn after an empty answer (EmptyAnswerRetry);
+      # 0 = off, capped at 3. No CLI flag: workers get no CLI args.
+      Entry.new(key: "retry.empty_answer",       yaml_path: %w[retry empty_answer],       type: :integer, default: 1,               expose: %i[env config]),
+      # What `chi update` touches; its --no-gem/--no-bundles/--no-desktop turn one off for a run.
+      Entry.new(key: "update.gem",               yaml_path: %w[update gem],               type: :bool,    default: true,            expose: %i[env config]),
+      Entry.new(key: "update.bundles",           yaml_path: %w[update bundles],           type: :bool,    default: true,            expose: %i[env config]),
+      Entry.new(key: "update.desktop",           yaml_path: %w[update desktop],           type: :bool,    default: true,            expose: %i[env config]),
 
       Entry.new(key: "read.truncate_at_bytes",        yaml_path: %w[read truncate_at_bytes],        type: :integer, default: 65_536,   expose: %i[env config cli]),
       Entry.new(key: "read.preview_bytes",            yaml_path: %w[read preview_bytes],            type: :integer, default: 12_288,   expose: %i[env config cli]),
@@ -141,6 +155,8 @@ module Samagotchi
       Entry.new(key: "web.markdown",             yaml_path: %w[web markdown],             type: :bool,    default: false,           expose: %i[env config cli]),
       # The page shows each turn as one block of generations (the live one at the bottom); false brings back the row of bubbles; ?view=turn|chat overrides it per page load.
       Entry.new(key: "web.turn_view",            yaml_path: %w[web turn_view],            type: :bool,    default: true,           expose: %i[env config cli]),
+      # Quick replies next to Annotate in the page's selection bubble, "|"-separated (a YAML list works too); "" leaves only Annotate.
+      Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli]),
 
       Entry.new(key: "no_interrupt",             yaml_path: %w[no_interrupt],             type: :bool,   default: false,            expose: %i[env config cli]),
       Entry.new(key: "no_default_input",         yaml_path: %w[no_default_input],         type: :bool,   default: false,            expose: %i[env config cli]),
@@ -149,18 +165,34 @@ module Samagotchi
       Entry.new(key: "default.input",            yaml_path: %w[default input],            type: :string, default: nil,              expose: %i[env config]),
       Entry.new(key: "history.file",             yaml_path: %w[history file],             type: :string, default: nil,              expose: %i[env config]),
       Entry.new(key: "skip_agent_md",            yaml_path: %w[skip_agent_md],            type: :bool,   default: false,            expose: %i[env config]),
-      Entry.new(key: "bridge.enable",            yaml_path: %w[bridge enable],            type: :bool,   default: false,            expose: %i[env config]),
     ].freeze
 
+    # Top-level maps read by their own code, whose entry names and contents
+    # are the user's: ConfigFile.model_aliases / preloaded_memories,
+    # Hooks::Loader, Engine#read_bundle_settings.
+    FREE_FORM_MAPS = %w[model_aliases hooks bundles memories].freeze
+    # Maps of named entries and the keys an entry may hold
+    # (ConfigFile.hosts_config, ConfigFile.model_settings).
+    MAP_ENTRY_KEYS = {
+      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking enabled].freeze,
+      "models" => %w[profile vision sampling thinking].freeze
+    }.freeze
+    # Section keys beyond the registry's: guardrails' YAML rules (Engine#guardrail_rules).
+    SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze }.freeze
+    # Removed settings that warn on their own (Engine.warn_removed_backend_setting).
+    REMOVED_KEYS = %w[backend].freeze
+
     # Fast lookup maps
     BY_KEY = ENTRIES.each_with_object({}) { |e, h| h[e.key] = e }.freeze
-    BY_ENV = ENTRIES.each_with_object({}) do |e, h|
-      h[e.env_key] = e
-      Array(e.aliases).each { |a| h[a] = e }
-    end.freeze
-    BY_CLI = ENTRIES.each_with_object({}) { |e, h| h[e.cli_flag] = e if e.cli_exposed? }.freeze
+    BY_ENV = ENTRIES.each_with_object({}) { |e, h| h[e.env_key] = e }.freeze
 
     class << self
+      # The +candidates+ within edit distance 2 of +probe+, closest first
+      # (the "did you mean" of an unknown key or host).
+      def near_names(probe, candidates)
+        candidates.uniq.map { |c| [levenshtein(probe, c), c] }.select { |d, _| d <= 2 }.sort.map(&:last)
+      end
+
       def find_by_key(key)
         BY_KEY[key.to_s]
       end
@@ -169,10 +201,6 @@ module Samagotchi
         BY_ENV[env_key.to_s]
       end
 
-      def find_by_cli(flag)
-        BY_CLI[flag.to_s]
-      end
-
       def all_entries
         ENTRIES
       end
@@ -186,7 +214,8 @@ module Samagotchi
         return nil if raw.nil?
         # For string, preserve as-is (including trailing spaces like "Please ")
         if entry.type == :string
-          str = raw.to_s
+          # A YAML list for a "|"-separated setting (web.annotate_presets).
+          str = raw.is_a?(Array) ? raw.join("|") : raw.to_s
           return nil if str.empty? && entry.type != :string
           return str
         end
@@ -286,21 +315,31 @@ module Samagotchi
         end
       end
 
-      # Lookup yaml_path in nested hash, accepting snake leaf, kebab alias,
-      # entry-specific yaml_aliases, and legacy flat UPPER keys (e.g.,
-      # SAMAGOTCHI_DEFAULT_MODEL) for transition.
+      # Lookup yaml_path in nested hash, accepting snake leaf, kebab alias and
+      # entry-specific yaml_aliases, then legacy flat UPPER keys (e.g.,
+      # SAMAGOTCHI_DEFAULT_MODEL) for transition: the nested key wins when a
+      # file has both (ConfigFile.load_global_env! warns about that).
       def lookup_yaml(data, yaml_path)
         entry = ENTRIES.find { |e| e.yaml_path == yaml_path }
-        # Legacy flat top-level fallback (transition): e.g., file contains SAMAGOTCHI_DEFAULT_MODEL
-        if entry && data.is_a?(Hash)
-          if data.key?(entry.env_key)
-            return data[entry.env_key]
-          end
-          Array(entry.aliases).each do |a|
-            return data[a] if data.key?(a)
-            return data[a.to_sym] if data.key?(a.to_sym)
-          end
-        end
+        nested = lookup_nested(data, yaml_path, entry)
+        return nested unless nested.nil?
+
+        lookup_legacy(data, entry)
+      end
+
+      # The legacy flat key's value for +entry+, or nil.
+      def lookup_legacy(data, entry)
+        return nil unless entry && data.is_a?(Hash)
+
+        key = entry.env_key
+        return data[key] if data.key?(key)
+        return data[key.to_sym] if data.key?(key.to_sym)
+
+        nil
+      end
+
+      # The nested key's value for +yaml_path+, or nil.
+      def lookup_nested(data, yaml_path, entry = nil)
         cur = data
         yaml_path.each_with_index do |seg, idx|
           return nil unless cur.is_a?(Hash)
@@ -363,6 +402,16 @@ module Samagotchi
         get_with_origin(key).first
       end
 
+      # A timeout setting (server.open_timeout, server.read_timeout) in
+      # seconds, +given+ (a caller's own value) first; one that isn't
+      # positive (0, a word) is the key's default, on every kind of host.
+      def positive_seconds(key, given = nil)
+        value = (given.nil? ? get(key) : given).to_i
+        value.positive? ? value : find_by_key(key).default
+      rescue StandardError
+        find_by_key(key)&.default
+      end
+
       # [value, origin] for the live value #get returns; origin is one of
       # :cli, :env, :file, :default.
       def get_with_origin(key)
@@ -380,26 +429,98 @@ module Samagotchi
         reload!(cli_overrides: overrides)
       end
 
-      # Validation for top-level sections
+      # Problems with the keys of a parsed config.yml, one message per key the
+      # code doesn't read (with a "did you mean" when a known key is close).
+      # Every config-exposed entry in ENTRIES is known as written; names under
+      # the maps are the user's, and host/model entries may hold the keys
+      # their readers take. Legacy flat keys warn in ConfigFile.load_global_env!.
       def validate_yaml_sections(data)
         return [] unless data.is_a?(Hash)
-        errors = []
-        # Legacy flat UPPER keys are handled separately — don't flag them here
-        legacy_keys = BY_ENV.keys
-        data.each_key do |k|
-          next if %w[hosts hooks model_aliases models guardrails bundles].include?(k.to_s)
-          next if legacy_keys.include?(k.to_s)
-          # Sections are top-level keys that map to hashes (e.g., default, recap)
-          # If key contains _ or -, suggest dotted form
-          if k.to_s.include?("_")
-            errors << "top-level key '#{k}' contains '_' — use nested form '#{k.to_s.tr('_', '.')}' (e.g., default.model)"
+
+        data.flat_map do |key, value|
+          key = key.to_s
+          if find_by_env(key)&.config_exposed? || FREE_FORM_MAPS.include?(key) || REMOVED_KEYS.include?(key)
+            []
+          elsif MAP_ENTRY_KEYS.key?(key)
+            map_entry_problems(key, value)
+          elsif value.is_a?(Hash) && (known_sections.include?(key) || ENTRIES.any? { |e| e.yaml_path.size > 1 && e.section == key })
+            value.keys.filter_map { |leaf| key_problem("#{key}.#{leaf}") }
+          elsif known_sections.include?(key)
+            # An all-commented section is nil; recap: false turns recaps off.
+            value.nil? || (key == "recap" && value == false) ? [] : ["config: '#{key}' must be a mapping of settings; ignored"]
+          else
+            [key_problem(key)].compact
           end
-          # Check section name shape if its value is a Hash
-          if data[k].is_a?(Hash) && k.to_s.match?(/[_-]/)
-            errors << "section '#{k}' must match #{SECTION_RE.inspect} (no _ or -)"
+        end
+      end
+
+      # Dotted keys config.yml may set: config-exposed entries (snake and kebab
+      # leaf, yaml_aliases), the extra section keys and the map names.
+      def known_config_keys
+        @known_config_keys ||= ENTRIES.select(&:config_exposed?).flat_map do |entry|
+          *section, leaf = entry.yaml_path
+          [leaf, leaf.tr("_", "-"), *Array(entry.yaml_aliases)].map { |l| [*section, l].join(".") }
+        end.to_set.merge(SECTION_EXTRA_KEYS.flat_map { |s, leaves| leaves.map { |l| "#{s}.#{l}" } })
+                                .merge(FREE_FORM_MAPS).merge(MAP_ENTRY_KEYS.keys).freeze
+      end
+
+      private
+
+      def known_sections
+        @known_sections ||= known_config_keys.filter_map { |k| k.split(".").first if k.include?(".") }.to_set.freeze
+      end
+
+      # nil when +dotted+ is a key the file may hold.
+      def key_problem(dotted)
+        return nil if known_config_keys.include?(dotted)
+
+        entry = find_by_key(dotted) || find_by_env(dotted)
+        if entry
+          where = entry.cli_exposed? ? "#{entry.env_key} or #{entry.cli_flag}" : entry.env_key
+          return "config: '#{dotted}' can't be set in config.yml; use #{where}"
+        end
+
+        canonical = ENTRIES.select(&:config_exposed?).map(&:key) + known_sections.to_a +
+                    SECTION_EXTRA_KEYS.flat_map { |s, leaves| leaves.map { |l| "#{s}.#{l}" } } + FREE_FORM_MAPS + MAP_ENTRY_KEYS.keys
+        # A legacy-looking flat key compares by its nested form.
+        probe = dotted.start_with?("SAMAGOTCHI_") ? dotted.delete_prefix("SAMAGOTCHI_").downcase : dotted
+        unknown_key_message(dotted, probe, canonical)
+      end
+
+      def map_entry_problems(map, value)
+        return [] unless value.is_a?(Hash)
+
+        allowed = MAP_ENTRY_KEYS.fetch(map)
+        value.flat_map do |name, entry|
+          next [] unless entry.is_a?(Hash)
+
+          (entry.keys.map(&:to_s) - allowed).map do |k|
+            unknown_key_message("#{map}.#{name}.#{k}", k, allowed, prefix: "#{map}.#{name}.")
+          end
+        end
+      end
+
+      # "config: unknown key 'x'", with a "did you mean" naming the candidates
+      # within edit distance 2 of +probe+ (closest first) and the ones that
+      # share its last segment, at most three.
+      def unknown_key_message(key, probe, candidates, prefix: "")
+        candidates = candidates.uniq
+        near = near_names(probe, candidates)
+        close = (near + candidates.select { |c| c.split(".").last == probe.split(".").last }).uniq.first(3)
+        hint = close.empty? ? "" : " (did you mean #{close.map { |c| "'#{prefix}#{c}'" }.join(' or ')}?)"
+        "config: unknown key '#{key}'#{hint}"
+      end
+
+      def levenshtein(a, b)
+        prev = (0..b.size).to_a
+        a.each_char.with_index(1) do |ca, i|
+          cur = [i]
+          b.each_char.with_index(1) do |cb, j|
+            cur << [prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (ca == cb ? 0 : 1)].min
           end
+          prev = cur
         end
-        errors
+        prev.last
       end
     end
   end
@@ -467,6 +588,43 @@ module Samagotchi
       nil
     end
 
+    # Request keys chi sets itself; a `sampling:` map can't override them.
+    # (Length caps would need their own semantics.)
+    SAMPLING_RESERVED_KEYS = %w[model messages prompt stream stream_options tools tool_choice stop n_predict
+                                max_tokens n parallel_tool_calls response_format cache_prompt].freeze
+
+    # A `sampling:` setting (hosts entry or models: entry): request parameters
+    # passed through to the provider as written (keys symbolized, nested maps
+    # too, so e.g. chat_template_kwargs works). A null value means "don't
+    # send it" (drops chi's own temperature default). Not a map: warns once,
+    # nil. Reserved keys warn once and are dropped. nil when nothing is left.
+    def sampling_map(value, where)
+      return nil if value.nil?
+      unless value.is_a?(Hash)
+        warn_once "Warning: #{where}: sampling must be a map of request parameters; ignored"
+        return nil
+      end
+
+      result = value.each_with_object({}) do |(raw_key, raw_value), acc|
+        key = raw_key.to_s.strip
+        next if key.empty?
+        if SAMPLING_RESERVED_KEYS.include?(key)
+          warn_once "Warning: #{where}: sampling.#{key} is set by chi; ignored"
+          next
+        end
+        acc[key.to_sym] = deep_symbolize(raw_value)
+      end
+      result.empty? ? nil : result.freeze
+    end
+
+    def deep_symbolize(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s.to_sym, deep_symbolize(v)] }.freeze
+      when Array then value.map { |v| deep_symbolize(v) }.freeze
+      else value
+      end
+    end
+
     # Forget the warnings already printed (specs).
     def reset_warnings!
       @warned = nil
@@ -492,11 +650,18 @@ module Samagotchi
       existed = File.file?(path)
       raw = read_yaml(env: env, path: path) || {}
       if existed
-        Samagotchi::Config.validate_yaml_sections(raw).each { |w| Log.warn(:config, "invalid_section", echo: "Warning: #{w}") }
-        # Warn on legacy UPPER keys
+        Samagotchi::Config.validate_yaml_sections(raw).each { |w| Log.warn(:config, "config_key", echo: "Warning: #{w}") }
+        # Warn on legacy UPPER keys; the nested key wins when both are set.
+        # Any other flat key is unknown to validate_yaml_sections.
         raw.each_key do |k|
-          if k.to_s.match?(/\A[A-Z_]{2,}\z/) && k.to_s.start_with?("SAMAGOTCHI_")
-            Log.warn(:config, "legacy_key", echo: "Warning: config key '#{k}' is legacy UPPER — use '#{k.to_s.downcase.sub(/^samagotchi_/, '').tr('_', '.')}' (e.g., default.model)", key: k.to_s)
+          entry = Samagotchi::Config.find_by_env(k)
+          next unless entry&.config_exposed?
+
+          if !Samagotchi::Config.lookup_nested(raw, entry.yaml_path, entry).nil?
+            nested = entry.yaml_path.join(".")
+            Log.warn(:config, "legacy_key", echo: "Warning: config: both '#{k}' and '#{nested}' are set; using '#{nested}', remove the flat key", key: k.to_s)
+          else
+            Log.warn(:config, "legacy_key", echo: "Warning: config key '#{k}' is legacy UPPER — use '#{entry.yaml_path.join('.')}'", key: k.to_s)
           end
         end
       end
@@ -507,10 +672,11 @@ module Samagotchi
       # avoid polluting ENV with defaults.
       Samagotchi::Config.all_entries.each do |entry|
         next unless entry.env_exposed?
+        # The env's thinking.level outranks models:/hosts: levels, the file's doesn't (Thinking.resolve).
+        next if entry.key == "thinking.level"
         # check if file actually contained this key (including legacy flat)
         file_val = Samagotchi::Config.lookup_yaml(raw, entry.yaml_path)
         file_val ||= raw[entry.env_key] if raw.key?(entry.env_key)
-        Array(entry.aliases).each { |a| file_val ||= raw[a] if raw.key?(a) }
         next if file_val.nil?
         val = Samagotchi::Config.store[entry.key]
         next if val.nil?
@@ -580,6 +746,8 @@ module Samagotchi
           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}'")
+          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}'")
           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
@@ -643,7 +811,7 @@ module Samagotchi
                                   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 }
+                                  vision: vision, sampling: sampling, thinking: thinking }
         end
       end
 
@@ -734,6 +902,26 @@ module Samagotchi
       [nil, value]
     end
 
+    # Hosted providers' names, which no local model family uses: as a
+    # prefix they always mean a host ("openai:gpt-4o"). "mistral" and
+    # "deepseek" are left out: Ollama has mistral:7b and deepseek-* tags.
+    PROVIDER_HOST_NAMES = %w[openrouter openai anthropic google gemini groq xai together fireworks].freeze
+
+    # The host a model ref names when that host isn't configured, or nil.
+    # A ':' in a model id is often a tag (qwen3:8b, org/model:Q4_K_M), so
+    # the prefix counts as a host only when it could be a host name and
+    # either the rest looks like a hosted provider's org/model id
+    # ("nosuch:anthropic/claude-sonnet-4"; Ollama-style tags never hold a
+    # '/') or the prefix is a provider's name (PROVIDER_HOST_NAMES).
+    def unknown_host_prefix(raw, hosts:)
+      prefix, rest = raw.to_s.strip.split(":", 2)
+      return nil if rest.to_s.strip.empty? || !prefix.match?(HOST_NAME_RE)
+      return nil unless rest.include?("/") || PROVIDER_HOST_NAMES.include?(prefix.downcase)
+
+      prefix = prefix.downcase
+      hosts.keys.map { |k| k.to_s.downcase }.include?(prefix) ? nil : prefix
+    end
+
     def hosts_json_for_env(env: ENV, path: global_path(env: env))
       hosts = hosts_config(env: env, path: path)
       # Only serialize if non-default or explicitly configured hosts:
@@ -746,7 +934,7 @@ module Samagotchi
         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]).compact
+                       "vision" => v[:vision], "sampling" => v[:sampling], "thinking" => v[:thinking]&.to_s).compact
       end
       JSON.generate(simple)
     rescue StandardError
@@ -828,11 +1016,27 @@ module Samagotchi
         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
       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.
+    def model_setting(names, field, models: nil)
+      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?
+      end
+      nil
+    end
+
     def resolve_model_alias(raw, env: ENV, path: global_path(env: env), hosts: nil)
       value = raw.to_s.strip
       return value if value.empty?

data/lib/samagotchi/desktop/macos/App.swift

@@ -1,5 +1,6 @@
-// Chi Helper: the "Send to chi" Service opens the panel with the selection,
-// the hotkey with the clipboard. No Dock icon (LSUIElement); it stays
+// Chi Helper: the "Send to chi" Service opens the panel with the selection
+// (text, or images: files in Finder, a picture in Preview), the hotkey with
+// the clipboard (a screenshot too). No Dock icon (LSUIElement); it stays
 // running after the first launch. `ChiHelper --login on|off|status` (run
 // directly by chi desktop) manages the login item and exits.
 import AppKit
@@ -10,11 +11,12 @@ final class ServiceProvider: NSObject {
 
   // Info.plist NSServices: NSMessage = sendToChi.
   @objc func sendToChi(_ pboard: NSPasteboard, userData: String?, error: AutoreleasingUnsafeMutablePointer<NSString>) {
-    guard let text = pboard.string(forType: .string) else {
-      error.pointee = "No text in the selection" as NSString
+    let (text, images) = ImageIntake.read(pboard)
+    guard !text.isEmpty || !images.isEmpty else {
+      error.pointee = "No text or image in the selection" as NSString
       return
     }
-    app?.open(text: text)
+    app?.open(text: text, images: images)
   }
 }
 
@@ -28,6 +30,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
 
   func applicationDidFinishLaunching(_ notification: Notification) {
     provider.app = self
+    ImageIntake.sweep()
     NSApp.servicesProvider = provider
     NSUpdateDynamicServices()
     hotkey = Hotkey { [weak self] in self?.openFromClipboard() }
@@ -54,12 +57,13 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
 
   /// The hotkey doesn't activate us, so the frontmost app is the source.
   func openFromClipboard() {
-    open(text: NSPasteboard.general.string(forType: .string) ?? "")
+    let (text, images) = ImageIntake.read(NSPasteboard.general)
+    open(text: text, images: images)
   }
 
-  func open(text: String) {
+  func open(text: String, images: [PanelImage] = []) {
     let from = sourceApp
-    panel.show(text: text, source: from?.localizedName?.lowercased() ?? "desktop", returnTo: from)
+    panel.show(text: text, images: images, source: from?.localizedName?.lowercased() ?? "desktop", returnTo: from)
   }
 }
 

data/lib/samagotchi/desktop/macos/ChiRunner.swift

@@ -49,18 +49,24 @@ struct LiveSession: Decodable, Identifiable, Equatable {
   /// Only UUID-shaped ids go into chi's argv, so nothing can turn into a flag.
   var valid: Bool { UUID(uuidString: id) != nil }
 
-  var shortCwd: String {
-    guard let cwd else { return "" }
+  var shortCwd: String { cwd.map(Self.shorten) ?? "" }
+
+  /// A path with the home folder as "~".
+  static func shorten(_ path: String) -> String {
     let home = NSHomeDirectory()
-    return cwd.hasPrefix(home) ? "~" + cwd.dropFirst(home.count) : cwd
+    return path.hasPrefix(home) ? "~" + path.dropFirst(home.count) : path
   }
 
-  /// "just now", "5m ago", "2h ago", "yesterday", "3d ago", or "".
-  func age(now: Date = Date()) -> String {
-    guard let updatedAt else { return "" }
+  var updated: Date? {
+    guard let updatedAt else { return nil }
     let precise = ISO8601DateFormatter()
     precise.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
-    guard let date = precise.date(from: updatedAt) ?? ISO8601DateFormatter().date(from: updatedAt) else { return "" }
+    return precise.date(from: updatedAt) ?? ISO8601DateFormatter().date(from: updatedAt)
+  }
+
+  /// "just now", "5m ago", "2h ago", "yesterday", "3d ago", or "".
+  func age(now: Date = Date()) -> String {
+    guard let date = updated else { return "" }
     let seconds = max(0, now.timeIntervalSince(date))
     switch seconds {
     case ..<60: return "just now"
@@ -100,7 +106,9 @@ final class ChiRunner {
   /// Runs `chi <args>`, with stdin written from a background queue and
   /// stdout/stderr drained as they come (no pipe deadlock near the 16 KiB
   /// note cap). Calls back on the main queue.
-  func run(_ args: [String], stdin: Data? = nil, completion: @escaping (Result<ChiResult, ChiError>) -> Void) {
+  /// @param timeout this call's limit instead of the runner's
+  func run(_ args: [String], stdin: Data? = nil, timeout: TimeInterval? = nil,
+           completion: @escaping (Result<ChiResult, ChiError>) -> Void) {
     let config: LaunchConfig
     do { config = try loadLaunch() } catch let error as ChiError {
       completion(.failure(error)); return
@@ -155,7 +163,7 @@ final class ChiRunner {
         try? input.fileHandleForWriting.close()
       }
     }
-    DispatchQueue.global().asyncAfter(deadline: .now() + timeout) {
+    DispatchQueue.global().asyncAfter(deadline: .now() + (timeout ?? self.timeout)) {
       if process.isRunning {
         lock.lock(); timedOut = true; lock.unlock()
         process.terminate()