samagotchi 0.51.0 → 0.52.0

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -58,7 +58,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
 - `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
-- `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
+- `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.51.0
+version: 0.52.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:337ad1b4cc9308dc5abb47b13f51a76df4691ba80fe41648f391687b5b929b65
+  config_modification_protocol.md: sha256:a7a6352c03979db69d98955bee8f36eb468a6cf68904d418b7f3ddb788c83e7b
   memory_guide.md: sha256:15cd3b24eda853cc458371c6c75809a2d4b5352311d075aaa4384926b5221c27
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/children_status.rb

@@ -95,7 +95,7 @@ module Samagotchi
       return "running" if Tools::Delegate.running?(row)
       return "stopped" if session.status == Session::STATUS_STOPPED
 
-      outcome = session.last_turn.is_a?(Hash) ? session.last_turn["outcome"] : nil
+      outcome = session.last_turn&.outcome
       return "failed" if session.status == Session::STATUS_ERROR || outcome == "failed"
       return "done" if outcome == "completed" && reply
 

data/lib/samagotchi/commands/registry.rb

@@ -21,7 +21,8 @@ module Samagotchi
       #   turn runs (MID_TURN): a symbol, or a lambda line (stripped) → one
       # @!attribute local [Boolean] the UI runs it; completion and help only
       # @!attribute uis [Array<Symbol>, nil] a local entry's UIs (:repl,
-      #   :attached) for completion; nil means every UI
+      #   :attached, :web) for completion and /help; nil means every UI
+      #   (for a local entry, every terminal)
       # @!attribute match [#call] line (stripped) → whether it is this command
       # @!attribute handler [Proc, nil] runs it; SessionCommands instance_execs
       #   a built-in's with the line, and calls a bundle's with the text

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

@@ -20,6 +20,29 @@ module Samagotchi
       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