samagotchi 0.51.0 → 0.53.0

data/lib/samagotchi/reply_wait.rb

@@ -61,7 +61,7 @@ module Samagotchi
     #   idle again ends the wait even if it was never seen running, and a
     #   question already pending then is not the answer's. A nil
     #   messages: skips the count. last_turn: (the session's
-    #   last_turn["ended_at"] then, maybe nil) ends the wait on any turn
+    #   last_turn.ended_at then, maybe nil) ends the wait on any turn
     #   that ended since, idle again, however fast it ran (a failure after
     #   a failure replaces the note and leaves the count as it was), and
     #   with it the count isn't used: a note between turns grows it too.
@@ -141,8 +141,7 @@ module Samagotchi
     # ended, so a turn that ends before the first look still ends the wait.
     # @return [Hash]
     def baseline_of(session, question_id: session.pending_question&.dig(:id))
-      last = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
-      { messages: session.messages.size, question_id: question_id, last_turn: last }
+      { messages: session.messages.size, question_id: question_id, last_turn: session.last_turn&.ended_at }
     end
 
     # An idle session whose turn ended after the baseline was taken: its
@@ -155,7 +154,7 @@ module Samagotchi
       return false unless baseline
 
       if baseline.key?(:last_turn)
-        ended = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
+        ended = session.last_turn&.ended_at
         return !ended.nil? && ended != baseline[:last_turn]
       end
       !!(baseline[:messages] && session.messages.size > baseline[:messages])
@@ -164,15 +163,14 @@ module Samagotchi
     # @return [Result] :no_reply with the outcome the session's last_turn
     #   records, when it is the turn waited for
     def no_reply(session, baseline)
-      last = session.last_turn.is_a?(Hash) ? session.last_turn : {}
-      fresh = baseline.nil? || !baseline.key?(:last_turn) || (last["ended_at"] && last["ended_at"] != baseline[:last_turn])
-      outcome = fresh ? last["outcome"] : nil
-      if fresh && last["exhausted"]
-        return Result.new(status: :no_reply, outcome: "exhausted", limit: last["limit"], session: session)
-      end
+      last = session.last_turn || LastTurn.new
+      fresh = baseline.nil? || !baseline.key?(:last_turn) || (last.ended_at && last.ended_at != baseline[:last_turn])
+      outcome = fresh ? last.outcome : nil
+      return Result.new(status: :no_reply, outcome: "exhausted", limit: last.limit, session: session) if fresh && last.exhausted
 
       text = outcome == "failed" ? TurnNote.failure_summary(session.messages) : nil
-      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by", "kept_steps").transform_keys(&:to_sym) : {}
+      # Every stop fact the turn has: Result takes them by name.
+      why = fresh ? last.stop_facts : {}
       Result.new(status: :no_reply, outcome: outcome, text: text, session: session, **why)
     end
 
@@ -188,12 +186,12 @@ module Samagotchi
     def settled(session, id, state_dir:)
       return session unless session.status == Session::STATUS_RUNNING
 
-      before = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
+      before = session.last_turn&.ended_at
       deadline = monotonic + SETTLE_SECONDS
       loop do
         sleep(0.02)
         fresh = Session.load(id, state_dir: state_dir)
-        ended = fresh.last_turn.is_a?(Hash) ? fresh.last_turn["ended_at"] : nil
+        ended = fresh.last_turn&.ended_at
         return fresh if fresh.status != Session::STATUS_RUNNING || ended != before || monotonic > deadline
       end
     rescue ArgumentError

data/lib/samagotchi/sampling_settings.rb

@@ -13,7 +13,7 @@ module Samagotchi
 
     # @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)
     # @return [Hash] frozen, symbol keys; may be empty
     def self.for(target, names:, models: nil)
       resolve(target, names, models).first
@@ -44,11 +44,11 @@ module Samagotchi
         {}
       end
       host = target.entry.sampling || EMPTY
-      key, model = ConfigFile.model_setting(names, :sampling, models: models)
+      model = ConfigFile.model_setting(names, :sampling, models: models)
       sources = []
       sources << "hosts.#{target.entry.name}" unless host.empty?
-      sources << "models: #{key}" if key
-      [host.merge(model || EMPTY).freeze, sources]
+      sources << "models: #{model.key}" if model
+      [host.merge(model&.value || EMPTY).freeze, sources]
     end
 
     private_class_method :resolve

