samagotchi 0.95.0 → 0.97.0

data/lib/samagotchi/llm/errors.rb

@@ -384,6 +384,24 @@ module Samagotchi
       # Seconds to wait before retrying a CreditsHeld without a Retry-After.
       CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
+      # How much of a server's error message the summary keeps.
+      MESSAGE_LIMIT = 500
+      # The 404 model hint's bounds (the message is the server's): how much
+      # of the message it reads, the longest model id, how many listed ids.
+      HINT_SCAN_CHARS = 64 * 1024
+      HINT_ID_MAX = 200
+      HINT_IDS_MAX = 2000
+      # A typo the hint forgives: at most this many edits, fewer than a
+      # third of the name, in a name at least HINT_FUZZY_MIN long.
+      HINT_MAX_EDITS = 2
+      HINT_FUZZY_MIN = 6
+      # A 404's model it couldn't find: "Model 'X' not found", "model `X`
+      # does not exist", "model X-1 not found" (unquoted, an id-like word,
+      # checked after the match). Bounded quantifiers: a server's long token
+      # can't make the match quadratic (Ruby 3.3 has no regex memoization).
+      MODEL_NOT_FOUND_RE = /model\s+(?:["'`]([^"'`\s]{1,#{HINT_ID_MAX}})["'`]|([^"'`\s]{1,#{HINT_ID_MAX}}))\s+(?:was\s+)?(?:not found|does not exist)/i
+      # The ids a 404 lists after "Available models:".
+      AVAILABLE_MODELS_RE = /available models?:\s*(.+)\z/im
       # The HTTP status an Anthropic error.type stands for, for an error
       # object that carries no numeric code (a Messages stream's error event,
       # an OpenAI error whose code is null or a name).
@@ -426,6 +444,7 @@ module Samagotchi
           else
             OutOfCredits.new(text, **options)
           end
+        when 404 then bad_request(text, status, message, options.merge(hint: model_hint(error_message(body, limit: nil))))
         when 400..499 then bad_request(text, status, message, options)
         when 500..599
           ServerError.new(text, retryable: RETRYABLE_SERVER_STATUSES.include?(status),
@@ -492,7 +511,7 @@ module Samagotchi
       # upstream failure (OpenRouter) often says only "Provider returned
       # error" and puts the upstream's words in error.metadata.raw and its
       # name in metadata.provider_name; both are added when present.
-      def error_message(body)
+      def error_message(body, limit: MESSAGE_LIMIT)
         parsed = parse_json(body.to_s)
         message =
           if parsed.is_a?(Hash)
@@ -502,9 +521,88 @@ module Samagotchi
         message = body.to_s if message.nil? || message.to_s.strip.empty?
         message = message.to_s.strip
         message = with_upstream(message, parsed["error"]["metadata"]) if parsed.is_a?(Hash) && parsed["error"].is_a?(Hash)
-        message.empty? ? "(empty body)" : message[0, 500]
+        return "(empty body)" if message.empty?
+
+        limit ? message[0, limit] : message
+      end
+
+      # "did you mean 'ID'?" for a 404 that names the model it couldn't find
+      # and lists the ones it has (oMLX: "Model 'X' not found. Available
+      # models: a, b, …"): the listed id that is X but for case, the one
+      # whose last segment (after "/" or "--") is X, else the one id a
+      # typo away (#typo_distance, whole or its last segment). Read from
+      # the message past the summary's cut (MESSAGE_LIMIT), within the
+      # HINT_* bounds; nil when there is no list, nothing close or a tie.
+      def model_hint(message)
+        message = message[0, HINT_SCAN_CHARS]
+        match = MODEL_NOT_FOUND_RE.match(message)
+        requested = match && (match[1] || match[2])
+        return nil unless requested && (match[1] || requested.match?(%r{[-/.:_\d]}))
+
+        list = message[AVAILABLE_MODELS_RE, 1]
+        return nil unless list
+
+        ids = list.split(/,\s*|\s+/, HINT_IDS_MAX + 1).first(HINT_IDS_MAX)
+                  .map { |id| id.delete("[]\"'`").sub(/[.;]+\z/, "") }
+                  .reject { |id| id.empty? || id.length > HINT_ID_MAX }.uniq
+        return nil if ids.empty? || ids.include?(requested)
+
+        close = closest_model_id(requested, ids)
+        close && "did you mean '#{close}'?"
       end
 
+      # The id that is +requested+ but for case, or whose last segment is,
+      # else the one id a typo away (#typo_distance); nil on a tie.
+      def closest_model_id(requested, ids)
+        probe = requested.downcase
+        exact = ids.find { |id| id.downcase == probe } || ids.find { |id| last_segment(id) == probe }
+        return exact if exact
+
+        scored = ids.filter_map do |id|
+          distance = [id.downcase, last_segment(id)].uniq.filter_map { |name| typo_distance(probe, name) }.min
+          [distance, id] if distance
+        end
+        return nil if scored.empty?
+
+        best = scored.map(&:first).min
+        closest = scored.select { |distance, _| distance == best }
+        closest.size == 1 ? closest.first.last : nil
+      end
+
+      # The edit distance of +a+ and +b+ when it is a typo's: at most
+      # HINT_MAX_EDITS and under a third of the shorter one, which has
+      # HINT_FUZZY_MIN characters or more; else nil. A banded Levenshtein:
+      # linear in the length.
+      def typo_distance(a, b)
+        shorter = [a.length, b.length].min
+        return nil if shorter < HINT_FUZZY_MIN || (a.length - b.length).abs > HINT_MAX_EDITS
+
+        distance = banded_distance(a, b, HINT_MAX_EDITS)
+        distance if distance && distance * 3 < shorter
+      end
+
+      # Levenshtein distance of +a+ and +b+ if at most +limit+, else nil;
+      # only cells within +limit+ of the diagonal are computed.
+      def banded_distance(a, b, limit)
+        far = limit + 1
+        prev = Hash.new(far)
+        (0..[limit, b.length].min).each { |j| prev[j] = j }
+        a.each_char.with_index(1) do |ca, i|
+          cur = Hash.new(far)
+          cur[0] = i if i <= limit
+          ([i - limit, 1].max..[i + limit, b.length].min).each do |j|
+            cost = ca == b[j - 1] ? 0 : 1
+            cur[j] = [prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost, far].min
+          end
+          return nil if cur.empty? || cur.values.min > limit
+
+          prev = cur
+        end
+        prev[b.length] <= limit ? prev[b.length] : nil
+      end
+
+      def last_segment(id) = id.downcase.split(%r{/|--}).last
+
       # error.metadata.reason of a JSON error body (OpenRouter), or nil.
       def error_reason(body)
         parsed = parse_json(body.to_s)

data/lib/samagotchi/memory_bundle/profile.rb

@@ -80,7 +80,7 @@ module Samagotchi
       # "Shipped notes").
       def kept_own_line(member, file)
         "#{member}: kept your own #{file} (not the bundle's; to take the bundle's, remove yours with " \
-          "memory_write remove: true, then chi bundle install #{member})"
+          "chi memory rm #{file.delete_suffix(".md")} --scope system, then chi bundle install #{member})"
       end
 
       # The one rule.
@@ -121,19 +121,29 @@ module Samagotchi
         member_dir = File.join(shipped_dir, member)
         failure = Manifest.requires_chi_failure(Manifest.read(dir: member_dir).requires_chi, chi_version)
         return result.skipped[member] = failure if failure
-        return result.installed << member if dry_run
 
+        # A dry run runs the Installer's too, which writes nothing, so it
+        # names the files the real run would keep as the user's own.
         installer = Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true,
-                                  shipped_dir: shipped_dir)
+                                  shipped_dir: shipped_dir, dry_run: dry_run)
         installer.run
         result.installed << member
-        kept = installer.results.select { |_, entry| entry[:status] == "skipped" && entry[:reason] == "already exists" }.keys
+        kept = installer.results.select { |_, entry| kept_own?(entry) }.keys
         result.kept_own[member] = kept.sort unless kept.empty?
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip
       end
       private_class_method :install_member
 
+      # An Installer result for a file the user already had, with other
+      # bytes: skipped ("already exists"), or a dry run's would_skip. One
+      # with the bundle's bytes ("already up to date") isn't named: nothing
+      # of the bundle's is missing (it stays the user's all the same).
+      def kept_own?(entry)
+        entry[:status] == "would_skip" || (entry[:status] == "skipped" && entry[:reason] == "already exists")
+      end
+      private_class_method :kept_own?
+
       # Uninstalls each recorded member still installed, then the meta. A
       # member that won't go (an edited .md file, without +force+) is
       # reported and the rest carry on; the meta then stays, still

data/lib/samagotchi/memory_command.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "memory_paths"
+require_relative "tools/memory"
+require_relative "memory_bundle/index_updater"
+require_relative "memory_bundle/provenance"
+
+module Samagotchi
+  # `chi memory`: the user's side of the memories (docs/memory.md). ls lists
+  # both scopes' entries from their index.md lines and files, as memory_read
+  # and the prompt see them; rm removes one as memory_write remove: true does
+  # (Tools::MemoryWrite.remove: the file and its model overlays into the
+  # bundle trash, the index line dropped, a bundle's memory refused).
+  class MemoryCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi memory <ls|rm> [options]
+        ls [--scope project|system] [--format text|json]   the memories: both scopes (this folder's project
+             first), or one; each with its size, date, the bundle it came from and its index description
+        rm NAME [--scope project|system]   remove a memory: its file and its model overlays (NAME.<key>.md)
+             move to the bundle trash (chi bundle trash lists and empties it) and its index line is dropped.
+             Without --scope NAME must be in one scope only. A bundle's memory is refused: chi bundle
+             uninstall removes it. NAME.<key> removes one model overlay alone.
+    TEXT
+
+    SUBCOMMANDS = %w[ls rm].freeze
+    SCOPES = Tools::VALID_SCOPES
+    # The description column's width in ls's text form (json has it all).
+    DESCRIPTION_WIDTH = 60
+    # ls's size column, right-aligned.
+    SIZE_COLUMN = 2
+
+    FLAGS = {
+      "ls" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--scope"
+        f.value "--format"
+      end,
+      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" }
+    }.freeze
+
+    # One memory of a scope. +date+ is the index line's (the file's mtime
+    # when it has none); +source+ the bundle that owns it; +overlays+ the
+    # model keys of its overlays; +indexed+ / +file+: whether it has an
+    # index line / a file (a line whose file was deleted by hand has none).
+    Entry = Data.define(:name, :scope, :path, :bytes, :date, :source, :description, :overlays, :indexed, :file) do
+      def to_h = super.transform_keys(&:to_s)
+    end
+
+    # A managed index line: "- **name** · scope · date · size[ · from b][ — desc]"
+    # or a legacy "- **name**: desc" (MemoryWrite.managed_pattern).
+    LINE = /^- \*\*([^*\n]+)\*\*[ \t]*(?:[·•][^\n]*|:[^\n]*)?$/
+
+    # @param argv [Array<String>] the arguments after "memory"
+    # The project scope is the cwd's project, as for the memory tools.
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return CLI::Exit::OK
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      scope = parsed.options[:scope]
+      return usage_error("unknown scope #{scope.inspect}: use --scope project|system") if scope && !SCOPES.include?(scope)
+
+      send(:"run_#{@sub}", parsed.options, parsed.args)
+    end
+
+    # The memories of +scope+ (project first, then system, when nil), by
+    # name within a scope.
+    # @return [Array<Entry>]
+    def self.entries(scope = nil)
+      owners = MemoryBundle::Provenance.each_installed.reject { |_, bundle| bundle.error? }
+      (scope ? [scope] : SCOPES).flat_map { |s| scope_entries(s, owners) }
+    end
+
+    def self.scope_entries(scope, owners)
+      dir = MemoryPaths.scope_dir(scope)
+      return [] unless File.directory?(dir)
+
+      index_path = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
+      index_text = File.file?(index_path) ? File.read(index_path, encoding: "UTF-8") : ""
+      # name => its line; the first one when a name has two. A name rm
+      # would refuse (a path: "../x") isn't listed.
+      lines = {}
+      index_text.each_line do |l|
+        (m = l.chomp.match(LINE)) or next
+        lines[m[1]] ||= m[0] unless Tools::MemoryRead.invalid_name?(m[1])
+      end
+      stems = Dir.children(dir).filter_map { |f| f.delete_suffix(".md") if f.end_with?(".md") && File.file?(File.join(dir, f)) }.to_set
+      overlays = overlays_by_base(stems, lines)
+      overlay_stems = overlays.values.flatten(1).to_set { |_key, stem| stem }
+      names = (lines.keys + stems.to_a).uniq - [Tools::MEMORY_INDEX]
+      names.filter_map do |name|
+        next if overlay_stems.include?(name)
+
+        path = File.join(dir, "#{name}.md")
+        line = lines[name]
+        file = stems.include?(name)
+        # A bold line of prose ("- **Important**") isn't a memory: only a
+        # managed line ("· …") counts without a file.
+        next unless file || line&.include?(" · ")
+
+        entry(name, scope, path, line, file, overlays.fetch(name, []).map(&:first), owners)
+      end.sort_by(&:name)
+    end
+
+    # base name => [[key, stem]...] of its model overlays, in one pass over
+    # the files (+stems+, a Set): <base>.<key>.md with a key ModelOverlay
+    # makes, whose base is a file and whose stem has no index line of its
+    # own (MemoryWrite.overlay_files' rule, for every base at once).
+    def self.overlays_by_base(stems, lines)
+      stems.sort.each_with_object({}) do |stem, by_base|
+        base, dot, key = stem.rpartition(".")
+        next if dot.empty? || base.empty? || !key.match?(/\A[a-z0-9-]+\z/)
+        next unless stems.include?(base) && !lines.key?(stem)
+
+        (by_base[base] ||= []) << [key, stem]
+      end
+    end
+
+    def self.entry(name, scope, path, line, file, overlay_keys, owners)
+      source = line && MemoryBundle::IndexUpdater.extract_source(line)
+      source ||= owners.find { |_, bundle| bundle.effective_scope == scope && bundle.owns?("#{name}.md") }&.first
+      Entry.new(
+        name: name, scope: scope, path: path, bytes: file ? File.size(path) : nil,
+        date: line.to_s[/ · (\d{4}-\d{2}-\d{2})\b/, 1] || (file ? File.mtime(path).strftime("%Y-%m-%d") : nil),
+        source: source, description: line && line.include?(" · ") ? line.split(" — ", 2)[1]&.strip : legacy(line),
+        overlays: overlay_keys,
+        indexed: !line.nil?, file: file
+      )
+    end
+
+    # A legacy "- **name**: desc" line's description.
+    def self.legacy(line) = line&.split("**:", 2)&.[](1)&.strip&.then { |d| d.empty? ? nil : d }
+    private_class_method :scope_entries, :overlays_by_base, :entry, :legacy
+
+    private
+
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi memory #{@sub}" : "chi memory"
+    def usage_on_error = nil
+
+    def run_ls(options, args)
+      return usage_error("ls takes no NAME (unexpected #{args.first})") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      rows = self.class.entries(options[:scope])
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(rows.map(&:to_h)))
+      elsif rows.empty?
+        @stdout.puts("no memories#{" in #{options[:scope]} scope" if options[:scope]}")
+      else
+        print_rows(rows)
+      end
+      CLI::Exit::OK
+    end
+
+    def print_rows(rows)
+      table = rows.map do |r|
+        notes = []
+        notes << "overlays: #{r.overlays.join(", ")}" unless r.overlays.empty?
+        notes << "no file" unless r.file
+        notes << "no index line" unless r.indexed
+        [r.scope, r.name, r.bytes.to_s, r.date.to_s, r.source ? "from #{r.source}" : "",
+         [clip(r.description.to_s), *notes.map { |n| "[#{n}]" }].reject(&:empty?).join(" ")]
+      end
+      widths = table.transpose.map { |column| column.map(&:length).max }
+      # A column no row fills (no memory from a bundle) takes no room.
+      table.each do |line|
+        cells = line.each_with_index.map { |cell, i| i == SIZE_COLUMN ? cell.rjust(widths[i]) : cell.ljust(widths[i]) }
+        @stdout.puts(cells.reject.with_index { |_, i| widths[i].zero? }.join("  ").rstrip)
+      end
+    end
+
+    def clip(text) = text.length > DESCRIPTION_WIDTH ? "#{text[0, DESCRIPTION_WIDTH - 1]}…" : text
+
+    def run_rm(options, args)
+      name = args.shift
+      return usage_error("give the memory's NAME") unless name
+      return usage_error("rm takes one NAME (unexpected #{args.first})") unless args.empty?
+
+      scope = options[:scope] || only_scope(name)
+      return scope if scope.is_a?(Integer)
+
+      result = Tools::MemoryWrite.call(nil, path: name, scope: scope, remove: true)
+      if result.start_with?("Error: ")
+        error_line("#{command_name}: #{result.delete_prefix("Error: ")}")
+        return CLI::Exit::FAILED
+      end
+
+      @stdout.puts(result)
+      CLI::Exit::OK
+    end
+
+    # The one scope +name+ is in (a file or an index line), else the exit
+    # status: a usage error when it is in both, a failure in neither (an
+    # invalid name goes on to remove's own error).
+    # @return [String, Integer]
+    def only_scope(name)
+      return "project" if Tools::MemoryRead.invalid_name?(name) || name == Tools::MEMORY_INDEX
+
+      found = SCOPES.select { |scope| present?(name, scope) }
+      case found.size
+      when 1 then found.first
+      when 0
+        error_line("#{command_name}: no memory '#{name}' in project or system scope")
+        CLI::Exit::FAILED
+      else
+        usage_error("#{name} is in both scopes: chi memory rm #{name} --scope project, or --scope system")
+      end
+    end
+
+    def present?(name, scope)
+      dir = MemoryPaths.scope_dir(scope)
+      index = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
+      File.file?(File.join(dir, "#{name}.md")) ||
+        (File.file?(index) && File.read(index, encoding: "UTF-8").match?(Tools::MemoryWrite.managed_pattern(name)))
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -21,8 +21,12 @@ module Samagotchi
       # The first chi release with each call a plugin may make (from git:
       # the first release tag holding it), for `chi bundle check`'s
       # requires-chi-floor: a bundle whose requires_chi admits an older chi.
-      # A call not listed gets no floor check: it came before the first tag
-      # (v0.2.0), or isn't listed yet. Keys have no "?" (API_CALL drops it).
+      # A call not listed gets no floor check: it is in the first tag (v0.2.0:
+      # chi.command/tool/on/service/init, ctx.settings, ctx.sessions,
+      # ctx.ask_model, ctx.notify, ctx.card, ctx.messages…). A member of
+      # one (ctx.sessions.children) is listed when it came later. Keys have
+      # no "?" (API_CALL drops it). A keyword added later (ctx.ask_model's
+      # model: in 0.80.0, ctx.sessions.send's delivery: in 0.64.0) has none.
       SINCE = {
         "ctx.steer" => "0.3.0", "ctx.stop_turn" => "0.3.0", "ctx.stop_generation" => "0.6.0",
         "Samagotchi::AtomicFile" => "0.8.0", "ctx.model" => "0.17.0", "ctx.model_key" => "0.17.0",
@@ -31,7 +35,7 @@ module Samagotchi
         "ctx.prompt_files" => "0.60.0", "chi.annotation" => "0.66.0", "chi.toolkit" => "0.66.0",
         "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
         "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
-        "ctx.cost" => "0.83.0"
+        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0"
       }.freeze
 
       # @param bundle [String]

data/lib/samagotchi/plugin/sessions.rb

@@ -53,7 +53,7 @@ module Samagotchi
 
         child = SessionManager.spawn_session(
           prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
-          parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, title: title,
+          parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, preview: title,
           images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir,
           setup: @host.setup&.call || SessionSetup.new
         )
@@ -105,7 +105,8 @@ module Samagotchi
       # Session +id+ now: from its worker when one runs (with a running turn
       # so far), else as saved.
       # @return [Hash] {id:, title:, status:, parent_id:, running:, messages:}
-      #   (messages without the system prompt, symbol keys)
+      #   (title: its own name, /title, else its first message's preview;
+      #   messages without the system prompt, symbol keys)
       # @raise [Error] no such session
       def read(id)
         state_dir = self.state_dir
@@ -120,7 +121,7 @@ module Samagotchi
             messages += Bridge::TurnAccumulator.messages_of(deep_symbolize(turn))
           end
         end
-        { id: sid, title: session.first_preview.to_s, status: session.status.to_s, parent_id: session.parent_id,
+        { id: sid, title: session.display_title, status: session.status.to_s, parent_id: session.parent_id,
           running: running, messages: without_system_head(messages) }
       end
 

data/lib/samagotchi/send_command.rb

@@ -416,7 +416,7 @@ module Samagotchi
       # says whether it ran as one.
       through_worker = images || command_like?(prompt)
       begin
-        start = through_worker ? { prompt: nil, title: prompt } : { prompt: prompt }
+        start = through_worker ? { prompt: nil, preview: prompt } : { prompt: prompt }
         session = if options[:continues]
                     SessionManager.continue_session(options[:continues], **start, model: options[:model],
                                                                              state_dir: @state_dir)
@@ -685,13 +685,12 @@ module Samagotchi
         return true
       end
 
-      ack = result.ack
       @delivered = result
       # What the worker applied, for --format json: its ack's delivery
       # (next_step for an idle session) and a cut's outcome.
-      @sent_delivery = ack["delivery"] || delivery
-      @sent_cut = ack["cut"]
-      @info.puts("#{short}  sent#{with_images}#{delivery_note(ack, delivery: delivery, running: running, owner: owner)}")
+      @sent_delivery = result.delivery || delivery
+      @sent_cut = result.cut
+      @info.puts("#{short}  sent#{with_images}#{delivery_note(result, delivery: delivery, running: running, owner: owner)}")
       true
     rescue SessionManager::OwnedByTUI
       @info.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
@@ -706,11 +705,12 @@ module Samagotchi
     # the outcome from the ack (now, waits, off); a --queue one runs after
     # the turn (or now, when the turn ended before it went in); images keep
     # their own wording; an idle session's turn simply runs.
-    # @param ack [Hash] the Bridge's 202 body ({} for the input file)
+    # @param result [SessionManager::DeliverResult] the accepted delivery
+    #   (its ack is {} for the input file)
     # @return [String] "" or " (...)"
-    def delivery_note(ack, delivery:, running:, owner:)
+    def delivery_note(result, delivery:, running:, owner:)
       return " (started its worker)" if owner.nil?
-      return queue_note(ack, running: running) if Delivery.queue?(delivery)
+      return queue_note(result, running: running) if Delivery.queue?(delivery)
       return "" unless running
 
       # A busy worker runs a message with images as its own next turn
@@ -720,18 +720,18 @@ module Samagotchi
       # 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 : ""
+      outcome = Delivery.cut?(delivery) ? result.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, ack["cut_after"])}"
+      " #{TerminalUI::Formatting.steer_cut_note(outcome.to_sym, result.cut_after)}"
     end
 
     # A --queue, worded from the Bridge's ack: queue when a turn ran as it
     # went in (one another client started too), next_step when none did
     # (it runs now). The input file (no Bridge) carries the queue to
     # whichever turn runs: worded from the session as chi read it.
