samagotchi 0.41.0 → 0.43.0

data/lib/samagotchi/self_report.rb

@@ -10,6 +10,8 @@ require_relative "session"
 require_relative "log_path"
 require_relative "model_profile"
 require_relative "model_overlay"
+require_relative "model_notes"
+require_relative "prompt_note"
 require_relative "thinking"
 require_relative "served_model"
 require_relative "host_registry"
@@ -59,6 +61,7 @@ module Samagotchi
         ["log", log_path(env)],
         ["model", model ? model_label(model, default, env) : "(not configured)"],
         ["model key", model ? model_key_for(model, env) : "-"],
+        ["model notes", model ? model_notes_for(model, env) : "-"],
         ["host", model ? host_for(model, env) : "-"],
         ["api key", model ? api_key_for(model, env) : "-"],
         ["loop", model ? loop_for(model, env) : "-"],
@@ -187,6 +190,35 @@ module Samagotchi
       ModelOverlay.key_for(model) || "-"
     end
 
+    # "model_notes_deepseek (system, 612 chars)": the model notes a prompt
+    # of +model+ loads (ModelNotes: matched on its bare id and key, the
+    # session's --mute list left out when chi self runs in one), "none"
+    # without any. Read from the memories dirs now: a session's prompt
+    # takes them at its next build (/stats names the ones it carries).
+    def model_notes_for(model, env)
+      bare = HostRegistry.new(env: env).bare_name(model)
+      notes = ModelNotes.for(name: bare, key: ModelOverlay.key_for(bare), muted: session_muted(env), env: env,
+                             warn: false)
+      text = PromptNote.text(notes.map { |note| PromptNote.from_note(note) })
+      text.empty? ? "none" : text
+    rescue StandardError => e
+      "(unreadable: #{e.message})"
+    end
+
+    # The --mute list of the session chi self runs in (its execute exports
+    # SAMAGOTCHI_PARENT_SESSION); [] outside one.
+    def session_muted(env)
+      id = env[PARENT_SESSION_ENV].to_s
+      return [] if id.empty? || !Session.valid_id?(id)
+
+      state_dir = Session.default_state_dir(env: env)
+      return [] unless Session.exist?(id, state_dir: state_dir)
+
+      MutedMemories.normalize_list(Session.load(id, state_dir: state_dir).muted_memory_names)
+    rescue StandardError
+      []
+    end
+
     def model_name
       ModelProfile.required_model_name
     rescue ArgumentError

data/lib/samagotchi/session.rb

@@ -7,6 +7,7 @@ require "time"
 require_relative "atomic_file"
 require_relative "context_note"
 require_relative "llm_context_override"
+require_relative "prompt_note"
 
 require_relative "paths"
 require_relative "project_scope"
@@ -44,6 +45,17 @@ module Samagotchi
     # from it (--mute): the worker rebuilds the same prompt on a respawn.
     # Names as given; the engine normalizes them.
     attr_accessor :preloaded_memory_names, :muted_memory_names
+    # The model notes the session's system prompt carried at its last build
+    # (Array<PromptNote>: name, scope, chars, digest; ModelNotes), set by the
+    # Engine at each build (a start, a resume's or a woken worker's first
+    # turn, /model) and saved, so what a session ran with can be read later.
+    attr_reader :prompt_notes
+
+    # @param notes [Array<PromptNote, Hash>] a file's hashes are read
+    #   (PromptNote.list)
+    def prompt_notes=(notes)
+      @prompt_notes = PromptNote.list(notes)
+    end
     # The name model_name was typed as when that differs from the resolved
     # ref stored in model_name (an alias: `small` for `gemma-small`), else
     # nil. The models: lookup takes it (HostRegistry#lookup_names).
@@ -118,7 +130,7 @@ module Samagotchi
                    first_preview: "", test_run: false, pending_question: nil,
                    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)
+                   last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [])
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -136,6 +148,7 @@ module Samagotchi
       @used_memory_names = self.class.name_list(used_memory_names)
       @preloaded_memory_names = self.class.name_list(preloaded_memory_names)
       @muted_memory_names = self.class.name_list(muted_memory_names)
+      self.prompt_notes = prompt_notes
       @project_root = project_root
       @parent_id = parent_id&.to_s
       @scratch = !!scratch
@@ -269,6 +282,7 @@ module Samagotchi
       "project_root" => nil,
       "preloaded_memory_names" => [],
       "muted_memory_names" => [],
+      "prompt_notes" => [],
       "parent_id" => nil,
       "scratch" => false,
       "last_turn" => nil,
