samagotchi 0.51.0 → 0.53.0

data/lib/samagotchi/session_manager.rb

@@ -6,6 +6,7 @@ require "time"
 require "securerandom"
 require "rbconfig"
 require_relative "client_id"
+require_relative "analytics_file"
 require_relative "atomic_file"
 require_relative "config"
 require_relative "delivery"
@@ -14,6 +15,7 @@ require_relative "session"
 require_relative "session_inbox"
 require_relative "session_metrics"
 require_relative "llm_context_strategy"
+require_relative "session_setup"
 require_relative "host_registry"
 require_relative "utf8_default"
 require_relative "turn_note"
@@ -163,8 +165,8 @@ module Samagotchi
     # @param images_from [String, nil] the session dir the seed's images are in
     # @param title [String, nil] what the lists show before the first turn
     #   (the prompt's preview by default, else the seed's first user message)
-    # @param llm_context [LLMContextOverride, nil] the session's own
-    #   llm_context values (chi --llm-context; a fork copies its parent's)
+    # @param setup [SessionSetup] the session's own settings (chi
+    #   --llm-context; a fork and a continue copy their session's)
     # @param continues [String, nil] the session this one continues (a
     #   session field; #continue_session)
     # @param note [String, nil] a context note the session starts with,
@@ -176,7 +178,7 @@ module Samagotchi
     #   and #model_warning: an id its host's saved list doesn't have
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
-                           title: nil, delegate: false, llm_context: nil, continues: nil, note: nil,
+                           title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
                            note_source: "chi", before_spawn: nil)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
@@ -198,7 +200,7 @@ module Samagotchi
         parent_id: parent_id,
         messages: messages,
         delegate: delegate,
-        llm_context: llm_context,
+        setup: setup,
         continues: continues
       )
       session.model_warning = model_warning
@@ -232,7 +234,7 @@ module Samagotchi
 
     # Start the next link of a chain: a new session that continues
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
-    # it was typed as, so an alias holds) and with its own llm_context,
+    # it was typed as, so an alias holds) and with its own setup (SessionSetup),
     # starting with a context note from chi: the link and the previous
     # link's recap (SessionChain.note_text). The previous link is archived
     # first, with its finished delegates (archive_session's rules: a turn
@@ -363,7 +365,7 @@ module Samagotchi
         ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
       end
       link = spawn_session(prompt: start, title: title, working_directory: previous.working_directory,
-                           model_name: previous.model_typed || previous.model_name, llm_context: previous.llm_context,
+                           model_name: previous.model_typed || previous.model_name, setup: SessionSetup.of(previous),
                            continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
                            note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn)
       link.moved_children = move
@@ -515,7 +517,7 @@ module Samagotchi
 
     GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
     # Tools::Builtins.parent_env's (Tools::TaskRuntime::MARKER_ENV_KEYS).
-    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL].freeze
+    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING].freeze
 
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).
@@ -973,7 +975,7 @@ module Samagotchi
     # session keeps. "pid" is the pid file workers wrote until 2026-10-01:
     # nothing writes or reads it now, but a folder from before still has one
     # and is still empty.
-    EMPTY_SKELETON_FILES = ["pid", "owner.lock", WorkerSidecar::FILE, "analytics.json"].freeze
+    EMPTY_SKELETON_FILES = ["pid", "owner.lock", WorkerSidecar::FILE, AnalyticsFile::NAME].freeze
     EMPTY_DIRS = [SessionInbox::INPUT_DIR, SessionInbox::NOTES_DIR, "images"].freeze
     EMPTY_SKELETON_DIRS = (EMPTY_DIRS + [SessionInbox::OUTPUT_DIR]).freeze
 
@@ -1057,17 +1059,48 @@ module Samagotchi
         path = File.join(dir, name)
         if EMPTY_SKELETON_DIRS.include?(name)
           File.directory?(path) && (!EMPTY_DIRS.include?(name) || Dir.empty?(path))