data/lib/samagotchi/self_report.rb

@@ -145,13 +145,15 @@ module Samagotchi
       return nil unless window
       return [window.tokens, "hosts.#{target.entry.name}"] if window.source == :host_setting
 
-      [window.tokens, "models: #{ConfigFile.model_setting(names, :window_tokens, models: models).first}"]
+      [window.tokens, "models: #{ConfigFile.model_setting(names, :window_tokens, models: models).key}"]
     rescue StandardError
       nil
     end
 
     SESSION_MODEL_ENV = "SAMAGOTCHI_SESSION_MODEL"
     PARENT_SESSION_ENV = "SAMAGOTCHI_PARENT_SESSION"
+    # The session's own thinking level, beside its model (Builtins.parent_env).
+    SESSION_THINKING_ENV = "SAMAGOTCHI_SESSION_THINKING"
 
     # The model of the session this chi self runs in (its execute exports
     # SAMAGOTCHI_SESSION_MODEL, the resolved ref, live after /model); nil
@@ -355,13 +357,14 @@ module Samagotchi
       end
     end
 
-    # The model's thinking level and where it came from (Thinking.resolve).
+    # The model's thinking level and where it came from (Thinking.resolve);
+    # in a session's commands its own level first (SAMAGOTCHI_SESSION_THINKING).
     def thinking_for(model, env)
       registry = HostRegistry.new(env: env)
       target = registry.resolve(model)
-      level, source = Thinking.resolve(target, names: registry.lookup_names(model, target: target),
-                                               models: ConfigFile.model_settings(env: env))
-      source ? "#{level} (#{source})" : level.to_s
+      session = session_model(env) ? Thinking.session_level(env[SESSION_THINKING_ENV]) : nil
+      Thinking.explain(target, names: registry.lookup_names(model, target: target),
+                               models: ConfigFile.model_settings(env: env), session: session).label
     rescue StandardError => e
       "(unknown: #{e.message})"
     end

data/lib/samagotchi/send_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "client_id"
 require_relative "delivery"
+require_relative "terminal_ui/formatting"
 require_relative "session"
 require_relative "session_commands"
 require_relative "session_inbox"
@@ -33,10 +34,12 @@ module Samagotchi
     CLIENT_ID = ClientId::CLI_SEND
     # The cap on one turn's images the Bridge checks.
     MAX_IMAGES = ImageStore::MAX_TURN_REFS
+    # A cut's outcomes in the Bridge's ack (SteerCut#cut_for_steer).
+    CUT_OUTCOMES = %w[now waits off].freeze
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... [--cut] (ID|PREFIX)...
-             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [-m TEXT] [--image PATH]...
+             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [-m TEXT] [--image PATH]...
              chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --wait [--timeout S] [--format json] ID
@@ -59,16 +62,20 @@ module Samagotchi
                     the current one
         --continues ID
                     (--new) start the next link of that session's chain:
-                    in its folder, on its model and LLM context, with a
-                    note carrying its recap; it is archived. last:ID
-                    names the chain's latest link. Without -m the new
-                    session waits idle. Refused for a session continued
-                    already (naming the next link) or with delegates
-                    still open
+                    in its folder, on its model, LLM context and
+                    thinking level, with a note carrying its recap; it
+                    is archived. last:ID names the chain's latest link.
+                    Without -m the new session waits idle. Refused for a
+                    session continued already (naming the next link) or
+                    with delegates still open
         --model M   (--new) its model; default the configured one
         --llm-context LAYERS, --llm-context-apply RULE, --llm-context-budget N
                     (--new) its own LLM context strategy (none, stale,forget),
                     apply rule and budget (64k, off), as chi takes them
+        --thinking LEVEL
+                    (--new) its own thinking level (off, low, medium,
+                    high; default: none of its own), above a process
+                    default such as SAMAGOTCHI_THINKING_LEVEL
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
                     answer from you: the question, its options and the
@@ -110,6 +117,7 @@ module Samagotchi
       f.value "--llm-context", key: :llm_strategy
       f.value "--llm-context-apply", key: :llm_apply
       f.value "--llm-context-budget", key: :llm_budget
+      f.value "--thinking"
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.switch "--cut"
@@ -242,7 +250,7 @@ module Samagotchi
       return usage_error("at most #{MAX_IMAGES} images") if options[:images].size > MAX_IMAGES
       return new_options(options) if options[:new]
 