@@ -393,6 +407,7 @@ module Samagotchi
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
                 when "llm_context" then llm_context_file
+                when "prompt_notes" then @prompt_notes.map(&:to_file)
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")

data/lib/samagotchi/session_commands.rb

@@ -3,6 +3,7 @@
 require_relative "config"
 require_relative "model_profile"
 require_relative "served_model"
+require_relative "prompt_note"
 require_relative "turn_flow"
 require_relative "tools/execute"
 require_relative "tools/builtins"
@@ -110,6 +111,14 @@ module Samagotchi
       @builtin_registry ||= register_builtins(Commands::Registry.new).freeze
     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):
+    # the UIs say so (BridgeClient.stale_worker_message) instead of "not a
+    # session command".
+    # @return [String, nil]
+    def self.builtin_name(line) = builtin_registry.lookup(line)&.name
+
     # @return [String] the model /model clear goes back to
     attr_reader :default_model
 
@@ -362,9 +371,9 @@ module Samagotchi
     def model_command(input)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
-        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}", false] if model_name == @engine.model_ref_for(@default_model)
+        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}#{notes_note}", false] if model_name == @engine.model_ref_for(@default_model)
 
-        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}#{thinking_note}", false]
+        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}#{thinking_note}#{notes_note}", false]
       end
 
       # Parse flags: --default and --alias <name> / --alias=<name> (tolerant order)
@@ -434,14 +443,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}", true]
+          return ["runtime model reset to #{model_name}#{model_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", true]
+          ["runtime model set to #{model_name}#{model_note} and default updated#{notes_note}", true]
         else
-          ["runtime model set to #{model_name}#{model_note}", true]
+          ["runtime model set to #{model_name}#{model_note}#{notes_note}", true]
         end
       end
     end
@@ -482,6 +491,16 @@ module Samagotchi
       ""
     end
 
+    # "; notes: model_notes_deepseek (system, 612 chars)": the model notes
+    # the session's prompt carries (after a switch, the ones the new
+    # model's prompt loads); "" without any.
+    def notes_note
+      text = PromptNote.text(@engine.prompt_notes)
+      text.empty? ? "" : "; notes: #{text}"
+    rescue StandardError
+      ""
+    end
+
     # "; thinking: off (models: qwen)" when the model has a level set.
     def thinking_note
       summary = @engine.thinking_summary

data/lib/samagotchi/session_metrics.rb

@@ -37,6 +37,8 @@ module Samagotchi
     # The most turns (with their tool calls) a live snapshot carries: the
     # unsaved ones of a collector whose saves keep failing stay bounded.
     LIVE_RECORDS_CAP = 20
+    # The most characters of a failed turn's error message its record keeps.
+    FAILURE_MESSAGE_CHARS = 2000
 
     # A generation shorter than this gets no decode speed of its own: one
     # tiny generation would skew the session's average.
@@ -308,7 +310,7 @@ module Samagotchi
       when :turn_canceled
         end_turn(status: "canceled", reason: event[:cancellation_reason], by: event[:cancelled_by])
       when :turn_failed
-        end_turn(status: "failed")
+        end_turn(status: "failed", failure: failure_fields(event))
       end
 
       @mutex.synchronize { @last_activity_at = now.iso8601(3) }
@@ -497,9 +499,10 @@ module Samagotchi
     end
 
     # A canceled turn's record keeps why (+reason+: "user", "ctrl_c", ...)
-    # and who stopped it (+by+: a hook's bundle), so a reloaded web history
-    # can show the cancel line the live one did.
-    def end_turn(status: "completed", reason: nil, by: nil)
+    # and who stopped it (+by+: a hook's bundle), a failed one what its line
+    # says (+failure+, #failure_fields), so a reloaded web history can show
+    # the cancel or failure line the live one did.
+    def end_turn(status: "completed", reason: nil, by: nil, failure: nil)
       @mutex.synchronize do
         if @turn
           # A turn that failed mid-stream never saw its generation end:
@@ -522,6 +525,7 @@ module Samagotchi
           }
           record[:cancellation_reason] = reason.to_s unless reason.nil? || reason.to_s.empty?
           record[:cancelled_by] = by.to_s unless by.nil? || by.to_s.empty?
+          record[:failure] = failure if failure
           record.merge!(turn_token_fields(@turn))
           @turn_records << record
           count_turn(record)
@@ -530,6 +534,19 @@ module Samagotchi
       end
     end
 