-        elsif name == "analytics.json"
-          Array(JSON.parse(File.read(path))["turn_records"]).empty?
+        elsif name == AnalyticsFile::NAME
+          analytics_empty?(path)
         # Cards and notices from before any turn (Bridge::CardStore).
         elsif name == "cards.json"
-          JSON.parse(File.read(path))["turns"].to_i.zero?
+          cards_empty?(path)
         else
           EMPTY_SKELETON_FILES.include?(name)
         end
       end
     end
 
+    # A folder's analytics.json is empty only when it is a JSON object with
+    # an empty turn_records array. Anything unreadable, not JSON, not an
+    # object, the wrong type, or turn_records the wrong shape reads as
+    # "not empty": a broken analytics keeps the folder instead of crashing
+    # the retention sweep (or of a wrong-shape one reading as empty).
+    def self.analytics_empty?(path)
+      data = read_json(path)
+      turns = data.is_a?(Hash) ? data["turn_records"] : nil
+      turns.is_a?(Array) && turns.empty?
+    end
+
+    # A folder's cards.json is empty only when it is a JSON object whose
+    # turns is an integer zero. Anything unreadable, not JSON, not an
+    # object, the wrong type, or turns not an integer reads as "not empty":
+    # a broken or wrong-shape cards file keeps the folder instead of
+    # raising (Array#/Hash#to_i) or reading as empty.
+    def self.cards_empty?(path)
+      data = read_json(path)
+      turns = data.is_a?(Hash) ? data["turns"] : nil
+      turns.is_a?(Integer) && turns.zero?
+    end
+
+    # A session-dir JSON file's contents, or nil when it is missing,
+    # unreadable, not JSON or not an object (mirrors AnalyticsFile#read): a
+    # broken file reads as none, so its folder is kept, not deleted.
+    def self.read_json(path)
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
     # Delete one session: its <id>.json, the whole <id>/ directory
     # (history sidecars, input, output, notes, images) and its attached
     # context (ContextSources: its sources, subscriptions, mute markers). The CLI, the TUI's

data/lib/samagotchi/session_metrics.rb

@@ -5,6 +5,7 @@ require "monitor"
 require "time"
 require "fileutils"
 require "securerandom"
+require_relative "analytics_file"
 require_relative "atomic_file"
 require_relative "token_usage"
 require_relative "model_price"
@@ -172,8 +173,8 @@ module Samagotchi
     # @param budget_tokens [Integer, Proc, nil] see .saved_context_pct
     # @return [SavedSummary, nil]
     def self.saved_summary(session_dir, budget_tokens: nil)
-      data = JSON.parse(File.read(File.join(session_dir, "analytics.json")))
-      return nil unless data.is_a?(Hash)
+      data = AnalyticsFile.read(session_dir)
+      return nil unless data
 
       tokens = data["tokens"].is_a?(Hash) ? data["tokens"] : {}
       count = ->(key) { tokens[key].is_a?(Numeric) ? tokens[key] : 0 }
@@ -182,7 +183,7 @@ module Samagotchi
                        reasoning_sum: count.call("reasoning_sum"), cost_sum: count.call("cost_sum"),
                        cost_estimate_sum: count.call("cost_estimate_sum"),
                        memory_index: data["memory_index"].is_a?(Hash) ? data["memory_index"] : nil)
-    rescue JSON::ParserError, SystemCallError, TypeError
+    rescue TypeError
       nil
     end
 
@@ -217,10 +218,10 @@ module Samagotchi
     def self.saved_tool_records(session_dir, turn_id)
       return [] if turn_id.to_s.empty?
 
-      records = JSON.parse(File.read(File.join(session_dir, "analytics.json")))["tool_records"]
+      records = AnalyticsFile.read(session_dir)&.dig("tool_records")
       Array(records).select { |r| r.is_a?(Hash) && r["turn_id"] == turn_id }
                     .sort_by { |r| [r["iteration"].to_i, r["call_index"].to_i] }
-    rescue JSON::ParserError, SystemCallError, TypeError
+    rescue TypeError
       []
     end
 
@@ -234,9 +235,9 @@ module Samagotchi
     def self.saved_turn_record(session_dir, turn_id)
       return nil if turn_id.to_s.empty?
 