-      %i[dir model continues].each { |key| return usage_error("--#{key} needs --new") if options[key] }
+      %i[dir model continues thinking].each { |key| return usage_error("--#{key} needs --new") if options[key] }
       LLM_CONTEXT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") if options[key] }
       return usage_error("give session ids") if options[:ids].empty?
 
@@ -259,9 +267,9 @@ module Samagotchi
 
       if options[:continues]
         taken = [("--dir" if options[:dir]), ("--model" if options[:model])] +
-                LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] }
+                LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])]
         unless taken.compact.empty?
-          return usage_error("--continues takes the previous session's folder, model and LLM context; " \
+          return usage_error("--continues takes the previous session's folder, model, LLM context and thinking level; " \
                              "leave out #{taken.compact.join(", ")}")
         end
       end
@@ -273,6 +281,15 @@ module Samagotchi
         return usage_error(e.message)
       end
 
+      if options[:thinking]
+        word = options[:thinking].strip.downcase
+        unless Thinking::LEVELS.map(&:to_s).include?(word)
+          return usage_error("--thinking takes #{Thinking::LEVELS.join(", ")}, not #{options[:thinking]}")
+        end
+
+        options[:thinking] = Thinking.session_level(word)
+      end
+
       if options[:dir]
         options[:dir] = File.expand_path(options[:dir])
         return usage_error("no folder #{options[:dir]}") unless File.directory?(options[:dir])
@@ -317,7 +334,9 @@ module Samagotchi
                     SessionManager.continue_session(options[:continues], **start, state_dir: @state_dir)
                   else
                     SessionManager.spawn_session(**start, working_directory: options[:dir],
-                                                          model_name: options[:model], llm_context: options[:llm_context],
+                                                          model_name: options[:model],
+                                                          setup: SessionSetup.new(llm_context: options[:llm_context],
+                                                                                  thinking: options[:thinking]),
                                                           state_dir: @state_dir)
                   end
       rescue SessionManager::ContinueRefused, SessionManager::ArchiveRefused, SessionManager::OwnedByTUI => e
@@ -462,26 +481,8 @@ module Samagotchi
     # (a bundle's too).
     def command_like?(text) = text.to_s.lstrip.start_with?("/", "!")
 
-    # The UI-only built-in command +text+ (stripped) is a line of (/stats,
-    # /exit, …), or nil: the worker never runs it, so chi send must not pass
-    # it on. What the UIs run: the line as the entry's match takes it — bare
-    # "exit" too (/exit's match), but not with arguments ("/exit --delete" is
-    # a UI line; "/stats please" is a prompt), as in a terminal.
-    # @return [Commands::Registry::Entry, nil]
-    def local_command(text)
-      line = text.to_s.strip
-      return nil unless command_like?(line) || line.match?(/\Aexit\z/i)
-
-      entry = SessionCommands.builtin_registry.lookup_local(line)
-      # Only the exact line the UI runs: "/stats please" is a prompt, and
-      # "/exit --delete" is left to the worker (the TUI runs it as /exit, the
-      # worker answers its unknown-command way). Bare "exit" is /exit's line
-      # as its match takes it; the reply names the command, /exit.
-      return nil unless entry
-      return entry if line == entry.name
-
-      line.match?(/\Aexit\z/i) ? entry : nil
-    end
+    # @return [Commands::Registry::Entry, nil] SessionCommands.ui_only_entry
+    def local_command(text) = SessionCommands.ui_only_entry(text)
 
     # A UI-only command: nothing is sent (with --new, no session is created
     # either). /stats points at its model-free reader and names the session;
@@ -506,13 +507,7 @@ module Samagotchi
       CLI::Exit::FAILED
     end
 
-    # Why a UI-only command isn't sent: /stats points at its model-free
-    # reader (naming the session when there is one).
-    def local_refusal(name, id)
-      return "#{name} is a terminal and web command; chi send doesn't run it" unless name == "/stats"
-
-      "#{name} is a terminal and web command; use chi sessions stats #{id ? id[0, 8] : "ID"}"
-    end
+    def local_refusal(name, id) = SessionCommands.ui_only_refusal(name, id, runner: "chi send")
 
     # --wait after a message that ran as a session command: no reply comes
     # for it. Its output shows where the session is open.
@@ -585,14 +580,13 @@ module Samagotchi
       # rather than merging it into the running one.
       return " (runs after the current turn)" unless @images.empty?
 
-      case (Delivery.cut?(delivery) ? ack["cut"].to_s : "")
-      when "now" then " (cut in now)"
-      when "waits" then " (cuts in once the thinking passes #{Config.get("steer.cut_after").to_i} s)"
-      when "off" then " (cutting is off; goes in at the next step)"
-      # No outcome: a plain message, or the input file (the Bridge went
-      # away), which the next step's drain takes.
-      else " (goes in at the running turn's next step)"
-      end
+      # The TUIs' words for a cut's outcome. No outcome: a plain message,
+      # or the input file (the Bridge went away), which the next step's
+      # drain takes.
+      outcome = Delivery.cut?(delivery) ? ack["cut"].to_s : ""
+      return " (goes in at the running turn's next step)" unless CUT_OUTCOMES.include?(outcome)
+
+      " #{TerminalUI::Formatting.steer_cut_note(outcome.to_sym)}"
     end
 
     # More keys for --format json, with --cut only (the line is unchanged

data/lib/samagotchi/session.rb

@@ -6,7 +6,9 @@ require "securerandom"
 require "time"
 require_relative "atomic_file"
 require_relative "context_note"
+require_relative "last_turn"
 require_relative "llm_context_override"
+require_relative "session_setup"
 require_relative "prompt_note"
 
 require_relative "paths"
@@ -86,14 +88,16 @@ module Samagotchi
     # A `chi scratch` session: deleted when its REPL ends, and by the next
     # sweep (or `chi sessions clean`) when the process died first.
     attr_accessor :scratch
-    # How the last turn ended, for the web's notifications (the hub sends
-    # it in the summary): {"outcome" => "completed"|"failed"|"canceled",
-    # "ended_at" => iso8601, "seconds" => Float, "origin" =>
-    # "client"|"reminder"|"delegate"|"delegate_report"|"context"}; nil
-    # before the first turn. delegate_report: a turn a parent ran for its
-    # delegate children's reports (ChildReports); context: one an attached
-    # context source's change started (Worker).
-    attr_accessor :last_turn
+    # How the last turn ended (LastTurn), for a parent's wait (ReplyWait)
+    # and the web's notifications (the hub sends it in the summary); nil
+    # before the first turn.
+    attr_reader :last_turn
+
+    # @param value [LastTurn, Hash, nil] a file's Hash is read
+    #   (LastTurn.from_file)
+    def last_turn=(value)
+      @last_turn = LastTurn.from_file(value)
+    end
     # The session's own llm_context values (LLMContextOverride: strategy,
     # apply rule, budget), before the model's; nil when it has none.
     # Saved, so a --resume and a respawned worker keep them; a plugin's
@@ -115,13 +119,28 @@ module Samagotchi
       saved.empty? ? nil : saved
     end
 
+    # The session's own thinking level (:off, :low, :medium, :high), before
+    # the process default and the model's (Thinking.resolve); nil when it
+    # has none. Saved, so a --resume, a respawned worker and a continue keep
+    # it; a plugin's fork copies it, a delegate child starts without.
+    attr_reader :thinking
+
+    # @param value [Symbol, String, nil] a value that isn't a level reads
+    #   as nil and is saved back as written, until the session sets its own
+    def thinking=(value)
+      @thinking = Thinking.session_level(value)
+      unread = @thinking.nil? && value.is_a?(String) && !value.strip.casecmp?(Thinking::DEFAULT.to_s)
+      @thinking_unread = unread ? value : nil
+    end
+
+    # The session file's "thinking": the level, else a value it couldn't
+    # read; nil when there is neither.
+    def thinking_file = @thinking&.to_s || @thinking_unread
+
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
-    # left), e.g. "loop-guard"; nil when it ended otherwise. Both strings
-    # and symbols are read (the file's keys are strings).
+    # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by
-      return nil unless @last_turn.is_a?(Hash)
-
-      (@last_turn["stopped_by"] || @last_turn[:stopped_by])&.to_s
+      @last_turn&.stopped_by&.to_s
     end
     # Archived (ArchiveStore): hidden from the lists. Set by .list (with
     # include_archived); not saved in session.json.
@@ -146,7 +165,7 @@ module Samagotchi
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
-                   continues: nil)
+                   continues: nil, thinking: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -168,10 +187,11 @@ module Samagotchi
       @project_root = project_root
       @parent_id = parent_id&.to_s
       @scratch = !!scratch