+    # What turn_failed's line is made of (format.js failedTurnText): a
+    # provider error's summary, else the message (capped: a server's error
+    # page can be long) and class, and the steps that stayed (kept_steps).
+    def failure_fields(event)
+      summary = event[:summary].to_s
+      return { summary: summary, kept_steps: event[:kept_steps] }.compact unless summary.empty?
+
+      message = event[:message].to_s
+      message = "#{message[0, FAILURE_MESSAGE_CHARS - 1]}…" if message.length > FAILURE_MESSAGE_CHARS
+      { message: message.empty? ? nil : message, error_class: event[:error_class]&.to_s,
+        kept_steps: event[:kept_steps] }.compact
+    end
+
     # The model the server says answered, and the name asked for then (a
     # /model switch makes it stale until the next generation reports).
     def record_served_model(event)

data/lib/samagotchi/system_prompt.rb

@@ -80,13 +80,17 @@ module Samagotchi
       key = [chat, thinking, layers]
       @built ||= {}
       @index_sizes ||= {}
+      @notes_loaded ||= {}
       unless @built.key?(key)
+        @section_notes = nil
         @built[key] = system_prompt_with_index(
           assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat, thinking: thinking, layers: layers
         )
         @index_sizes[key] = @measured_index
+        @notes_loaded[key] = @section_notes || []
       end
       @memory_index = @index_sizes[key]
+      @prompt_notes = @notes_loaded[key]
       @built[key]
     end
 
@@ -98,11 +102,19 @@ module Samagotchi
     # @return [Hash, nil]
     attr_reader :memory_index
 
+    # The model notes the prompt #build returned last carries
+    # (Array<ModelNotes::Note>, [] with none), nil before a build and after
+    # #reset!. Read when the prompt is built, as the section is.
+    # @return [Array<ModelNotes::Note>, nil]
+    attr_reader :prompt_notes
+
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
       @built = nil
       @index_sizes = nil
+      @notes_loaded = nil
+      @prompt_notes = nil
       @stable_lengths = nil
     end
 
@@ -323,6 +335,7 @@ module Samagotchi
     # identity: a heading per scope, each note under its name, the models:
     # line left out. nil without any, so the prompt stays as it was.
     def model_notes_section
+      @section_notes = []
       notes = Array(@model_notes_lookup.call)
       return nil if notes.empty?
 