-      records = JSON.parse(File.read(File.join(session_dir, "analytics.json")))["turn_records"]
+      records = AnalyticsFile.read(session_dir)&.dig("turn_records")
       Array(records).find { |r| r.is_a?(Hash) && r["id"] == turn_id }
-    rescue JSON::ParserError, SystemCallError, TypeError
+    rescue TypeError
       nil
     end
 
@@ -422,8 +423,7 @@ module Samagotchi
       # (XDG) location; passing an explicit nil would override it and break
       # File.join.
       FileUtils.mkdir_p(dir = session_dir(sid, state_dir || @state_dir))
-      path = File.join(dir, "analytics.json")
-      AtomicFile.write(path, JSON.pretty_generate(data) + "\n")
+      AtomicFile.write(AnalyticsFile.path(dir), JSON.pretty_generate(data) + "\n")
       @mutex.synchronize { @persisted_turns = [@persisted_turns, turn_count].max }
       true
     rescue StandardError
@@ -977,11 +977,8 @@ module Samagotchi
     # broken file, or an older shape: nothing, or zeros where keys are
     # missing). Caller holds the mutex.
     def load_persisted
-      path = File.join(session_dir(@session_id, @state_dir), "analytics.json")
-      return unless File.file?(path)
-
-      prior = JSON.parse(File.read(path))
-      return unless prior.is_a?(Hash)
+      prior = AnalyticsFile.read(session_dir(@session_id, @state_dir))
+      return unless prior
 
       loaded_turns = loaded_records(prior["turn_records"])
       @turn_records = loaded_turns + @turn_records
@@ -1004,12 +1001,10 @@ module Samagotchi
       @memory_index ||= symbolized(prior["memory_index"]) if prior["memory_index"].is_a?(Hash)
       # The window last seen, until this process's first generation reports.
       window = prior["context"].is_a?(Hash) ? prior["context"] : {}
-      if window["window_tokens"] && @context_window_tokens.nil?
-        @context_window_tokens = window["window_tokens"]
-        @context_window_source = window["window_source"]
-      end
-    rescue JSON::ParserError, SystemCallError
-      nil
+      return unless window["window_tokens"] && @context_window_tokens.nil?
+
+      @context_window_tokens = window["window_tokens"]
+      @context_window_source = window["window_source"]
     end
 
     def symbolized(hash)

data/lib/samagotchi/session_setup.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_override"
+require_relative "thinking"
+
+module Samagotchi
+  # A session's own settings that come before its model's, carried as one
+  # value on the paths that spawn a session from a whole setup
+  # (SessionManager.spawn_session, a continue, a plugin's fork, the web's
+  # create, chi send --new): +llm_context+ is an LLMContextOverride or nil,
+  # +thinking+ a level Symbol (Thinking.session_level) or nil.
+  #
+  # It doesn't save itself: the session keeps each setting in its own field
+  # and file key, and resolves it on its own. A delegate child starts
+  # without one; a continue and a fork copy their session's (.of).
+  SessionSetup = Data.define(:llm_context, :thinking) do
+    def initialize(llm_context: nil, thinking: nil) = super
+
+    def empty? = llm_context.nil? && thinking.nil?
+
+    # A session's own setup, for a session that starts from it.
+    # @param session [Session, nil]
+    # @return [SessionSetup]
+    def self.of(session)
+      return new if session.nil?
+
+      new(llm_context: session.llm_context, thinking: session.thinking)
+    end
+  end
+end

data/lib/samagotchi/sessions_command.rb

@@ -5,6 +5,7 @@ require_relative "session"
 require_relative "session_manager"
 require_relative "session_retention"
 require_relative "project_scope"
+require_relative "analytics_file"
 require_relative "session_metrics"
 require_relative "recap_store"
 require_relative "session_delete_command"
@@ -337,10 +338,10 @@ module Samagotchi
           return [TerminalUI::EventRenderer.deep_symbolize_keys(body), true, nil]
         end
       end