-      @last_turn = last_turn
+      self.last_turn = last_turn
       @delegate = !!delegate
       @continues = continues&.to_s
       self.llm_context = llm_context
+      self.thinking = thinking
       @archived = false
     end
 
@@ -220,9 +240,10 @@ module Samagotchi
     # Build a new, unsaved session.
     # @param messages [Array<Hash>] a conversation to start from (a fork's
     #   seed); [] by default
+    # @param setup [SessionSetup] the session's own settings (none by default)
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
                          preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
-                         scratch: false, model_typed: nil, delegate: false, llm_context: nil, continues: nil)
+                         scratch: false, model_typed: nil, delegate: false, setup: SessionSetup.new, continues: nil)
       now = Time.now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?
@@ -247,7 +268,8 @@ module Samagotchi
         parent_id: parent_id,
         scratch: scratch,
         delegate: delegate,
-        llm_context: llm_context,
+        llm_context: setup.llm_context,
+        thinking: setup.thinking,
         continues: continues
       )
     end
@@ -281,7 +303,8 @@ module Samagotchi
     # value for a file without it (REQUIRED for the ones it must have).
     # .from_h and #to_h both go by this table; messages and
     # pending_question change key type on the way (symbols in memory,
-    # strings on disk).
+    # strings on disk); last_turn and prompt_notes are value objects in
+    # memory (LastTurn, PromptNote).
     FIELDS = {
       "metadata_version" => 1,
       "id" => REQUIRED,
@@ -307,7 +330,8 @@ module Samagotchi
       "last_turn" => nil,
       "delegate" => false,
       "llm_context" => nil,
-      "continues" => nil
+      "continues" => nil,
+      "thinking" => nil
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -428,7 +452,9 @@ module Samagotchi
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
                 when "llm_context" then llm_context_file
+                when "thinking" then thinking_file
                 when "prompt_notes" then @prompt_notes.map(&:to_file)
+                when "last_turn" then @last_turn&.to_file
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")
@@ -522,11 +548,6 @@ module Samagotchi
       File.join(state_dir, "#{check_id!(session_id)}#{FILE_EXT}")
     end
 
-    # Default sessions directory path.
-    def self.default_sessions_dir
-      default_state_dir
-    end
-
     # XDG-aware sessions directory.
     def self.default_state_dir(env: ENV)
       File.join(Paths.state_home(env: env), STATE_SUBDIR)

data/lib/samagotchi/session_commands.rb

@@ -11,6 +11,7 @@ require_relative "tools/context_read"
 require_relative "tools/peers"
 require_relative "commands/registry"
 require_relative "llm_context_command"
+require_relative "thinking_command"
 
 module Samagotchi
   # The session commands a REPL and a session worker both run: /model,
@@ -29,6 +30,7 @@ module Samagotchi
     CONTEXT_COMMAND = "/context"
     HELP_COMMAND = "/help"
     LLM_CONTEXT_COMMAND = LLMContextCommand::NAME
+    THINKING_COMMAND = ThinkingCommand::NAME
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
     MODELS_PER_HOST = 20
@@ -88,6 +90,8 @@ module Samagotchi
       # Setting it saves the session; it takes effect at the next turn's start.
       registry.register(LLM_CONTEXT_COMMAND, "show or set this session's LLM context strategy, apply rule and budget",
                         id: :llm_context, mid_turn: show_mid_turn(LLM_CONTEXT_COMMAND), match: ->(text) { text.match?(%r{\A/llm-context(?:\s+.*)?\z}) }) { |text| llm_context(text) }
+      registry.register(THINKING_COMMAND, "show or set this session's thinking level (off|low|medium|high|default)",
+                        id: :thinking, mid_turn: show_mid_turn(THINKING_COMMAND), match: ->(text) { text.match?(%r{\A/thinking(?:\s+.*)?\z}) }) { |text| thinking(text) }
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
@@ -102,11 +106,12 @@ module Samagotchi
                                                                         match: ->(text) { text.casecmp?("/detach") })
       # /cut TEXT and /queue TEXT while a turn runs: a delivery the UIs parse
       # themselves (Formatting#steer_choice) before any command check; the