-    def queue_note(ack, running:)
-      queued = ack.key?("delivery") ? ack["delivery"] == Delivery::QUEUE : running
+    def queue_note(result, running:)
+      queued = result.delivery.nil? ? running : result.delivery == Delivery::QUEUE
       return " (queued: runs after the current turn)" if queued
 
       running ? " (the running turn had ended: it runs now)" : " (nothing running: it runs now)"

data/lib/samagotchi/session.rb

@@ -56,6 +56,10 @@ 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 name the user gave the session (/title, TitleCommand), else nil:
+    # every list, card and tab shows it in place of #first_preview (see
+    # #display_title). A continue's new link inherits it.
+    attr_accessor :title
     # The files chi --append-system-prompt put into the session's system
     # prompt (absolute paths; config.yml's append_system_prompt: entries
     # aren't stored): kept on respawns, copied by a fork and a continue
@@ -276,7 +280,7 @@ module Samagotchi
                    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, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, bundle_settings: {}, interrupted_turn: nil, parent_answers: nil)
+                   toolkit: nil, bundle_settings: {}, interrupted_turn: nil, parent_answers: nil, title: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -289,6 +293,7 @@ module Samagotchi
       @status = status
       @last_prompt = last_prompt
       @first_preview = first_preview
+      @title = title
       @test_run = !!test_run
       self.pending_question = pending_question
       @used_memory_names = self.class.name_list(used_memory_names)