-      return [nil, false, nil] unless File.file?(File.join(dir, "analytics.json"))
+      return [nil, false, nil] unless File.file?(Samagotchi::AnalyticsFile.path(dir))
 
       snapshot = Samagotchi::SessionMetrics.new.tap { |m| m.session_id = session.id }.saved_snapshot
-      note = live_worker?(session.id) ? "(no live worker answered; from the saved analytics.json)" : nil
+      note = live_worker?(session.id) ? "(no live worker answered; from the saved #{Samagotchi::AnalyticsFile::NAME})" : nil
       [snapshot, false, note]
     end
 

data/lib/samagotchi/steer_cut.rb

@@ -22,6 +22,13 @@ module Samagotchi
       { thinking: event[:thinking].to_s, text: text.to_s }
     end
 
+    # steer.cut_after: how long a generation streams only thinking before a
+    # message may cut it, in whole seconds (0 or less: cutting is off).
+    # @return [Integer]
+    def self.cut_after
+      Config.get("steer.cut_after").to_i
+    end
+
     # +clock+: monotonic seconds; +controller+: the running turn's cancel
     # controller (nil between turns), read only when a cut is due.
     def initialize(clock:, controller:)
@@ -51,7 +58,7 @@ module Samagotchi
     def cut_for_steer(source, epoch: nil)
       return :off unless Steer.cuts?(source)
 
-      after = Config.get("steer.cut_after").to_i
+      after = self.class.cut_after
       return :off unless after.positive?
 
       ctrl = @controller.call
@@ -104,7 +111,7 @@ module Samagotchi
     def recheck
       return unless @waiting.waiting?
 
-      after = Config.get("steer.cut_after").to_i
+      after = self.class.cut_after
       return unless after.positive? && @phase.cuttable?(after)
 
       source = @waiting.take

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../config"
 require_relative "../model_profile"
 require_relative "../session_manager"
+require_relative "../thinking_command"
 require_relative "../bridge_client"
 require_relative "../parent_report"
 require_relative "../cli/exit"
@@ -40,16 +41,20 @@ module Samagotchi
       #   (LLMContextOverride.update): a new session starts with them; a
       #   resumed or attached one's worker gets a /llm-context, after the
       #   /model
+      # @param thinking [String, nil] --thinking as typed: a new session
+      #   starts with it as its own level; a resumed or attached one's
+      #   worker gets a /thinking, after those
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {})
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil)
         client = connect(attach: attach, shared: shared, resume: resume, model: model,
-                         memories: memories, muted_memories: muted_memories, llm_context: llm_context)
+                         memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
+        commands << "#{ThinkingCommand::NAME} #{thinking}" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
         surface = open_surface
         attached = AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
@@ -111,7 +116,7 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], llm_context: {}, err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, err: $stderr)
         sd = state_dir || Session.default_state_dir
         warn_memory_flags_ignored(attach || resume, memories, muted_memories, err) if attach || resume
         if attach
@@ -127,7 +132,8 @@ module Samagotchi
                   else
                     SessionManager.spawn_session(prompt: nil, model_name: model && model_ref(model), state_dir: sd,
                                                  memories: memories, muted_memories: muted_memories,
-                                                 llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context))
+                                                 setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
+                                                                         thinking: Thinking.session_level(thinking)))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -430,7 +430,7 @@ module Samagotchi
       # @return [nil]
       def submit_delivery(choice, text)
         return @screen.commit(STEER_CHOICE_USAGE) if text.empty?
-        return @screen.commit(QUEUE_UNAVAILABLE) if choice == :queue
+        return @screen.commit(QUEUE_UNAVAILABLE) if choice == :queue && @running
 
         # To an idle session it is an ordinary prompt: no delivery to send.
         send_prompt(text, delivery: @running ? Delivery::CUT : nil)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -5,6 +5,7 @@ require_relative "../served_model"
 require_relative "../image_store"
 require_relative "../turn_note"
 require_relative "../steer"
+require_relative "../steer_cut"
 require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
 
@@ -19,7 +20,7 @@ module Samagotchi
       # (no UI: the same text from the CLI).
       # @return [String] "(no metrics yet)" without a snapshot
       def self.format_session_metrics(snapshot)