-      # entries exist for Tab completion and /help. /queue is a real
-      # after-the-turn list only in the local REPL (the attached TUI's
-      # worker doesn't skip queued files yet), so it is offered there.
+      # entries exist for Tab completion and /help. The web composer sends
+      # /cut too. /queue is a real after-the-turn list only in the local
+      # REPL (the attached TUI's worker doesn't skip queued files yet), so
+      # it is offered there.
       registry.register("/cut", "cut the running generation and go in now (/cut TEXT)",
-                        local: true, match: ->(text) { text.casecmp?("/cut") || text.match?(%r{\A/cut\s+\S}) })
+                        local: true, uis: %i[repl attached web], match: ->(text) { text.casecmp?("/cut") || text.match?(%r{\A/cut\s+\S}) })
       registry.register("/queue", "run as the next turn after this one (/queue TEXT)",
                         local: true, uis: [:repl], match: ->(text) { text.casecmp?("/queue") || text.match?(%r{\A/queue\s+\S}) })
       registry
@@ -136,6 +141,34 @@ module Samagotchi
       @builtin_registry ||= register_builtins(Commands::Registry.new).freeze
     end
 
+    # The UI-only built-in command +text+ is a line of (/stats, /exit, …), or
+    # nil: neither a worker nor a one-shot run (chi send, chi -p
+    # --non-interactive) runs it, so they refuse it rather than send it to
+    # the model as a prompt. What the UIs run: the line as the entry's match
+    # takes it — bare "exit" too (/exit's match), but not with arguments
+    # ("/exit --delete" is a UI line; "/stats please" is a prompt), as in a
+    # terminal.
+    # @return [Commands::Registry::Entry, nil]
+    def self.ui_only_entry(text)
+      line = text.to_s.strip
+      return nil unless line.start_with?("/", "!") || line.match?(/\Aexit\z/i)
+
+      entry = builtin_registry.lookup_local(line)
+      return nil unless entry
+      return entry if line == entry.name
+
+      line.match?(/\Aexit\z/i) ? entry : nil
+    end
+
+    # Why a UI-only command isn't run by +runner+ ("chi send"): /stats points
+    # at its model-free reader (naming the session +id+ when there is one).
+    # @return [String]
+    def self.ui_only_refusal(name, id, runner:)
+      return "#{name} is a terminal and web command; #{runner} doesn't run it" unless name == "/stats"
+
+      "#{name} is a terminal and web command; use chi sessions stats #{id ? id[0, 8] : "ID"}"
+    end
+
     # The name of this chi's own session command +line+ is (one a worker
     # runs), or nil. A worker that answers such a line unknown_command runs
     # an older chi that doesn't have it yet (/llm-context against 0.39.0):