@@ -455,6 +460,7 @@ module Samagotchi
       "status" => STATUS_IDLE,
       "last_prompt" => "",
       "first_preview" => "",
+      "title" => nil,
       "test_run" => false,
       "pending_question" => nil,
       "used_memory_names" => [],
@@ -719,6 +725,12 @@ module Samagotchi
       File.join(Paths.state_home(env: env), STATE_SUBDIR)
     end
 
+    # What names the session: its #title when it has one, else its
+    # #first_preview.
+    def display_title
+      title.to_s.strip.empty? ? first_preview.to_s : title
+    end
+
     # Derive and cache the first user-message preview in the session record.
     # Returns true if the cached value was set or updated.
     # A session with only context notes so far previews by its first note

data/lib/samagotchi/session_commands.rb

@@ -14,6 +14,7 @@ require_relative "llm_context_command"
 require_relative "thinking_command"
 require_relative "toolkit_command"
 require_relative "parent_answers_command"
+require_relative "title_command"
 require_relative "reasoning_history_command"
 require_relative "guardrails/parent_policy"
 
@@ -37,6 +38,7 @@ module Samagotchi
     THINKING_COMMAND = ThinkingCommand::NAME
     TOOLKIT_COMMAND = ToolkitCommand::NAME
     PARENT_ANSWERS_COMMAND = ParentAnswersCommand::NAME
