samagotchi 0.51.0 → 0.53.0

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
 

data/lib/samagotchi/engine.rb

@@ -504,6 +504,20 @@ module Samagotchi
     end
     private :record_prompt_notes
 
+    # A failed turn's one line (the error's #summary). A host's failure
+    # under an alias says what the alias became (HostRegistry#alias_note):
+    # "host main" alone doesn't tell --model splash's user it was splash.
+    # @return [String]
+    def failure_summary(error)
+      summary = error.respond_to?(:summary) ? error.summary : error.message
+      return summary unless error.is_a?(LLM::ProviderError) && error.host
+
+      note = @host_registry.alias_note(@effective_model_name)
+      note && note.end_with?("on host #{error.host}") ? "#{summary} (#{note})" : summary
+    rescue StandardError
+      summary
+    end
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -954,7 +968,7 @@ module Samagotchi
       served, served_for = served_model_for(snapshot, target: target)
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
                                 served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
-                                prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
+                                thinking: thinking_explained&.summary, prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -1029,16 +1043,46 @@ module Samagotchi
       nil
     end
 
-    # "off (models: qwen)" for /model: the effective model's thinking level
-    # and where it came from, nil when none is set.
+    # "off (models: qwen)", "low (session)" for /model: the effective
+    # model's thinking level and where it came from, nil when none is set.
     def thinking_summary
+      explained = thinking_explained
+      explained&.source ? explained.label : nil
+    end
+
+    # The effective model's thinking level with where it came from and the
+    # session's own (Thinking::Explained), as the next turn resolves it;
+    # nil when it can't be resolved.
+    # @return [Thinking::Explained, nil]
+    def thinking_explained
       target = @host_registry.resolve(@effective_model_name)
-      level, source = Thinking.resolve(target, names: model_lookup_names(target))
-      source ? "#{level} (#{source})" : nil
+      Thinking.explain(target, names: model_lookup_names(target), session: thinking_override)
     rescue StandardError
       nil
     end
 
+    # The session's own thinking level, nil when it has none.
+    # @return [Symbol, nil]
+    def thinking_override = @session&.thinking
+
+    # What a thinking level change costs the effective model's prompt
+    # cache (Thinking.cache_cost): :full, :provider or :tail.
+    # @return [Symbol]
+    def thinking_cache_cost
+      target = @host_registry.resolve(@effective_model_name)
+      Thinking.cache_cost(target, profile: target.entry&.chat? ? nil : profile&.name)
+    end
+
+    # Set the session's own thinking level (nil unsets it); the next turn's
+    # start resolves it, never a running one (its TurnSettings are fixed).
+    # The caller saves the session.
+    # @raise [ArgumentError] with no session yet
+    def thinking_override=(level)
+      raise ArgumentError, "no session yet" unless @session
+
+      @session.thinking = level
+    end
+
     # The model the server serves for the current model, and the name asked
     # for: what the last generation of that name reported, else llama.cpp's
     # model_alias (/props, one short cached probe; not with probe: false),
@@ -1105,6 +1149,7 @@ module Samagotchi
         served_expected_by: served_expected_by(served_pair[0]),
         context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
         llm_context: llm_context_summary,
+        thinking: thinking_explained&.summary,
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1242,22 +1287,22 @@ module Samagotchi
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
-      session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
-                            "seconds" => seconds.round(1), "origin" => source }
-      session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
-      session.last_turn.merge!(stop_facts(event))
+      session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
+                                       origin: source, exhausted: limit ? true : nil, limit: limit,
+                                       **stop_facts(event))
     end
 
-    # Why a turn stopped, from its end event, for a parent agent's wait
-    # (ReplyWait): a provider error's kind and whether a retry may help, a
-    # cancel's reason and the hook that stopped it. Only what is known.
+    # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
+    # parent agent's wait (ReplyWait): a provider error's kind and whether
+    # a retry may help, a cancel's reason and the hook that stopped it.
+    # Only what is known.
     def stop_facts(event)
       case event&.dig(:type)
       # kept_steps: the turn's work stayed (a parent must not send the task again).
       when :turn_failed
-        { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable], "kept_steps" => event[:kept_steps] }.compact
+        { error_kind: event[:error_kind]&.to_s, retryable: event[:retryable], kept_steps: event[:kept_steps] }
       when :turn_canceled