@@ -175,13 +208,26 @@ module Samagotchi
         notes = []
         notes << entry.source unless entry.source == "core"
         notes << MID_TURN_NOTES[entry.mid_turn_label] if MID_TURN_NOTES[entry.mid_turn_label]
-        notes << (entry.uis ? "#{entry.uis.join(" and ")} only" : "terminal only") if entry.local
+        notes << "#{ui_words(entry.uis)} only" if entry.local
         line = "  #{self.class.display_name(entry).ljust(width)}  #{entry.description}"
         notes.empty? ? line : "#{line}  (#{notes.join("; ")})"
       end
       "commands:\n#{lines.join("\n")}"
     end
 
+    # Where a UI's own entry runs, for /help: both terminals are
+    # "terminal" (also for no uis: every terminal), then "web".
+    # @param uis [Array<Symbol>, nil]
+    # @return [String] "terminal", "repl", "terminal and web" …
+    def ui_words(uis)
+      return "terminal" if uis.nil?
+
+      terminals = uis & %i[repl attached]
+      words = terminals.size == 2 ? ["terminal"] : terminals.map(&:to_s)
+      words << "web" if uis.include?(:web)
+      words.join(" and ")
+    end
+
     # How help and errors name an entry (the shell's "!" is "!<cmd>").
     def self.display_name(entry) = entry.name == SHELL_BANG_PREFIX ? "#{SHELL_BANG_PREFIX}<cmd>" : entry.name
 
@@ -372,14 +418,25 @@ module Samagotchi
     # /llm-context (LLMContextCommand); :llm_context in changed when it set
     # the session's values.
     def llm_context(text)
-      output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_llm_context(session) })
+      output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
                                          .run(text.delete_prefix(LLM_CONTEXT_COMMAND))
       reply(output, changed: changed ? [:llm_context] : [])
     rescue ArgumentError => e
       reply(e.message, status: :error)
     end
 