-        (@formatter ||= Object.new.extend(Formatting)).send(:format_session_metrics, snapshot)
+        (@formatter ||= Object.new.extend(Formatting)).format_session_metrics(snapshot)
       end
 
       def format_tool_activity_line(activity, duration_ms: nil)
@@ -99,7 +100,8 @@ module Samagotchi
       # line goes in at the running turn's next step boundary (nothing cuts
       # unless the message asked for it), /cut's cutting now or once the
       # thinking passes steer.cut_after, and /queue's waiting for the end.
-      # Both TUIs print the same words (SteerCut#cut_for_steer's answer).
+      # Both TUIs and chi send --cut print the same words
+      # (SteerCut#cut_for_steer's answer).
       NEXT_STEP_NOTE = "(goes in at the next step)"
       CUT_NOW_NOTE = "(cut in now)"
       CUT_WAITS_NOTE = "(cuts in once the thinking passes %d s)"
@@ -115,14 +117,17 @@ module Samagotchi
 
       # @param outcome [Symbol] SteerCut#cut_for_steer's answer: :now, :waits or :off
       # @return [String] the dim line to show for a /cut
-      def steer_cut_note(outcome)
+      def self.steer_cut_note(outcome)
         case outcome
         when :now then CUT_NOW_NOTE
-        when :waits then format(CUT_WAITS_NOTE, Config.get("steer.cut_after").to_i)
+        when :waits then format(CUT_WAITS_NOTE, SteerCut.cut_after)
         else CUT_OFF_NOTE
         end
       end
 
+      # The same words, for a UI that includes the module.
+      def steer_cut_note(outcome) = Formatting.steer_cut_note(outcome)
+
       # The choice a mid-turn line carries, as [:cut, "TEXT"] or
       # [:queue, "TEXT"]; nil for any other line. The text is "" when the
       # line named the choice without one.
@@ -538,6 +543,8 @@ module Samagotchi
         value.length > width ? value[0, width] : value
       end
 
+      public
+
       # Render the analytics snapshot as a compact, user-facing report. Raw event
       # logs (debug-only) are intentionally excluded; this surface is for the REPL
       # and `chi sessions stats` (the module function above).
@@ -591,6 +598,8 @@ module Samagotchi
         lines << "model notes:      #{notes}" unless notes.empty?
         llm_context = llm_context_stats_text(snapshot[:llm_context])
         lines << "llm context:      #{llm_context}" if llm_context
+        thinking = thinking_stats_text(snapshot[:thinking])
+        lines << "thinking:         #{thinking}" if thinking
         if snapshot[:served_model]
           asked = snapshot[:served_model_for]
           differs = !snapshot[:served_expected_by] && ServedModel.differs?(asked, snapshot[:served_model])
@@ -600,6 +609,8 @@ module Samagotchi
         lines.join("\n")
       end
 
+      private
+
       # " (25.0% of the 64000 budget)" when the session's llm_context budget
       # is set and smaller than the window, else " (12.5%)": the live meter
       # counts against the smaller of the two (ContextStatus#counted_against),
@@ -630,6 +641,17 @@ module Samagotchi
           "budget #{budget} (#{get.call(:budget_where)})"
       end
 
+      # "low (session)", "default" for /stats (Thinking::Explained#summary;
+      # symbol or string keys, the attached TUI's come as JSON); nil
+      # without one.
+      def thinking_stats_text(summary)
+        return nil unless summary.is_a?(Hash)
+
+        level = summary[:level] || summary["level"]
+        source = summary[:source] || summary["source"]
+        source ? "#{level} (#{source})" : level
+      end
+
       # ", cached 4864 (93%), cache writes 312, re-prefilled 2100, reasoning
       # 212" for the tokens line; the counts a server didn't report are left
       # out (re-prefilled: SessionMetrics' reprefill_sum).

data/lib/samagotchi/terminal_ui.rb