-        { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
+        { cancel_reason: event[:cancellation_reason]&.to_s, stopped_by: event[:cancelled_by]&.to_s }
       else {}
       end
     end
@@ -2088,7 +2133,7 @@ module Samagotchi
       failed[:kept_steps] = steps if steps
       # A provider error says what kind it is, for one line per kind in the UIs.
       if error.is_a?(LLM::ProviderError)
-        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: error.summary)
+        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: failure_summary(error))
       end
       failed
     end
@@ -2237,9 +2282,9 @@ module Samagotchi
       hook_notify(text, level, "thinking")
     end
 
-    # +target+'s thinking level (Thinking.resolve).
+    # +target+'s thinking level (Thinking.resolve), the session's own first.
     def thinking_level(target)
-      Thinking.resolve(target, names: model_lookup_names(target)).first
+      Thinking.resolve(target, names: model_lookup_names(target), session: thinking_override).first
     rescue StandardError
       Thinking::DEFAULT
     end
@@ -2470,7 +2515,7 @@ module Samagotchi
         model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
-        llm_context: -> { @session&.llm_context },
+        setup: -> { SessionSetup.of(@session) },
         frontend: -> { interface }
       )
     end

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/hooks/bundle_loader.rb

@@ -3,6 +3,7 @@
 require_relative "registry"
 require "digest"
 require_relative "../log"
+require_relative "../memory_bundle/bundle_hook"
 require_relative "../memory_bundle/provenance"
 require_relative "../memory_bundle/manifest"
 require_relative "../version"
@@ -44,7 +45,8 @@ module Samagotchi
         #
         # @param bundle_name [String]
         # @param hooks_dir [String] directory containing the bundle's .rb hook files
-        # @param metadata [Hash] basename => { event:, on_error:, priority: }
+        # @param metadata [Hash] basename => { event:, on_error:, priority:,
+        #   sha256: } (MemoryBundle::BundleHook.parse reads it)
         # @param registry [Samagotchi::Hooks::Registry]
         # @param failures [Guardrails::LoadFailures, nil] collects hooks that
         #   failed to load
@@ -64,14 +66,13 @@ module Samagotchi
             basename = raw_basename.to_s
             next if basename.empty?
 
-            meta = ->(key) { raw_meta && (raw_meta[key] || raw_meta[key.to_s]) }
-            event = meta.call(:event).to_s
+            hook = MemoryBundle::BundleHook.parse(raw_meta)
             # A hook with no declared event cannot be auto-registered.
-            next if event.empty?
+            next if hook.event.empty?
 
-            event_sym = event.to_sym
-            on_error = (meta.call(:on_error) || "skip").to_s
-            priority = (meta.call(:priority) || 100).to_i
+            event_sym = hook.event.to_sym
+            on_error = hook.on_error
+            priority = hook.priority
             fail_closed = on_error == "fail_closed" && event_sym == :before_tool_call
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
@@ -79,7 +80,7 @@ module Samagotchi
               failures&.add(what, "the file is missing", required: true) if fail_closed
               next
             end
-            if (mismatch = too_old || sha_mismatch(file, meta.call(:sha256), required: fail_closed))
+            if (mismatch = too_old || sha_mismatch(file, hook.sha256, required: fail_closed))
               Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
               failures&.add(what, mismatch, required: fail_closed)
               next

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
@@ -278,6 +273,19 @@ module Samagotchi
       ModelTarget.new(model: raw_model, entry: entry, bare_model: bare, client: client_for(entry))
     end
 
+    # What the alias +raw_model+ became, for an error that names only the
+    # host ("splash is an alias: gemma-x on host main"), or nil when it
+    # isn't an alias. An alias without a host of its own goes where a bare
+    # id goes (#host_for_model), often the default host the user never typed.
+    # @return [String, nil]
+    def alias_note(raw_model)
+      ref = model_ref(raw_model)
+      return nil unless ref.alias_name
+
+      target = resolve(raw_model)
+      "#{ref.alias_name} is an alias: #{target.bare_model} on host #{target.entry.name}"
+    end
+
     # The model id sent for +full_ref+: its alias applied, a known host
     # prefix stripped ("box:gemma" → "gemma").
     def bare_name(full_ref)

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

@@ -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