-    def save_llm_context(session)
+    # /thinking (ThinkingCommand); :thinking in changed when it set the
+    # session's level.
+    def thinking(text)
+      output, changed = ThinkingCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
+                                       .run(text.delete_prefix(THINKING_COMMAND))
+      reply(output, changed: changed ? [:thinking] : [])
+    rescue ArgumentError => e
+      reply(e.message, status: :error)
+    end
+
+    # A session setting changed (/llm-context, /thinking): saved with its model.
+    def save_setup(session)
       @engine.store_model!(session)
       @save.call(session)
     end
@@ -459,7 +516,7 @@ module Samagotchi
 
         key = alias_name.strip.downcase
         warn_prefix = previous ? "warning: overwriting alias '#{key}' (#{previous} -> #{model_name}); " : ""
-        base = persist_default ? "runtime model set to #{model_name}#{model_note} and default updated" : "runtime model set to #{model_name}#{model_note}"
+        base = persist_default ? "runtime model set to #{model_name}#{model_note} and default updated#{thinking_note}" : "runtime model set to #{model_name}#{model_note}#{thinking_note}"
         ["#{warn_prefix}#{base}; alias '#{key}' -> '#{model_name}' persisted", true]
       else
         return ["--default requires a model name: usage /model --default <name> or /model <name> [--default]", false] if arg.empty?
@@ -468,14 +525,14 @@ module Samagotchi
           return ["--default cannot be combined with clear/default/none/off", false] if persist_default
 
           switch_model(@default_model)
-          return ["runtime model reset to #{model_name}#{model_note}#{notes_note}", true]
+          return ["runtime model reset to #{model_name}#{model_note}#{thinking_note}#{notes_note}", true]
         end
 
         switch_model(arg, persist_default: persist_default)
         if persist_default
-          ["runtime model set to #{model_name}#{model_note} and default updated#{notes_note}", true]
+          ["runtime model set to #{model_name}#{model_note} and default updated#{thinking_note}#{notes_note}", true]
         else
-          ["runtime model set to #{model_name}#{model_note}#{notes_note}", true]
+          ["runtime model set to #{model_name}#{model_note}#{thinking_note}#{notes_note}", true]
         end
       end
     end

data/lib/samagotchi/session_inbox.rb

@@ -183,20 +183,29 @@ module Samagotchi
       Dir.glob(File.join(input_dir, "*.json"))
     end
 
-    # @return [Array(String, Hash|nil, Boolean, Array<Hash>, String|nil)] a
-    #   claimed input file's prompt, origin ({client_id:, enqueued_id:},
-    #   nil when it names no sender), whether its turn runs with the raised
-    #   iteration limit (--no-interrupt), its image refs ({file:, name:}),
-    #   and its delivery ("queue" or nil; a file without the key is one an
-    #   older chi wrote, so nil)
+    # A claimed input file as read: its +prompt+, +origin+ ({client_id:,
+    # enqueued_id:}, nil when it names no sender), whether its turn runs
+    # with the raised iteration limit (+no_interrupt+, --no-interrupt), its
+    # +images+ ({file:, name:} refs), and its +delivery+ ("queue" or nil; a
+    # file without the key is one an older chi wrote, so nil).
+    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery) do
+      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil) = super
+    end
+    # A file that doesn't parse, or isn't a JSON object: no prompt.
+    UNREADABLE_INPUT = Input.new(prompt: nil)
+
+    # @return [Input] a claimed input file's contents; UNREADABLE_INPUT for
+    #   one that isn't a JSON object
     def self.read_input(claimed_file)
       data = JSON.parse(File.read(claimed_file).to_s)
+      return UNREADABLE_INPUT unless data.is_a?(Hash)
+
       origin = { client_id: data["client_id"], enqueued_id: data["enqueued_id"] }.compact
       images = Array(data["images"]).select { |image| image.is_a?(Hash) }.map { |image| image.transform_keys(&:to_sym) }
-      [data["prompt"].to_s, origin.empty? ? nil : origin, data["no_interrupt"] == true, images,
-       Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil]
+      Input.new(prompt: data["prompt"].to_s, origin: origin.empty? ? nil : origin, no_interrupt: data["no_interrupt"] == true,
+                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil)
     rescue JSON::ParserError
-      [nil, nil, false, [], nil]
+      UNREADABLE_INPUT
     end
 
     # Whether an unclaimed input file carries images (a mid-turn drain