@@ -90,9 +90,12 @@ module Samagotchi
     #   however the REPL ends, saves no memories and writes no recap
     # @param llm_context [Hash{Symbol => String}] --llm-context* as typed
     #   (LLMContextOverride.update): set on the new or resumed session
+    # @param thinking [String, nil] --thinking as typed: the new or resumed
+    #   session's own level (default unsets it)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
-                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {})
+                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil)
       @scratch        = scratch
+      @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
       @default_model_name = ModelProfile.required_model_name(nil)
@@ -235,6 +238,10 @@ module Samagotchi
       # --non-interactive with no --prompt is a harmless no-op exit: build
       # nothing and return (no transient session, no banner).
       return if @non_interactive && @prompt.nil?
+      # A UI-only command (/stats, /exit …) isn't run without the REPL, and
+      # isn't a prompt either: refused as chi send refuses it, before any
+      # session is made (bin/chi exits 1).
+      return refuse_one_shot_ui_command if @non_interactive && SessionCommands.ui_only_entry(@prompt)
 
       session = @resume_session || @engine.store_model!(Session.new_session(
         mode: "assist",
@@ -246,8 +253,10 @@ module Samagotchi
       ))
       # --llm-context*: the session's own values, over a resumed one's.
       # Saved at once on a resumed one: leaving before a turn keeps them.
-      unless @llm_context_words.empty?
-        session.llm_context = LLMContextOverride.update(session.llm_context, @llm_context_words)
+      # --thinking: the session's own level, saved at once on a resumed one.
+      unless @llm_context_words.empty? && @thinking_word.nil?
+        session.llm_context = LLMContextOverride.update(session.llm_context, @llm_context_words) unless @llm_context_words.empty?
+        session.thinking = Thinking.session_level(@thinking_word) if @thinking_word
         session.save if @resume_session
       end
       claim_session!(session.id) unless @owner_lock
@@ -343,7 +352,7 @@ module Samagotchi
     # so the session is kept and `chi --resume` takes it up again.
     # @return [Symbol] :turn_failed
     def one_shot_failed(session, error)
-      warn "Error: #{error.respond_to?(:summary) ? error.summary : error.message}"
+      warn "Error: #{@engine.failure_summary(error)}"
       if !@scratch && Session.exist?(session.id)
         warn "chi: the session is kept with your prompt; continue it with: chi --resume #{session.id}"
       end
@@ -366,6 +375,14 @@ module Samagotchi
       :turn_failed if result.status == :error
     end
 
+    # `chi -p /stats --non-interactive`: why it doesn't run, on stderr.
+    # @return [Symbol] :turn_failed
+    def refuse_one_shot_ui_command
+      name = SessionCommands.ui_only_entry(@prompt).name
+      warn "chi: refused: #{SessionCommands.ui_only_refusal(name, @resume_session&.id, runner: "--non-interactive")}"
+      :turn_failed
+    end
+
     # Ctrl-C in a -p --non-interactive turn: the Engine kept the prompt and
     # a cancel note in the session (it saves only a failed turn), so save
     # it here: `chi --resume` takes it up again. A scratch session goes in

data/lib/samagotchi/thinking.rb

@@ -10,7 +10,9 @@ module Samagotchi
   #   low, medium, high   the effort a chat host is asked for
   #   default  chi sends nothing: the provider's or template's own default
   #
-  # Order (#resolve): --thinking / SAMAGOTCHI_THINKING_LEVEL, then
+  # Order (#resolve): the session's own level (/thinking, chi --thinking at
+  # start, chi send --new --thinking, the web), then the process default
+  # (chi web --thinking / SAMAGOTCHI_THINKING_LEVEL), then
   # models.<key>.thinking, hosts.<name>.thinking, thinking.level in
   # config.yml, then default.
   module Thinking
@@ -33,8 +35,39 @@ module Samagotchi
     # anything there (low/medium/high have no native knob).
     Native = Data.define(:system_token, :prefill, :honoured)
 