+    TITLE_COMMAND = TitleCommand::NAME
     REASONING_HISTORY_COMMAND = ReasoningHistoryCommand::NAME
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
@@ -112,6 +114,9 @@ module Samagotchi
                                                 "never looser than config.yml's)",
                         id: :parent_answers, mid_turn: show_mid_turn(PARENT_ANSWERS_COMMAND),
                         match: ->(text) { text.match?(%r{\A/parent-answers(?:\s+.*)?\z}) }) { |text| parent_answers(text) }
+      # Only a name: renaming a running session doesn't wait for its turn.
+      registry.register(TITLE_COMMAND, "show or set this session's title (--clear: back to its first message)",
+                        id: :title, anytime: true, match: ->(text) { text.match?(%r{\A/title(?:\s+.*)?\z}) }) { |text| title(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)
@@ -522,6 +527,14 @@ module Samagotchi
       reply(output, status: status, changed: changed ? [:parent_answers] : [])
     end
 
+    # /title (TitleCommand); :title in changed when it named the session or
+    # cleared its name. A plain save: no setting moved, and it may run on
+    # an anytime thread beside a turn.
+    def title(text)
+      output, changed, status = TitleCommand.new(engine: @engine, save: @save).run(text.delete_prefix(TITLE_COMMAND))
+      reply(output, status: status, changed: changed ? [:title] : [])
+    end
+
     # A session setting changed (/llm-context, /thinking, /reasoning-history):
     # saved with its model.
     def save_setup(session)