@@ -330,7 +343,7 @@ module Samagotchi
       notes.group_by(&:scope).map do |scope, list|
         heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
         [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
-      end.join("\n\n")
+      end.join("\n\n").tap { @section_notes = notes }
     rescue StandardError
       nil
     end

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -522,6 +522,9 @@ module Samagotchi
           return
         end
         return @screen.commit(stale_worker("run commands")) if reply.status == 404
+
+        name = older_worker_command(reply, line)
+        return @screen.commit(stale_worker("run #{name}")) if name
         return @screen.commit("could not run the command (#{LATE})") if too_late?(reply)
 
         detail = reply.json&.fetch("detail", nil) || reply.json&.fetch("error", nil)
@@ -828,6 +831,14 @@ module Samagotchi
       # so it shows above what it got.
       def echo_answer(text) = @screen.commit("#{paint(QUESTION_PROMPT, 33)}#{text}")
 
+      # The name of this chi's own command +line+ when the worker answered it
+      # unknown_command (it runs an older chi without it), else nil.
+      def older_worker_command(reply, line)
+        return nil unless reply.status == 400 && reply.json&.fetch("error", nil) == "unknown_command"
+
+        SessionCommands.builtin_name(line)
+      end
+
       def stale_worker(cant)
         BridgeClient.stale_worker_message(@client.session_id, cant: cant)
       end
@@ -1002,6 +1013,7 @@ module Samagotchi
 
         why =
           if reply.status == 404 then stale_worker("run commands")
+          elsif (name = older_worker_command(reply, line)) then stale_worker("run #{name}")
           elsif too_late?(reply) then LATE
           else "the worker answered #{reply.status}"
           end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -6,6 +6,7 @@ require_relative "../image_store"
 require_relative "../turn_note"
 require_relative "../steer"
 require_relative "../memory_bundle/index_size"
+require_relative "../prompt_note"
 
 module Samagotchi
   class TerminalUI
@@ -485,6 +486,9 @@ module Samagotchi
         lines << "prompt profile:   #{snapshot[:profile]} (#{snapshot[:profile_source]})" if snapshot[:profile]
         memory_index = memory_index_text(snapshot[:memory_index])
         lines << "memory index:     #{memory_index}" unless memory_index.empty?
+        # The model notes the session's prompt carried (Engine#prompt_notes).
+        notes = PromptNote.text(snapshot[:prompt_notes])
+        lines << "model notes:      #{notes}" unless notes.empty?
         llm_context = llm_context_stats_text(snapshot[:llm_context])
         lines << "llm context:      #{llm_context}" if llm_context
         if snapshot[:served_model]

data/lib/samagotchi/tool_declarations.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "tools/args"
 require_relative "llm_context_strategy"
+require_relative "tools/memory"
 
 module Samagotchi
   # Tool-declaration constants, protocol constants, and guidance text.
@@ -146,7 +147,7 @@ module Samagotchi
             },
             description: {
               type: "string",
-              description: "Optional one-line description (at most 200 characters) appended to the managed index line; without content, it changes only that line"
+              description: "Optional one-line description (at most #{Tools::MemoryWrite::DESCRIPTION_LIMIT} characters) appended to the managed index line; without content, it changes only that line"
             },
             current_model_only: {
               type: "boolean",

data/lib/samagotchi/turn_flow.rb

@@ -46,11 +46,18 @@ module Samagotchi
     #   (context summarizes the interrupted turn for a "no, <reason>")
     attr_reader :offer
 
+    # How many times the conversation went back to a checkpoint (a failed
+    # or canceled turn's restore, !rollback): a worker compares it across a
+    # turn to tell whether the turn's messages (the delegate reports it
+    # merged) left the conversation.
+    attr_reader :restores
+
     def initialize(engine:)
       @engine = engine
       @checkpoint = nil
       @continue_checkpoint = nil
       @offer = nil
+      @restores = 0
     end
 
     def awaiting_continue? = !@offer.nil?
@@ -198,6 +205,7 @@ module Samagotchi
       restored = Array(checkpoint) + arrived
       restored = TurnNote.replace_trailing(restored, note) if note
       @engine.rollback_to(restored)
+      @restores += 1
     end
 
     def conversation_of(result)

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.41.0"
+  VERSION = "0.43.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -20,6 +20,7 @@ require_relative "../session_metrics"
 require_relative "../session_commands"
 require_relative "../steer"
 require_relative "../host_registry"
+require_relative "../llm_context_override"
 require_relative "../model_catalog"
 require_relative "../model_profile"
 require_relative "../sampling_settings"
@@ -458,7 +459,8 @@ module Samagotchi
       end
 
       # Each model's configured sampling as /model words it ("temperature=0.6
-      # (hosts.work)"), on the models that have some: the picker's tooltip.
+      # (hosts.work)"), on the models that have some: the picker's tooltip;
+      # and each model's LLM context (LLMContextStrategy::Explained#summary).
       # A config that can't be read leaves the list as it is.
       def add_sampling(models, registry)
         return if registry.nil? || models.empty?
@@ -466,14 +468,23 @@ module Samagotchi
         settings = ConfigFile.model_settings
         models.each do |model|
           target = registry.resolve(model[:name])
-          summary = SamplingSettings.summary(target, names: registry.lookup_names(model[:name], target: target),
-                                                     models: settings)
+          names = registry.lookup_names(model[:name], target: target)
+          summary = SamplingSettings.summary(target, names: names, models: settings)
           model[:sampling] = summary if summary
+          add_llm_context(model, target, names, settings)
         end
       rescue StandardError
         nil
       end
 
+      # The LLM context +model+ starts under (the start page's llm ctx chip);
+      # one that can't be read leaves this model without, not the others.
+      def add_llm_context(model, target, names, settings)
+        model[:llm_context] = LLMContextStrategy.explain(target, names: names, models: settings).summary(nil)
+      rescue StandardError
+        nil
+      end
+
       # A session's LLM context strategy, apply rule and budget, each with
       # where it came from (LLMContextStrategy::Explained#summary), as its
       # worker would resolve them; nil when they can't be.
@@ -563,6 +574,12 @@ module Samagotchi
         dir, error = scope_dir(body["dir"])
         return error if error
 
+        # llm_context: the session's own LLM context values before its first
+        # turn (the start page's llm ctx chip; chi --llm-context), read
+        # before anything spawns so a bad one spawns nothing.
+        llm_context, error = request_llm_context(body["llm_context"])
+        return error if error
+
         folder = dir ? { working_directory: dir } : {}
         # model: the model the session starts on (the start page's picker,
         # spelled as GET /api/models lists it); blank means the default.
@@ -573,6 +590,7 @@ module Samagotchi
         # until that turn is saved.
         preview = idle ? body["preview"].to_s.strip : ""
         folder[:title] = preview unless preview.empty?
+        folder[:llm_context] = llm_context if llm_context
         begin
           session = @manager.spawn_session(prompt: idle ? nil : prompt.to_s, state_dir: @state_dir, **folder)
         rescue ModelProfile::MissingModel => e
@@ -588,6 +606,25 @@ module Samagotchi
         json_response(201, session_to_json(session).merge(bridge_port: port))
       end
 
+      # The create request's "llm_context" ({strategy:, apply:, budget:},
+      # each a word as /llm-context takes it, "default" for unset) as an
+      # override: [override, nil] (nil when absent or all default), or
+      # [nil, a 400 response] for anything else.
+      def request_llm_context(raw)
+        return [nil, nil] if raw.nil?
+
+        fields = LLMContextOverride::COMMAND_WORDS.invert
+        unless raw.is_a?(Hash) && raw.all? { |key, word| fields.key?(key) && word.is_a?(String) }
+          return [nil, error_response(400, "invalid_llm_context",
+                                      "llm_context is an object of #{fields.keys.join(", ")} words")]
+        end
+
+        override = LLMContextOverride.update(nil, raw.to_h { |key, word| [fields.fetch(key), word] })
+        [override.empty? ? nil : override, nil]
+      rescue ArgumentError => e
+        [nil, error_response(400, "invalid_llm_context", e.message)]
+      end
+
       def handle_show(req, id)
         # The page's light re-reads: never the whole conversation.
         return handle_cards_read(id) if req.params["cards"] == "1"
@@ -626,6 +663,8 @@ module Samagotchi
         # What the worker's server said it served for that model (after a turn).
         if snapshot
           session_json = session_json.merge(served_model: snapshot["served_model"], served_model_for: snapshot["served_model_for"])
+          # The model notes its prompt carries now (a /model there changes them).
+          session_json = session_json.merge(prompt_notes: snapshot["prompt_notes"]) if snapshot["prompt_notes"].is_a?(Array)
         end
         # The LLM context strategy the next turn runs under (the info bar's
         # chip): the worker's, else worked out here from the session file.
@@ -680,8 +719,9 @@ module Samagotchi
       # history again (nor a render of every earlier answer). Live: the
       # worker's GET tail alone (no session file read); else the file. The
       # session part is what the page reads of it (id, status, used memory
-      # names). ?turn_id=: that turn's answer (a queued turn's page re-reads
-      # after the next one started). ?recent=1 (the page since this
+      # names, the model notes its prompt carried: the first turn's build or
+      # a /model records them). ?turn_id=: that turn's answer (a queued
+      # turn's page re-reads after the next one started). ?recent=1 (the page since this
       # release): the timing's records are the newest turn's (#recent_timing),
       # which the page merges by id; without it, the whole timing as before.
       def handle_tail_read(req, id)
@@ -692,12 +732,14 @@ module Samagotchi
         tail = live_tail(id, turn_id: turn_id)
         state = tail && tail["session_state_snapshot"]
         if state.is_a?(Hash)
-          session_json = { id: id, status: state["status"], used_memory_names: Array(state["used_memory_names"]) }
+          session_json = { id: id, status: state["status"], used_memory_names: Array(state["used_memory_names"]),
+                           prompt_notes: Array(state["prompt_notes"]) }
           messages = last_assistant_for_display([tail["answer"]].compact)
         else
           session = @session_class.load(id, state_dir: default_state_dir)
           state = nil
-          session_json = { id: id, status: displayed_status(session), used_memory_names: Array(session.used_memory_names) }
+          session_json = { id: id, status: displayed_status(session), used_memory_names: Array(session.used_memory_names),
+                           prompt_notes: session.prompt_notes.map(&:to_h) }
           messages = last_assistant_for_display(session.messages, turn_id: turn_id)
         end
         live_metrics = state && state["metrics"]
@@ -839,7 +881,12 @@ module Samagotchi
           when 202
             record_history(body, line) if PromptHistory.shell_line?(line)
             json_response(202, reply.json || { status: "accepted" })
-          when 400 then error_response(400, reply.json&.dig("error") || "unknown_command", reply_detail(reply, "not a session command"))
+          when 400
+            # One of this chi's own commands the worker doesn't know: it runs an older chi.
+            name = reply.json&.dig("error") == "unknown_command" && SessionCommands.builtin_name(line)
+            next error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: "run #{name}")) if name
+
+            error_response(400, reply.json&.dig("error") || "unknown_command", reply_detail(reply, "not a session command"))
           end
         end
       rescue SessionManager::OwnedByTUI => e