+    # The source a session's own level reads as.
+    SESSION_SOURCE = "session"
+
+    # A level and where it came from (#explain): +source+ is "session",
+    # "--thinking", "SAMAGOTCHI_THINKING_LEVEL", "models: qwen",
+    # "hosts.work" or "thinking.level", nil for the default; +own+ is the
+    # session's own level, nil without one. What /thinking, /model,
+    # /stats, the snapshots and the web read.
+    Explained = Data.define(:level, :source, :own) do
+      # "low (session)", "default" with no source.
+      def label = source ? "#{level} (#{source})" : level.to_s
+
+      # The plain form the snapshots, the worker's command_ran event and
+      # the web read.
+      # @return [Hash] symbol keys
+      def summary = { level: level.to_s, source: source, own: own&.to_s }
+    end
+
     module_function
 
+    # A session's own level from its file or a command word: :off, :low,
+    # :medium or :high; nil for anything else, default included (unset:
+    # the session follows the process default and the model). Never warns:
+    # a session file keeps a value it can't read as written.
+    # @return [Symbol, nil]
+    def session_level(value)
+      return value if LEVELS.include?(value) && value != DEFAULT
+      return nil unless value.is_a?(String)
+
+      level = value.strip.downcase.to_sym
+      LEVELS.include?(level) && level != DEFAULT ? level : nil
+    end
+
     # A configured value as a level; nil when unset or not a level (that
     # warns once, naming +where+). YAML reads an unquoted `off` as false,
     # which is :off; true (`on`) isn't a level.
@@ -51,13 +84,17 @@ module Samagotchi
       nil
     end
 
-    # The level for +target+ and where it came from ("--thinking",
-    # "models: qwen", "hosts.work", "thinking.level"; nil for the default).
+    # The level for +target+ and where it came from ("session",
+    # "--thinking", "models: qwen", "hosts.work", "thinking.level"; nil for
+    # the default).
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param session [Symbol, nil] the session's own level (Session#thinking)
     # @return [Array(Symbol, String|nil)]
-    def resolve(target, names:, models: nil)
+    def resolve(target, names:, models: nil, session: nil)
+      return [session, SESSION_SOURCE] if session
+
       global, origin = global_level
       return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
 
@@ -66,8 +103,8 @@ module Samagotchi
       rescue StandardError
         {}
       end
-      key, value = ConfigFile.model_setting(names, :thinking, models: models)
-      return [value, "models: #{key}"] if key
+      setting = ConfigFile.model_setting(names, :thinking, models: models)
+      return [setting.value, "models: #{setting.key}"] if setting
 
       host = target.entry.thinking
       return [host, "hosts.#{target.entry.name}"] if host
@@ -76,6 +113,13 @@ module Samagotchi
       [DEFAULT, nil]
     end
 
+    # #resolve, as an Explained with the session's own level beside it.
+    # @return [Explained]
+    def explain(target, names:, models: nil, session: nil)
+      level, source = resolve(target, names: names, models: models, session: session)
+      Explained.new(level: level, source: source, own: session)
+    end
+
     # thinking.level as a level and its origin (:cli, :env, :file), or nil.
     def global_level
       raw, origin = Config.get_with_origin("thinking.level")
@@ -88,6 +132,22 @@ module Samagotchi
       nil
     end
 
+    # What a level change costs the prompt cache on +target+ (/thinking's
+    # note; a confirm step may ask before the costly ones):
+    #   :full      the native Gemma 4 prompt starts with <|think|>, so the
+    #              whole prompt is read again;
+    #   :provider  a chat host gets other request fields: a local llama.cpp
+    #              or Splash server keeps its cache, a hosted API may not;
+    #   :tail      native Qwen and the rest: only the tail changes.
+    # @param target [HostRegistry::ModelTarget]
+    # @param profile [String, nil] the native prompt profile's name
+    # @return [Symbol]
+    def cache_cost(target, profile: nil)
+      return :provider if target.entry&.chat?
+
+      profile == "gemma4" ? :full : :tail
+    end
+
     # Request fields for an OpenAI-style chat host. off sends both switches
     # (the template's enable_thinking and the OpenAI-style reasoning_effort
     # "none"): llama.cpp, Splash and OpenRouter each honour one of them.